locomotivemtl/charcoal-app

Charcoal application, based on Slim 3

Maintainers

Details

github.com/locomotivemtl/charcoal-app

Homepage

Source

Issues

Installs: 19 811

Dependents: 13

Suggesters: 2

Security: 0

Stars: 13

Watchers: 16

Forks: 3

Open Issues: 2

0.9.2 2021-12-17 17:58 UTC

Requires

Requires (Dev)

MIT 2dac1f0814a38081a7443c75a006b58a3680eb24

  • Mathieu Ducharme <mat.woop@locomotive.ca>
  • Locomotive

frameworkcmsslimcharcoal

This package is auto-updated.

Last update: 2024-04-10 19:49:25 UTC

README

License Latest Stable Version Code Quality Coverage Status SensioLabs Insight Build Status

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

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

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.

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:

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:

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:

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

Development Dependencies

Coding Style

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

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

Credits

License

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