PHPackages                             locomotivemtl/charcoal-slim - 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. locomotivemtl/charcoal-slim

ActiveLibrary

locomotivemtl/charcoal-slim
===========================

171PHPCI failing

Since Mar 22Pushed 3y ago2 watchersCompare

[ Source](https://github.com/locomotivemtl/charcoal-slim)[ Packagist](https://packagist.org/packages/locomotivemtl/charcoal-slim)[ RSS](/packages/locomotivemtl-charcoal-slim/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Charcoal Slim
=============

[](#charcoal-slim)

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

Dependencies
------------

[](#dependencies)

- PHP 7.4+
- `slim/slim` and `slim/psr7` For the main PSR-7 App.
- `pimple/pimple` To generate the (PSR-11) DI Container from service-providers.
- `charcoal/config` For the configuration format.
- `charcoal/view` For templating (mustache, twig) support.
- `guzzlehttp/guzzle` For the HTTP Client (used to proxy requests).

How does it work?
-----------------

[](#how-does-it-work)

> View [mducharme/slim4-boilerplate](https://github.com/mducharme/slim4-boilerplate) for an example implementation.

### The Bootstrap class

[](#the-bootstrap-class)

The Bootstrap class can be used to set up a slim application, with a charcoal configuration object and a pimple container. The charcoal configuration object can be set with PHP and JSON. The pimple container is typically used as a dependency injection container and is set with service providers.

Typically, the bootstrap will be passed a bunch of callback functions that will be executed when starting the app.

There are 4 types of callback methods that can be added, depending on which object they need to modify.

- **Config** callbacks can be added with `$bootstrap->addConfig(function (\Charcoal\Config\ConfigInterface $config) : \Charcoal\Config\ConfigInterface { /* */ });`
    - This is how to add custom configuration to an app, and would most likely be used for every project, typically to load the JSON (and php) config files.
- **Container** callbacks can be added with `$bootstrap->addContainer(function (\Pimple\Container $container) : \Pimple\Container { /* */ });`
    - This is how to register custom service providers on the Pimple DI container.
- **Bootstrap** callbacks can be added with `$bootstrap->addBootstrap(function (\Charcoal\Slim\Bootstrap $bootstrap) : \Charcoal\Slim\Bootstrap { /* */ });`
    - This is how to add Charcoal modules or any other system that needs to add more config, container or app callbacks to the process.
- **App** callbacks can be added with `$bootstrap->addApp(function \Slim\App $app): \Slim\App { /* */ });`
    - This is how to add any (psr-15) middlewares or route / route handlers to the Slim app.

Here is how a typical Charcoal project's front controller (`index.php`) may look:

```
$bootstrap = new \Charcoal\Slim\Bootstrap();
$bootstrap->addConfig((require __DIR__ . '/../app/config.php'));
$bootstrap->addContainer((require __DIR__ . '/../app/services.php'));
$bootstrap->addBootstrap((require __DIR__ . '/../app/modules.php'));
$bootstrap->addApp((require __DIR__ . '/../app/middlewares.php'));
$bootstrap->addApp((require __DIR__ . '/../app/routes.php'));
$app = $bootstrap();
$app->run();
```

(All the `app/*.php` files should return a callback function that matches the appropriate signature.)

### The Route Mapper

[](#the-route-mapper)

The Route Mapper is an essential service provided by this library. It will transform a "route definition" array into an actual Slim route for the app.

Here is JSON example of different route definitions.

```
{
    "routes": {
        "home": {
            "type": "view",
            "view": "contexts/views/home",
            "template": "view/home"
        },
        "redirect-example": {
            "type": "redirect",
            "target" "https://foo.com/"
        },
        "json-api-example": {
            "type": "json",
            "context": "contexts/foobar"
        }
    }

}
```

> The `type` is required. It must match a defined route handler. See below for the 5 handlers available by default

To set up those routes on the app:

```
$routeMapper = new RouteMapper();
$routeMapper($app, $config['routes']);
```

#### Adding a route manually

[](#adding-a-route-manually)

### The 5 core (default) types of handler

[](#the-5-core-default-types-of-handler)

- **Controller** (`\Charcoal\Slim\Handlers\Controller`)
    - Configuration
        - `controller`
- **JSON** (`\Charcoal\Slim\Handlers\Controller`)
    - Configuration
        - `context`
- **Proxy** (`\Charcoal\Slim\Handlers\Controller`)
    - Configuration
        - `url`
        - `requestOptions`
        - `proxyMethod` (Optional, use current request method if unspecified)
- **Redirection** (`\Charcoal\Slim\Handlers\Redirection`)
    - Configuration:
        - `target`
        - `code` (default = 301)
- **View** (`\Charcoal\Slim\Handlers\View`)
    - Configuration
        - `engine` (Optional, use app default if unspecified)
        - `template`
        - `view` (Optional view controller)

### Default service providers

[](#default-service-providers)

There are 2 available service providers:

- \\Charcoal\\Slim\\Services\\ControllersProvider
    - Provide (empty) `app/controllers` and `app/contexts`.
- \\Charcoal\\Slim\\Services\\HandlersProvider
    - Provide (empty) `app/handlers`.

Important: note that those providers must be registered manually to the app container, with

```
$bootstrap->addToContainer(function callback(Container $container) {
   $container->register(new \Charcoal\Slim\Services\HandlersProvider());
   $container->extends(
       'app/handlers',
       function(array $handlers, Container $container) : array {
          // Add custom route handlers here
          $handlers['custom'] = \App\Handlers\CustomHandler::class;
          return $handlers;
       }
   );

   $container->register(new ControllersProvider());
   $container->extend(
       'app/controllers',
       function (array $controllers, Container $container): array {
           // Add custom route controllers here
           $controllers['custom'] = \App\Controllers\Custom::class;
           return $controllers;
       }
   );
   $container->extend(
       'app/contexts',
       function (array $contexts, Container $container): array {
           // Add custom json or view contexts here
           $contexts['custom'] = \App\Contexts\Custom::class;
           $contexts['views/custom'] = \App\Contexts\Views\Custom::class;
           return $contexts;
       }
   );
});
```

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

[](#development)

To install the development environment:

```
$ composer install
```

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

```
$ composer test
```

### Development Dependencies

[](#development-dependencies)

- [php-coveralls/php-coveralls](phpcov)
- [phpunit/phpunit](phpunit)
- [squizlabs/php\_codesniffer](phpcs)

### Coding Style

[](#coding-style)

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

- \[*PSR-4*\]\[psr-4\], autoloading is therefore provided by *Composer*.
- \[*PSR-12*\]\[psr-12\]
- [*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)

- [Locomotive](https://locomotive.ca/)

License
-------

[](#license)

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

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity22

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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.

### Community

Maintainers

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

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (7 commits)")

### Embed Badge

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

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

PHPackages © 2026

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