locomotivemtl/charcoal-project-boilerplate

A Charcoal Project Boilerplate

Maintainers

Details

github.com/locomotivemtl/charcoal-project-boilerplate

Homepage

Source

Issues

Installs: 446

Dependents: 0

Suggesters: 0

Security: 0

Stars: 26

Watchers: 15

Forks: 3

Open Issues: 2

Type:project

0.6.2 2022-09-16 15:33 UTC

Requires

Requires (Dev)

MIT a1efbf6286f4022573efba69ba228bb971187bb4

boilerplateprojectSkeletoncharcoal

This package is auto-updated.

Last update: 2024-12-20 00:02:38 UTC

README

⚠️ 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

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.

Boilerplate homepage

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:

You should also change the information of the Composer package:

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.

Admin login

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

Status matrix

What's inside this Boilerplate?

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

  • Autoloader
    • Provided by Composer.
  • Config
  • Front Controller
  • 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

Coding Style

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

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

Authors