locomotivemtl / charcoal-app
Charcoal application, based on Slim 3
Installs: 19 970
Dependents: 13
Suggesters: 2
Security: 0
Stars: 13
Watchers: 16
Forks: 3
Open Issues: 2
Requires
- php: ^7.3 || ^8.0
- ext-pdo: *
- league/climate: ^3.2
- league/flysystem: ^1.0
- locomotivemtl/charcoal-cache: ~0.1
- locomotivemtl/charcoal-config: ~0.8
- locomotivemtl/charcoal-factory: ~0.4
- locomotivemtl/charcoal-translator: ~0.3
- locomotivemtl/charcoal-view: ~0.3
- monolog/monolog: ^1.17
- psr/http-message: ^1.0
- psr/log: ^1.0
- slim/slim: ~3.7
Requires (Dev)
- league/flysystem-aws-s3-v3: ^1.0
- league/flysystem-memory: ^1.0
- league/flysystem-sftp: ^1.0
- mockery/mockery: ^1.0
- mustache/mustache: ^2.11
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^9.0
- squizlabs/php_codesniffer: ^3.0
- tedivm/stash: ~0.16
- dev-master / 0.9.x-dev
- 0.9.2
- 0.9.1
- 0.9.0
- 0.8.5
- 0.8.4.1
- 0.8.4
- 0.8.3.3
- 0.8.3.2
- 0.8.3.1
- 0.8.3
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.1
- 0.7
- 0.6.1
- 0.6
- 0.5.3
- 0.5.2
- 0.5.1.3
- 0.5.1.2
- 0.5.1.1
- 0.5.1
- 0.5.0.1
- 0.5
- 0.4.8
- 0.4.7
- 0.4.6
- 0.4.5.3
- 0.4.5.2
- 0.4.5.1
- 0.4.5
- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4
- 0.3.1
- 0.3
- 0.2.8
- 0.2.7
- 0.2.6
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2
- 0.1.1
- 0.1
- dev-mcaskill-patch-improve-script-args
- dev-mcaskill-patch-from-base-path
- dev-slim4
- dev-fix/template-init
- dev-joel-start-fixing-config-merge
- dev-mducharme-scripts
- dev-mcaskill-develop
- dev-mcaskill-psr11
This package is auto-updated.
Last update: 2024-10-10 20:52:24 UTC
README
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
- 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.
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.
- 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.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
- 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:
- 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 withcomposer phpcbf
.
Credits
License
Charcoal is licensed under the MIT license. See LICENSE for details.