Charcoal Project Boilerplate

⚠️ This skeleton is built for locomotivemtl/charcoal-* and is deprecated in favour of charcoal/boilerplate.

The goal of this project is to provide a fully working "boilerplate" (empty skeleton project) using the Charcoal framework.

It can also optionally set up the Locomotive Boilerplate for the frontend.

Table of Content

• How to Install
  • 1. Installing boilerplate
  • 2. Test your installation
  • 3. Set up a database storage
  • 4. Set the project name
  • 5. Set up charcoal-admin
  • 6. (Optional) Install locomotive-boilerplate
• Going further
  • More config customizations
  • Creating a custom template
  • Using objects
  • Customizing the backend
• Dependencies and requirements
  • The charcoal modules
    • Status matrix
• What's inside this Boilerplate
• Development
  • Development dependencies
  • Continuous Integration
  • Coding Style
  • Authors

Intended scope

Although it is fully ready to use, this boilerplate is still incomplete. It does not yet showcase all of the Charcoal features and therefore require a lot of manual tinkering for options.

Here is a short "mission statement" of what is expected to be accomplished with this project:

• A fully automated setup process.
  • Optionally install locomotive-boilerplate for the frontend.
• Translation (l10n) fully working with charcoal-translator.
  • Default data also provided in english and french.
  • ...and spanish and more...
• A working "backend" with charcoal-admin.
  • User set up automatically.
  • With a default configuration that allows to manage CMS objects (sections, news, events, blogs, locations, etc.)
  • Permission system working and enabled.
  • Notification system working and enabled.
  • Revisioning system working and enabled.
  • Media library working and enabled.
  • Built-in help (doc) system working and enabled.
• A few default, common templates (mustache) built-in.
  • Home page, with a few options and widgets (like carousel) or similar.
  • News list / news details, with attachment support.
  • Calendar (event list) with ajax options / event details, with attachment support.
  • Blog / article details, with attachment support and options to enable comments, and ajax actions
  • Contact, with a contact form that saves to a database and send a confirmation email depending to category options, with ajax actions.
  • Map, with locations by categories.
• Metadata 100% fully working on every pages and for every objects.
  • Use objects' metadata information, which all are editable in charcoal-admin.
• Provide an optimized set of SEO features.
• Search enabled
  • Results returned for all types of cms objects (sections, news, events, blogs, locations, etc.)
  • Used keywords, which all are editable in charcoal-admin.
  • Also search in attachments.
  • Auto-complete enabled and working.
• 100% tested with PHPUnit.

How to Install

To start a Charcoal project with this Boilerplate, simply:

1. Installing boilerplate

Charcoal uses the Composer create-project command to install the boilerplate:

★ composer create-project --prefer-dist locomotivemtl/charcoal-project-boilerplate acme

Replace "acme" with the desired directory name for your new project.

About the Document Root

👉 The project should not be cloned directly in a web-accessible directory. The web server should be configured to serve the www/ folder directly (or through a symlink). The other folders (vendor/, src/, templates/, metadata/, config/, etc.) should therefore not be available from the web server (kept outside the document root).

2. Test your installation

A quick server can be started using the PHP builtin server:

★ cd www
★ php -S localhost:8080

Point your browser to http://localhost:8080/ and you should see the boilerplate's default home page.

How to change the default page and add routes/templates is explained later in this README.

Hint: the recommended way is from the admin, by adding pages (sections).

3. Set up a database storage

The next step requires a custom configuration file. It is recommended to use config/config.local.json and making sure it is not committed to source control:

★ cp config/config.sample.json config/config.local.json

Then edit the config/config.local.json file with this information.

If your project does not require any database storage, use a database in memory such as SQLite by adding the following to the config/config.local.json file:

{
    "databases": {
        "default": {
            "type": "sqlite",
            "database": ":memory:"
        }
    },
    "default_database": "default"
}

If your project uses MySQL, create an empty database and ensure a SQL user has the proper permissions for this database. Then add the following to the config/config.local.json file:

{
    "databases": {
        "default": {
            "type": "mysql",
            "hostname": "127.0.0.1",
            "database": "foobar",
            "username": "foo_bar",
            "password": "F00$BâR123"
        }
    },
    "default_database": "default"
}

4. Set the project name

By default, the project is named "Acme" and namespaced under App and is autoloaded by Composer using the PSR-4 autoloading standard.

There are a few occurrences of "Acme" in the boilerplate:

• config/admin.json: See admin.title.
• config/config.json: See project_name and cache.prefix.

You should also change the information of the Composer package:

• composer.json: See name.

5. Set up charcoal-admin

A quick-and-dirty script is provided to install charcoal-admin automatically:

★ sh ./build/scripts/install-charcoal-admin.sh

Point your browser to http://localhost:8080/admin and you should see the Charcoal's admin login screen.

The next step to customize the backend is to configure the main menu, as well as the various admin options. See the config/admin.json file for details.

Refer to the charcoal-admin help for more information.

6. (Optional) Install locomotive-boilerplate)

Another quick-and-dirty script is provided to install the locomotive frontend, from its github repository.

★ sh ./build/scripts/install-locomotive-boilerplate.sh

For more information about the locomotive-boilerplate frontend module: visit https://github.com/locomotivemtl/locomotive-boilerplate

Dependencies and Requirements

• PHP 7.4+
  • ext-json
  • ext-pdo
  • ext-spl
  • ext-mbstring

External libraries

Most Charcoal features are built on top of proven, open-source technologies:

• Composer (Deployment and auto-loading)
• Slim (PSR-7 App Framework)
• FastRoute (Router)
• Pimple (DI Container, from symfony)
• Mustache (Templating Engine)
  • Optionally supports Twig, from symfony
• PDO / MySQL (Database Storage)
• Stash (PSR-6 Cache)
• CLImate (Terminal Utility, from the php league)
• Flysystem (File system abstraction, from the php league)
• Symfony Translation (Localization Tools)
• Laminas ACL (Permissions Management)
• PHPmailer (Email Transport)
• Monolog (PSR-3 Logger)
• PHPUnit (Unit Testing)
• APIGen (API Documentation)
• PHP Code Sniffer (Coding Standards)
• jQuery (Javascript Framework)
• Bootstrap (CSS Framework)
• TinyMCE (HTML Editor)
• elFinder (File Manager)
• Github (Source control)
• Travis (Continuous Integration)

The Charcoal modules

• charcoal-admin
  • The backend, or control panel.
• charcoal-app
  • App components based on Slim.
• charcoal-attachment
  • Additional attachments to content objects.
• charcoal-cms
  • CMS objects (Section, News, Events, etc.)
• charcoal-config
  • Base configuration system.
• charcoal-core
  • Core objects, Model, Source.
• charcoal-email
  • Email utilities, based on phpmailer.
• charcoal-factory
  • Dynamic objects creation.
• charcoal-image
  • Image manipulation and effects.
• charcoal-object
  • Object definition (Content and UserData; based on Model), behaviors and tools.
• charcoal-property
  • Metadata's properties.
• charcoal-translator
  • Translation utilities, based on Symfony.
• charcoal-ui
  • Ui objects (Form, Menu, Dashboard, Layout, etc.)
• charcoal-user
  • User definition, authentication and authorization (based on Laminas ACL).
• charcoal-validator
  • Data validation.
• charcoal-view
  • View renderer. (mustache, twig, etc.)

Status matrix

Module	Version	Travis	Scrutinizer	Insights	Coveralls	PHPDoc	ApiGen
admin						PHPDoc	ApiGen
app						PHPDoc	ApiGen
attachment						PHPDoc	ApiGen
cms						PHPDoc	ApiGen
config						PHPDoc	ApiGen
core						PHPDoc	ApiGen
email						PHPDoc	ApiGen
factory						PHPDoc	ApiGen
image						PHPDoc	ApiGen
object						PHPDoc	ApiGen
presenter				-		PHPDoc	ApiGen
property						PHPDoc	ApiGen
queue				-		PHPDoc	ApiGen
translator						PHPDoc	ApiGen
ui						PHPDoc	ApiGen
user						PHPDoc	ApiGen
validator						PHPDoc	ApiGen
view						PHPDoc	ApiGen

What's inside this Boilerplate?

Like all Charcoal projects / modules, the main components are:

• Autoloader
  • Provided by Composer.
• Config
  • As JSON or PHP files in the config/ directory.
  • Use locomotivemtl/charcoal-config
• Front Controller
  • See www/.htaccess and www/index.php for details.
  • Route dispatcher
    • See config/routes.json for route configuration.
• Script Controller (Charoal Binary)
  • Installed from charcoal-app as vendor/bin/charcoal.
  • Many useful scripts are provided with the charcoal-admin module.
• PHP scripts
  • PSR-1, PSR2 and PSR-4 compliant scripts are located in src/
  • There are typically 3 types of controllers:
    • Templates
    • Actions
    • Scripts
  • ... 2 types of object
    • Objects based on Content
    • Objects based on UserData
  • ... and all other types of scripts (services, helpers, configs, factories, etc.)
• Assets
  • Assets are files required to be on the webserver root
  • Scripts, in src/scripts/ and compiled in www/assets/scripts/
  • Styles , with Sass in src/styles/ and compiled CSS in www/assets/styles/
  • Images, in www/assets/images/

Development

To install the development environment:

★ composer install --prefer-source

To run the scripts (phplint, phpcs and phpunit):

★ composer test

Development dependencies

• phpunit/phpunit
• squizlabs/php_codesniffer
• satooshi/php-coveralls

Continuous Integration

Service	Badge	Description
Travis		Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer		Code quality checker. Also validates API documentation quality.
Coveralls		Unit Tests code coverage.
Sensiolabs		Another code quality checker, focused on PHP.

Coding Style

The charcoal-project-boilerplate module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• Read the phpcs.xml file for all the details on code style.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Authors

• Locomotive, a Montreal Web agency