PHPackages                             locomotivemtl/charcoal-app - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. locomotivemtl/charcoal-app

ActiveLibrary[Framework](/categories/framework)

locomotivemtl/charcoal-app
==========================

Charcoal application, based on Slim 3

0.9.2(4y ago)1320.3k312MITPHPPHP ^7.3 || ^8.0

Since Mar 30Pushed 1y ago14 watchersCompare

[ Source](https://github.com/locomotivemtl/charcoal-app)[ Packagist](https://packagist.org/packages/locomotivemtl/charcoal-app)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/locomotivemtl-charcoal-app/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (10)Dependencies (20)Versions (60)Used By (12)

Charcoal App
============

[](#charcoal-app)

[![License](https://camo.githubusercontent.com/58c6330872c627c17d5fe6f5ce0d66bcc477d7a9be4bd5e0641be40d26123f79/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6c6f636f6d6f746976656d746c2f63686172636f616c2d6170702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/locomotivemtl/charcoal-app)[![Latest Stable Version](https://camo.githubusercontent.com/294d585dfa8b25609a4e6307599e58d1a4ffc0b70e647174781d4bbcec43e551/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c6f636f6d6f746976656d746c2f63686172636f616c2d6170702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/locomotivemtl/charcoal-app)[![Code Quality](https://camo.githubusercontent.com/f961f874eea941b58a29e7c048e9abab165b99e3100f728938891aabd51807b4/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6c6f636f6d6f746976656d746c2f63686172636f616c2d6170702e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-app/)[![Coverage Status](https://camo.githubusercontent.com/cf00ca98206a2e6c53abfa5aa8a5fc7ec772ea067a9e0010e362f0e562fbc55b/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f6c6f636f6d6f746976656d746c2f63686172636f616c2d6170702e7376673f7374796c653d666c61742d737175617265)](https://coveralls.io/r/locomotivemtl/charcoal-app)[![SensioLabs Insight](https://camo.githubusercontent.com/dfc09f6d6bc0ebbd538163ff0ac082ca2b33b2127e67fa2572f44b4851b39d93/68747470733a2f2f696d672e736869656c64732e696f2f73656e73696f6c6162732f692f35333362353739362d376536392d343261372d613034362d3731333432313436333038612e7376673f7374796c653d666c61742d737175617265)](https://insight.sensiolabs.com/projects/533b5796-7e69-42a7-a046-71342146308a)[![Build Status](https://camo.githubusercontent.com/09f55cf36b4eeffc3c2660e2a49e7708f1d53ac4ee797f05403e406474bbe5a4/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f6c6f636f6d6f746976656d746c2f63686172636f616c2d6170702e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/locomotivemtl/charcoal-app)

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

The framework is built on top of [Slim 3](https://github.com/slimphp/Slim/tree/3.x) and [Pimple](https://github.com/silexphp/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
-----------------

[](#table-of-contents)

- [Installation](#Installation)
    - [From Boilerplate](#from-boilerplate)
    - [Dependencies](#dependencies)
    - [Recommended Modules](#recommended-modules)
- [Components](#components)
    - [Config](#config-component)
    - [App](#app-compoment)
    - [Routes and RequestController](#routes-and-requestcontroller)
        - [Action Request Controller](#action-request-controller)
        - [Script Request Controller](#script-request-controller)
        - [Template Request Controller](#template-request-controller)
        - [Route API](#route-api)
        - [Routable objects](#routable-objects)
    - [Middlewares](#middlewares)
    - [Charcoal Binary](#charcoal-binary)
    - [PHPUnits Tests](#phpunit-tests)
- [Service Providers](#service-providers)
- [Usage](#usage)
- [Development](#development)
    - [Development dependencies](#development-dependencies)
    - [Continuous Integration](#continuous-integration)
    - [Coding Style](#coding-style)
    - [Authors](#authors)

Installation
------------

[](#installation)

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

```
★ composer require locomotivemtl/charcoal-app
```

### From Boilerplate

[](#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](https://github.com/locomotivemtl/charcoal-project-boilerplate):

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

### Dependencies

[](#dependencies)

#### Required

[](#required)

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

#### PSR

[](#psr)

- [**PSR-3**](https://www.php-fig.org/psr/psr-3/): Common interface for logging libraries. Fulfilled by Monolog.
- [**PSR-6**](https://www.php-fig.org/psr/psr-6/): Common interface for caching libraries. Fulfilled by Stash.
- [**PSR-7**](https://www.php-fig.org/psr/psr-7/): Common interface for HTTP messages. Fulfilled by Slim.
- [**PSR-11**](https://www.php-fig.org/psr/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](#development) section of this README file.

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

### Recommended Modules

[](#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**](https://packagist.org/packages/locomotivemtl/charcoal-email): Service provider for email management, using [PHPMailer](https://packagist.org/packages/phpmailer/phpmailer) (templating, queuing, sending, tracking).
- [**locomotivemtl/charcoal-cms**](https://packagist.org/packages/locomotivemtl/charcoal-cms): Pre-designed models and basic utilities for content management (pages, news, events).
- [**locomotivemtl/charcoal-admin**](https://packagist.org/packages/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
----------

[](#components)

The main components of the Charcoal App are:

- [Config](#config-component)
- [App](#app-compoment)
- [Module](#module-component)
- [Routes & Request Controllers](#routes--request-controllers)
    - [Action](#action-request-controller)
    - [Script](#script-request-controller)
    - [Template](#template-request-controller)
    - [Route API](#route-api)
- [Routable Objects](#routable-objects)
- [Charcoal Binary](#charcoal-binary)
- [PHPUnit Tests](#phpunit-tests)

Learn more about [components](docs/components.md).

Service Providers
-----------------

[](#service-providers)

Dependencies and extensions are handled by a dependency container, using [Pimple](https://packagist.org/packages/pimple/pimple), which can be defined via *service providers* (`Pimple\ServiceProviderInterface`).

#### Included Providers

[](#included-providers)

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

- [`AppServiceProvider`](docs/providers.md#app-service-provider)
- [`DatabaseServicePovider`](docs/providers.md#database-service-provider)
- [`FilesystemServiceProvider`](docs/providers.md#filesystem-service-provider)
- [`LoggerServiceProvider`](docs/providers.md#logger-service-provider)

#### External Providers

[](#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`](docs/providers.md#cache-service-provider)
- [`TranslatorServiceProvider`](docs/providers.md#translator-service-provider)
- [`ViewServiceProvider`](docs/providers.md#view-service-provider)

Learn more about [service providers](docs/providers.md).

Usage
-----

[](#usage)

Typical Front-Controller ([`www/index.php`](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](https://github.com/locomotivemtl/charcoal-project-boilerplate).

Development
-----------

[](#development)

To install the development environment:

```
$ composer install
```

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

```
$ composer test
```

### API Documentation

[](#api-documentation)

- The auto-generated `phpDocumentor` API documentation is available at:

- The auto-generated `apigen` API documentation is available at:
    [https://codedoc.pub/locomotivemtl/charcoal-app/master/](https://codedoc.pub/locomotivemtl/charcoal-app/master/index.html)

### Development Dependencies

[](#development-dependencies)

- [php-coveralls/php-coveralls](https://packagist.org/packages/php-coveralls/php-coveralls)
- [phpunit/phpunit](https://packagist.org/packages/phpunit/phpunit)
- [squizlabs/php\_codesniffer](https://packagist.org/packages/squizlabs/php_codesniffer)

### Coding Style

[](#coding-style)

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

- [*PSR-1*](https://www.php-fig.org/psr/psr-1/)
- [*PSR-2*](https://www.php-fig.org/psr/psr-2/)
- [*PSR-4*](https://www.php-fig.org/psr/psr-4/), autoloading is therefore provided by *Composer*.
- [*phpDocumentor*](http://phpdoc.org/) comments.
- [phpcs.xml.dist](phpcs.xml.dist) and [.editorconfig](.editorconfig) for coding standards.

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

Credits
-------

[](#credits)

- [Mathieu Ducharme](https://github.com/mducharme)
- [Chauncey McAskill](https://github.com/mcaskill)
- [Benjamin Roch](https://github.com/beneroch)
- [Locomotive](https://locomotive.ca/)

License
-------

[](#license)

Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance35

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community28

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 62.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~42 days

Recently: every ~217 days

Total

50

Last Release

1607d ago

PHP version history (5 changes)0.1PHP >=5.5.0

0.3PHP >=5.6.0

0.8.0PHP >=5.6.0 || >=7.0

0.9.0PHP >=7.1

0.9.1PHP ^7.3 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme)

![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill)

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (351 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (186 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (10 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (10 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (6 commits)")

---

Tags

appapplicationcharcoalphpslimframeworkslimcmscharcoal

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/locomotivemtl-charcoal-app/health.svg)

```
[![Health](https://phpackages.com/badges/locomotivemtl-charcoal-app/health.svg)](https://phpackages.com/packages/locomotivemtl-charcoal-app)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.6k509.9M17.0k](/packages/laravel-framework)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[cakephp/cakephp

The CakePHP framework

8.8k18.5M1.6k](/packages/cakephp-cakephp)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[slim/twig-view

Slim Framework 4 view helper built on top of the Twig 3 templating component

3708.0M210](/packages/slim-twig-view)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)