Charcoal application, based on Slim 3
- dev-master / 0.8.x-dev
This package is auto-updated.
Last update: 2020-07-24 16:11:33 UTC
Charcoal App is a PHP framework to create web applications and APIs using Charcoal components.
The Charcoal App is a collection of modules, routes (
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
- Service Providers
The preferred (and only supported) way of installing charcoal-app is with composer:
★ composer require locomotivemtl/charcoal-app
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
- 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-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.
composer.json file for more details on dependencies.
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).
charcoal-project-boilerplateis really the recommended way of making sure a "full" Charcoal application is set up.
To install:★ composer create-project locomotivemtl/charcoal-project-boilerplate
The main components of the Charcoal App are:
- Routes & Request Controllers
- Routable Objects
- Charcoal Binary
- PHPUnit Tests
Learn more about components.
Dependencies and extensions are handled by a dependency container, using Pimple, which can be defined via service providers (
The Charcoal App comes with several providers out of the box. All of these are within the
The Charcoal App requires a few providers from independent components. The following use their own namespace and are automatically injected via the
Learn more about service providers.
Typical Front-Controller (
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.
To install the development environment:
$ composer install
To run the scripts (phplint, phpcs, and phpunit):
$ composer test
- The auto-generated
phpDocumentorAPI documentation is available at:
- The auto-generated
apigenAPI documentation is available at:
The charcoal-cache module follows the Charcoal coding-style:
- 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
Charcoal is licensed under the MIT license. See LICENSE for details.