{"id":19110171,"url":"https://github.com/locomotivemtl/charcoal-app","last_synced_at":"2025-04-30T20:42:06.664Z","repository":{"id":45320447,"uuid":"41179190","full_name":"locomotivemtl/charcoal-app","owner":"locomotivemtl","description":"Slim-based application (modules, routes / controllers and middlewares)","archived":false,"fork":false,"pushed_at":"2025-04-08T14:02:16.000Z","size":19628,"stargazers_count":13,"open_issues_count":2,"forks_count":3,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-17T06:56:24.164Z","etag":null,"topics":["app","application","charcoal","php","slim"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/locomotivemtl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-21T21:57:38.000Z","updated_at":"2021-12-21T16:16:47.000Z","dependencies_parsed_at":"2022-09-17T04:51:02.256Z","dependency_job_id":null,"html_url":"https://github.com/locomotivemtl/charcoal-app","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locomotivemtl","download_url":"https://codeload.github.com/locomotivemtl/charcoal-app/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251779053,"owners_count":21642476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app","application","charcoal","php","slim"],"created_at":"2024-11-09T04:23:55.774Z","updated_at":"2025-04-30T20:42:06.643Z","avatar_url":"https://github.com/locomotivemtl.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal App \n============\n\n[![License][badge-license]][charcoal-app]\n[![Latest Stable Version][badge-version]][charcoal-app]\n[![Code Quality][badge-scrutinizer]][dev-scrutinizer]\n[![Coverage Status][badge-coveralls]][dev-coveralls]\n[![SensioLabs Insight][badge-sensiolabs]][dev-sensiolabs]\n[![Build Status][badge-travis]][dev-travis]\n\nCharcoal App is a PHP framework to create web applications and APIs using Charcoal components.\n\nThe framework is built on top of [Slim 3][gh-slim] and [Pimple][gh-pimple].\n\n---\n\nThe 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_.\n\nThe framework features (internally and externally) the following:\n\n- PSR-3 logger\n- PSR-6 cache system\u003csup\u003e†\u003c/sup\u003e\n- PSR-7 kernel (web, API, CLI)\n- PSR-11 container\n- Translation layer\u003csup\u003e†\u003c/sup\u003e\n- File system layer\n- Database layer\n- View layer\u003csup\u003e†\u003c/sup\u003e\n\n\u003csmall\u003e†  Provided by external Charcoal components\u003c/small\u003e\n\n\n\n## Table of Contents\n\n-   [Installation](#Installation)\n    -   [From Boilerplate](#from-boilerplate)\n    -   [Dependencies](#dependencies)\n    -   [Recommended Modules](#recommended-modules)\n-   [Components](#components)\n    -   [Config](#config-component)\n    -   [App](#app-compoment)\n    -   [Routes and RequestController](#routes-and-requestcontroller)\n        -   [Action Request Controller](#action-request-controller)\n        -   [Script Request Controller](#script-request-controller)\n        -   [Template Request Controller](#template-request-controller)\n        -   [Route API](#route-api)\n        -   [Routable objects](#routable-objects)\n    -   [Middlewares](#middlewares)\n    -   [Charcoal Binary](#charcoal-binary)\n    -   [PHPUnits Tests](#phpunit-tests)\n-   [Service Providers](#service-providers)\n-   [Usage](#usage)\n-   [Development](#development)\n    -   [Development dependencies](#development-dependencies)\n    -   [Continuous Integration](#continuous-integration)\n    -   [Coding Style](#coding-style)\n    -   [Authors](#authors)\n\n\n\n## Installation\n\nThe preferred (and only supported) way of installing _charcoal-app_ is with **composer**:\n\n```shell\n★ composer require locomotivemtl/charcoal-app\n```\n\n### From Boilerplate\n\nThis module is intended to be used as the base for a web aplication (such as a website).\n\nFor a complete, ready-to-use project, start from the [official boilerplate][gh-charcoal-boilerplate]:\n\n```shell\n★ composer create-project locomotivemtl/charcoal-project-boilerplate\n```\n\n### Dependencies\n\n#### Required\n\n-   [**PHP 5.6+**](https://php.net): _PHP 7_ is recommended.\n-   [**locomotivemtl/charcoal-cache**][charcoal-cache]: Service provider for a PSR-6 compliant caching system, using [Stash][stash].\n-   [**locomotivemtl/charcoal-config**][charcoal-config]: Data-objects for configuring the application and designing controllers.\n-   [**locomotivemtl/charcoal-factory**][charcoal-factory]: Factory interface for creating providers, processors, and controllers.\n-   [**locomotivemtl/charcoal-translator**][charcoal-translator]: Service provider for tools to internationalize your application, using [Symfony Translation][symfony/translation].\n-   [**locomotivemtl/charcoal-view**][charcoal-view]: Service provider for a view renderer and templating engine adapters for [Mustache][mustache] and [Twig][twig].\n-   [**league/climate**][climate]: Command-line abstraction for designing console commands for your application.\n-   [**league/flysystem**][flysystem]: File system abstraction for working with local and remote storage spaces.\n-   [**monolog/monolog**][monolog]: PSR-3 compliant client for logging your application's requests, errors, and information.\n-   [**pimple/pimple**][pimple]: PSR-11 compliant service container and provider library.\n-   [**slim/slim**][slim]: PSR-7 compliant HTTP client and router.\n\n#### PSR\n\n-   [**PSR-3**][psr-3]: Common interface for logging libraries. Fulfilled by Monolog.\n-   [**PSR-6**][psr-6]: Common interface for caching libraries. Fulfilled by Stash.\n-   [**PSR-7**][psr-7]: Common interface for HTTP messages. Fulfilled by Slim.\n-   [**PSR-11**][psr-11]: Common interface for dependency containers. Fulfilled by Pimple.\n\n\u003e 👉 Development dependencies, which are optional when using charcoal-app in a project, are described in the [Development](#development) section of this README file.\n\nRead the `composer.json` file for more details on dependencies.\n\n### Recommended Modules\n\nIn addition to the above dependencies, here's a list of recommended modules that can be added to a project.\n\n-   [**locomotivemtl/charcoal-email**][charcoal-email]: Service provider for email management, using [PHPMailer][phpmailer] (templating, queuing, sending, tracking).\n-   [**locomotivemtl/charcoal-cms**][charcoal-cms]: Pre-designed models and basic utilities for content management (pages, news, events).\n-   [**locomotivemtl/charcoal-admin**][charcoal-admin]: Administration interface for your Charcoal applications (add/edit/delete objects, file manager).\n\n\u003e Using the `charcoal-project-boilerplate` is really the recommended way of making sure a \"full\" Charcoal application is set up.\n\u003e \n\u003e To install:\n\u003e\n\u003e ```shell\n\u003e ★ composer create-project locomotivemtl/charcoal-project-boilerplate\n\u003e ```\n\n\n\n## Components\n\nThe main components of the Charcoal App are:\n\n-   [Config](#config-component)\n-   [App](#app-compoment)\n-   ~~[Module](#module-component)~~\n-   [Routes \u0026 Request Controllers](#routes--request-controllers)\n    -   [Action](#action-request-controller)\n    -   [Script](#script-request-controller)\n    -   [Template](#template-request-controller)\n    -   [Route API](#route-api)\n-   [Routable Objects](#routable-objects)\n-   [Charcoal Binary](#charcoal-binary)\n-   [PHPUnit Tests](#phpunit-tests)\n\nLearn more about [components](docs/components.md).\n\n\n\n## Service Providers\n\nDependencies and extensions are handled by a dependency container, using [Pimple][pimple], which can be defined via _service providers_ (`Pimple\\ServiceProviderInterface`).\n\n#### Included Providers\n\nThe Charcoal App comes with several providers out of the box. All of these are within the `Charcoal\\App\\ServiceProvider` namespace:\n\n-   [`AppServiceProvider`](docs/providers.md#app-service-provider)\n-   [`DatabaseServicePovider`](docs/providers.md#database-service-provider)\n-   [`FilesystemServiceProvider`](docs/providers.md#filesystem-service-provider)\n-   [`LoggerServiceProvider`](docs/providers.md#logger-service-provider)\n\n#### External Providers\n\nThe Charcoal App requires a few providers from independent components. The following use their own namespace and are automatically injected via the `AppServiceProvider`:\n\n-   [`CacheServiceProvider`](docs/providers.md#cache-service-provider)\n-   [`TranslatorServiceProvider`](docs/providers.md#translator-service-provider)\n-   [`ViewServiceProvider`](docs/providers.md#view-service-provider)\n\nLearn more about [service providers](docs/providers.md).\n\n\n\n## Usage\n\nTypical Front-Controller ([`www/index.php`](www/index.php)):\n\n```php\nuse \\Charcoal\\App\\App;\nuse \\Charcoal\\App\\AppConfig;\nuse \\Charcoal\\App\\AppContainer;\n\ninclude '../vendor/autoload.php';\n\n$config = new AppConfig();\n$config-\u003eaddFile(__DIR__.'/../config/config.php');\n$config-\u003eset('ROOT', dirname(__DIR__) . '/');\n\n// Create container and configure it (with charcoal-config)\n$container = new AppContainer([\n    'settings' =\u003e [\n        'displayErrorDetails' =\u003e true\n    ],\n    'config' =\u003e $config\n]);\n\n// Charcoal / Slim is the main app\n$app = App::instance($container);\n$app-\u003erun();\n```\n\nFor a complete project example using `charcoal-app`, see the [charcoal-project-boilerplate][gh-charcoal-boilerplate].\n\n\n\n## Development\n\nTo install the development environment:\n\n```shell\n$ composer install\n```\n\nTo run the scripts (phplint, phpcs, and phpunit):\n\n```shell\n$ composer test\n```\n\n\n\n### API Documentation\n\n-   The auto-generated `phpDocumentor` API documentation is available at:  \n    [https://locomotivemtl.github.io/charcoal-app/docs/master/](https://locomotivemtl.github.io/charcoal-app/docs/master/)\n-   The auto-generated `apigen` API documentation is available at:  \n    [https://codedoc.pub/locomotivemtl/charcoal-app/master/](https://codedoc.pub/locomotivemtl/charcoal-app/master/index.html)\n\n\n\n### Development Dependencies\n\n-   [php-coveralls/php-coveralls][phpcov]\n-   [phpunit/phpunit][phpunit]\n-   [squizlabs/php_codesniffer][phpcs]\n\n\n\n### Coding Style\n\nThe charcoal-cache module follows the Charcoal coding-style:\n\n-   [_PSR-1_][psr-1]\n-   [_PSR-2_][psr-2]\n-   [_PSR-4_][psr-4], autoloading is therefore provided by _Composer_.\n-   [_phpDocumentor_](http://phpdoc.org/) comments.\n-   [phpcs.xml.dist](phpcs.xml.dist) and [.editorconfig](.editorconfig) for coding standards.\n\n\u003e Coding style validation / enforcement can be performed with `composer phpcs`. An auto-fixer is also available with `composer phpcbf`.\n\n\n\n## Credits\n\n-   [Mathieu Ducharme](https://github.com/mducharme)\n-   [Chauncey McAskill](https://github.com/mcaskill)\n-   [Benjamin Roch](https://github.com/beneroch)\n-   [Locomotive](https://locomotive.ca/)\n\n\n\n## License\n\nCharcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.\n\n\n\n[charcoal-admin]:        https://packagist.org/packages/locomotivemtl/charcoal-admin\n[charcoal-app]:          https://packagist.org/packages/locomotivemtl/charcoal-app\n[charcoal-cache]:        https://packagist.org/packages/locomotivemtl/charcoal-cache\n[charcoal-cms]:          https://packagist.org/packages/locomotivemtl/charcoal-cms\n[charcoal-config]:       https://packagist.org/packages/locomotivemtl/charcoal-config\n[charcoal-email]:        https://packagist.org/packages/locomotivemtl/charcoal-email\n[charcoal-factory]:      https://packagist.org/packages/locomotivemtl/charcoal-factory\n[charcoal-translator]:   https://packagist.org/packages/locomotivemtl/charcoal-translator\n[charcoal-view]:         https://packagist.org/packages/locomotivemtl/charcoal-view\n\n[gh-slim]:                  https://github.com/slimphp/Slim/tree/3.x\n[gh-pimple]:                https://github.com/silexphp/Pimple\n[gh-charcoal-boilerplate]:  https://github.com/locomotivemtl/charcoal-project-boilerplate\n\n[dev-scrutinizer]:    https://scrutinizer-ci.com/g/locomotivemtl/charcoal-app/\n[dev-coveralls]:      https://coveralls.io/r/locomotivemtl/charcoal-app\n[dev-sensiolabs]:     https://insight.sensiolabs.com/projects/533b5796-7e69-42a7-a046-71342146308a\n[dev-travis]:         https://travis-ci.org/locomotivemtl/charcoal-app\n\n[badge-license]:      https://img.shields.io/packagist/l/locomotivemtl/charcoal-app.svg?style=flat-square\n[badge-version]:      https://img.shields.io/packagist/v/locomotivemtl/charcoal-app.svg?style=flat-square\n[badge-scrutinizer]:  https://img.shields.io/scrutinizer/g/locomotivemtl/charcoal-app.svg?style=flat-square\n[badge-coveralls]:    https://img.shields.io/coveralls/locomotivemtl/charcoal-app.svg?style=flat-square\n[badge-sensiolabs]:   https://img.shields.io/sensiolabs/i/533b5796-7e69-42a7-a046-71342146308a.svg?style=flat-square\n[badge-travis]:       https://img.shields.io/travis/locomotivemtl/charcoal-app.svg?style=flat-square\n\n[climate]:               https://packagist.org/packages/league/climate\n[fastroute]:             https://packagist.org/packages/nikic/fast-route\n[flysystem]:             https://packagist.org/packages/league/flysystem\n[monolog]:               https://packagist.org/packages/monolog/monolog\n[mustache]:              https://packagist.org/packages/mustache/mustache\n[phpmailer]:             https://packagist.org/packages/phpmailer/phpmailer\n[phpunit]:               https://packagist.org/packages/phpunit/phpunit\n[phpcs]:                 https://packagist.org/packages/squizlabs/php_codesniffer\n[phpcov]:                https://packagist.org/packages/php-coveralls/php-coveralls\n[pimple]:                https://packagist.org/packages/pimple/pimple\n[slim]:                  https://packagist.org/packages/slim/slim\n[stash]:                 https://packagist.org/packages/tedivm/stash\n[symfony/translation]:   https://packagist.org/packages/symfony/translation\n[twig]:                  https://packagist.org/packages/twig/twig\n\n[psr-1]:  https://www.php-fig.org/psr/psr-1/\n[psr-2]:  https://www.php-fig.org/psr/psr-2/\n[psr-3]:  https://www.php-fig.org/psr/psr-3/\n[psr-4]:  https://www.php-fig.org/psr/psr-4/\n[psr-6]:  https://www.php-fig.org/psr/psr-6/\n[psr-7]:  https://www.php-fig.org/psr/psr-7/\n[psr-11]: https://www.php-fig.org/psr/psr-11/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocomotivemtl%2Fcharcoal-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocomotivemtl%2Fcharcoal-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocomotivemtl%2Fcharcoal-app/lists"}