locomotivemtl/charcoal-app

Charcoal application, based on Slim 3

Thursday, June 7, 2018
by mducharme
Repository
11 Watchers
10 Stars
12,231 Installations

PHP
8 Dependents
1 Suggesters
3 Forks
0 Open issues
48 Versions
7 % Grown

The README.md

Charcoal App

![License][badge-license] ![Code Quality][badge-scrutinizer] ![SensioLabs Insight][badge-sensiolabs] , _(*1)

Charcoal App is a PHP framework to create web applications and APIs using Charcoal components., _(*2)

The framework is built on top of Slim 3 and Pimple., _(*3)

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., _(*4)

The framework features (internally and externally) the following:, _(*5)

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, _(*6)

Installation
Components
Service Providers
Usage
Development

Installation

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

★ 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)., _(*8)

For a complete, ready-to-use project, start from the official boilerplate:, _(*9)

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

Dependencies

Required

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

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., _(*10)

Read the composer.json file for more details on dependencies., _(*11)

Recommended Modules

In addition to the above dependencies, here's a list of recommended modules that can be added to a project., _(*12)

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

Using the charcoal-project-boilerplate is really the recommended way of making sure a "full" Charcoal application is set up., _(*13)

To install:, _(*14)
★ composer create-project locomotivemtl/charcoal-project-boilerplate
  

Components

The main components of the Charcoal App are:, _(*15)

Config
App
~~Module~~
Routes & Request Controllers
- Action
- Script
- Template
- Route API
Routable Objects
Charcoal Binary
PHPUnit Tests

Learn more about components., _(*16)

Service Providers

Dependencies and extensions are handled by a dependency container, using Pimple, which can be defined via _service providers_ (Pimple\ServiceProviderInterface)., _(*17)

Included Providers

The Charcoal App comes with several providers out of the box. All of these are within the Charcoal\App\ServiceProvider namespace:, _(*18)

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:, _(*19)

Learn more about service providers., _(*20)

Usage

Typical Front-Controller (www/index.php):, _(*21)

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., _(*22)

Development

To install the development environment:, _(*23)

$ composer install

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

$ composer test

API Documentation

The auto-generated phpDocumentor API documentation is available at:
https://locomotivemtl.github.io/charcoal-app/docs/master/
The auto-generated apigen API documentation is available at:
https://codedoc.pub/locomotivemtl/charcoal-app/master/

Development Dependencies

Coding Style

The charcoal-cache module follows the Charcoal coding-style:, _(*25)

PSR-1
PSR-2
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 composer phpcbf., _(*26)

Credits

License

Charcoal is licensed under the MIT license. See LICENSE for details., _(*27)

The Versions

07/06 2018

dev-mducharme-scripts

dev-mducharme-scripts https://charcoal.locomotive.ca

Charcoal application, based on Slim 3

library charcoal-app

Charcoal application, based on Slim 3

locomotivemtl/charcoal-app

The README.md

Charcoal App

Table of Contents

Installation

From Boilerplate

Dependencies

Required

PSR

Recommended Modules

Components

Service Providers

Included Providers

External Providers

Usage

Development

API Documentation

Development Dependencies

Coding Style

Credits

License

The Versions

dev-mducharme-scripts

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-master

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.8.0

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-patch-cache

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.7.1

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-wip

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

dev-mcaskill-develop

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.7

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.6.1

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.6

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.5.3

The Requires

The Development Requires

by Mathieu Ducharme

by Locomotive

0.5.2