Charcoal Slim

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

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?

View mducharme/slim4-boilerplate for an example implementation.

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

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

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

To install the development environment:

$ composer install

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

$ composer test

Development Dependencies

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

Locomotive

License

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

locomotivemtl/charcoal-slim