README

Charcoal App is a PHP framework to create web applications and APIs using Charcoal components.

The framework is built on top of Slim 3 and Pimple.

The Charcoal App is a collection of modules, routes (templates, actions and scripts), handlers, and services tied together with a config, a service container, and service providers.

The framework features (internally and externally) the following:

• PSR-3 logger
• PSR-6 cache system^†
• PSR-7 kernel (web, API, CLI)
• PSR-11 container
• Translation layer^†
• File system layer
• Database layer
• View layer^†

† Provided by external Charcoal components

Table of Contents

• Installation
  • From Boilerplate
  • Dependencies
  • Recommended Modules
• Components
  • Config
  • App
  • Routes and RequestController
    • Action Request Controller
    • Script Request Controller
    • Template Request Controller
    • Route API
    • Routable objects
  • Middlewares
  • Charcoal Binary
  • PHPUnits Tests
• Service Providers
• Usage
• Development
  • Development dependencies
  • Continuous Integration
  • Coding Style
  • Authors

Installation

The preferred (and only supported) way of installing charcoal-app is with composer:

★ composer require locomotivemtl/charcoal-app

From Boilerplate

This module is intended to be used as the base for a web aplication (such as a website).

For a complete, ready-to-use project, start from the official boilerplate:

★ composer create-project locomotivemtl/charcoal-project-boilerplate

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.
• locomotivemtl/charcoal-cache: Service provider for a PSR-6 compliant caching system, using Stash.
• locomotivemtl/charcoal-config: Data-objects for configuring the application and designing controllers.
• locomotivemtl/charcoal-factory: Factory interface for creating providers, processors, and controllers.
• locomotivemtl/charcoal-translator: Service provider for tools to internationalize your application, using Symfony Translation.
• locomotivemtl/charcoal-view: Service provider for a view renderer and templating engine adapters for Mustache and Twig.
• league/climate: Command-line abstraction for designing console commands for your application.
• league/flysystem: File system abstraction for working with local and remote storage spaces.
• monolog/monolog: PSR-3 compliant client for logging your application's requests, errors, and information.
• pimple/pimple: PSR-11 compliant service container and provider library.
• slim/slim: PSR-7 compliant HTTP client and router.

PSR

• PSR-3: Common interface for logging libraries. Fulfilled by Monolog.
• PSR-6: Common interface for caching libraries. Fulfilled by Stash.
• PSR-7: Common interface for HTTP messages. Fulfilled by Slim.
• PSR-11: Common interface for dependency containers. Fulfilled by Pimple.

👉 Development dependencies, which are optional when using charcoal-app in a project, are described in the Development section of this README file.

Read the composer.json file for more details on dependencies.

Recommended Modules

In addition to the above dependencies, here's a list of recommended modules that can be added to a project.

• locomotivemtl/charcoal-email: Service provider for email management, using PHPMailer (templating, queuing, sending, tracking).
• locomotivemtl/charcoal-cms: Pre-designed models and basic utilities for content management (pages, news, events).
• locomotivemtl/charcoal-admin: Administration interface for your Charcoal applications (add/edit/delete objects, file manager).

Using the charcoal-project-boilerplate is really the recommended way of making sure a "full" Charcoal application is set up.

To install:

★ composer create-project locomotivemtl/charcoal-project-boilerplate

Components

The main components of the Charcoal App are:

• Config
• App
• Module
• Routes & Request Controllers
  • Action
  • Script
  • Template
  • Route API
• Routable Objects
• Charcoal Binary
• PHPUnit Tests

Learn more about components.

Service Providers

Dependencies and extensions are handled by a dependency container, using Pimple, which can be defined via service providers (Pimple\ServiceProviderInterface).

Included Providers

The Charcoal App comes with several providers out of the box. All of these are within the Charcoal\App\ServiceProvider namespace:

• AppServiceProvider
• DatabaseServicePovider
• FilesystemServiceProvider
• LoggerServiceProvider

External Providers

The Charcoal App requires a few providers from independent components. The following use their own namespace and are automatically injected via the AppServiceProvider:

• CacheServiceProvider
• TranslatorServiceProvider
• ViewServiceProvider

Learn more about service providers.

Usage

Typical Front-Controller (www/index.php):

use \Charcoal\App\App;
use \Charcoal\App\AppConfig;
use \Charcoal\App\AppContainer;

include '../vendor/autoload.php';

$config = new AppConfig();
$config->addFile(__DIR__.'/../config/config.php');
$config->set('ROOT', dirname(__DIR__) . '/');

// Create container and configure it (with charcoal-config)
$container = new AppContainer([
    'settings' => [
        'displayErrorDetails' => true
    ],
    'config' => $config
]);

// Charcoal / Slim is the main app
$app = App::instance($container);
$app->run();

For a complete project example using charcoal-app, see the charcoal-project-boilerplate.

Development

To install the development environment:

$ composer install

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

$ composer test

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-app/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-app/master/

Development Dependencies

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

Coding Style

The charcoal-cache module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

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

Credits

• Mathieu Ducharme
• Chauncey McAskill
• Benjamin Roch
• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.