PHPackages locomotivemtl/charcoal-admin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Admin Panels](/categories/admin) 4. / 5. locomotivemtl/charcoal-admin ActiveLibrary[Admin Panels](/categories/admin) locomotivemtl/charcoal-admin ============================ The Charcoal Administration Dashboard 0.30.5(2y ago)1110.9k7[4 issues](https://github.com/locomotivemtl/charcoal-admin/issues)[6 PRs](https://github.com/locomotivemtl/charcoal-admin/pulls)12MITPHPPHP ^7.3 || ^8.0 Since Sep 14Pushed 3mo ago12 watchersCompare [ Source](https://github.com/locomotivemtl/charcoal-admin)[ Packagist](https://packagist.org/packages/locomotivemtl/charcoal-admin)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/locomotivemtl-charcoal-admin/feed)WikiDiscussions master Synced 4w ago READMEChangelog (10)Dependencies (27)Versions (354)Used By (12) Charcoal Admin Module ===================== [](#charcoal-admin-module) The standard Charcoal Admin Control Panel (Backend Dashboard). How to install ============== [](#how-to-install) The preferred (and only supported) way of installing charcoal-admin is with **composer**: ``` $ composer require locomotivemtl/charcoal-admin ``` > Note that charcoal-admin is intended to be run along a `charcoal-app` based project. To start from a boilerplate: > > ``` > $ composer create-project locomotivemtl/charcoal-project-boilerplate > ``` Dependencies ------------ [](#dependencies) - [locomotivemtl/charcoal-core](https://github.com/locomotivemtl/charcoal-core) - The framework classes. (Cache, Model, Metadata, View, Property, source, etc.) - It brings the following dependencies: - [locomotivemtl/charcoal-config](https://github.com/locomotivemtl/charcoal-config) - The configuration container for all things Charcoal. - [locomotivemtl/charcoal-property](https://github.com/locomotivemtl/charcoal-property) - The building blocks of the Model's definition. - [locomotivemtl/charcoal-image](https://github.com/locomotivemtl/charcoal-image) - Image manipulation. - [locomotivemtl/charcoal-view](https://github.com/locomotivemtl/charcoal-view) - The view / templating engines. Mustache is the default engine. - [locomotivemtl/charcoal-object](https://github.com/locomotivemtl/charcoal-object) - Object definition (Content and UserData), behaviors and tools. - [locomotivemtl/charcoal-user](https://github.com/locomotivemtl/charcoal-user) - User defintion (as Charcoal Model), authentication and authorization (with Laminas ACL). > 👉 Development dependencies are described in the *Development* section of this README file. Which, in turn, require: - `PHP 7.3+` - `ext-fileinfo` File / MIME identification. - `ext-mbstring` Multi-bytes string support. - `ext-pdo` PDO Database driver. - MySQL - Other databases (*postgresql*, *sqlite*) should work but are not supported. - Apache with `mod_rewrite` - Other HTTP servers (*IIS*, \_nginx) should work but are not supported. - `pimple/pimple` for dependency injection container. - `slim/slim` for the routing engine and HTTP handling. - `mustache/mustache` for the template engine. - `phpmailer` to send emails. - `league/climate` for CLI utilities. - `monolog/monolog` for (*PSR-3*) logging. Core concepts ============= [](#core-concepts) The *charcoal admin control panel* is: - Additional `admin` metadata on charcoal objects and models, which controls automatically how they can be customized in the backend. - A user / authentication system, which uses ACL for permissions. - A customizable 2-level menu, which builds custom backend for every install. - Dashboards and widgets. With some prebuilt functionalities for: - Listing collection of objects (`admin/object/collection`), customizable from the object's *admin metadata*. - Creating and editing objects (`admin/object/edit`), customizable from the objects's *admin metadata*. - Set of *scripts* to manage objects and the backend from the CLI. What's inside this module? ========================== [](#whats-inside-this-module) Like all Charcoal projects / modules, the main components are: - **Autoloader** - *PSR-4*, Provided by Composer. - **Config** - As JSON or PHP files in the [config/](config/) directory. - **Front Controller** - The admin front controller is handled in the `\Charcoal\Admin\Module` class. - **Objects** - Typically into `\Charcoal\Object\Content` and `\Charcoal\Object\UserData` - Extends `\Charcoal\Model\AbstractModel`, which implements the following interface: - `\Charcoal\Model\ModelInterface` - `\Charcoal\Core\IndexableInterface` - `\Charcoal\Metadata\DescribableInterface` - `\Charcoal\Source\StorableInterface` - `\Charcoal\Validator\ValidatableInterface` - `\Charcaol\View\ViewableInterface` - PHP Models in `src/Charcoal/Boilerplate/` - JSON metadata in `metadata/charcoal/boilerplate/` - **Templates** - Templates are specialized Model which acts as View / Controller - Split in `Templates`, `Widgets`, `PropertyDisplay`, and `PropertyInput` - PHP Models in `src/Charcoal/Boilerplate/Template/` - Mustache views (templates) in `templates/boilerplate/` - Optionnally, templates metadata in `metdata/boilerplate/template/` - **Actions** - Actions handle input and provide a response to a request - They create the charcoal-admin REST API. - The PHP classes in `src/Charcoal/Boilerplate/Action` - **Assets** - Assets are files required to be on the webserver root - Scripts, in `src/scripts/` and compiled in `www/assets/scripts/` - Styles , with SASS in `src/styles/` and compiled CSS in `www/assets/styles/` - Images, in `www/assets/images/` Objects ------- [](#objects) Users ----- [](#users) Authentication is done through the `Charcoal\Admin\User` class. It reuses the authentication, authorization and user model provided by \[charcoal-user\](. UI Elements =========== [](#ui-elements) User-Interface Elements, in charcoal-admin (or any other Charcoal modules, in fact), are composed of: - A PHP Controller, in *src/Charcoal/Admin/{{type}}/{{ident}}* - A mustache templates, in *templates/charcoal/admin/{{type}}/{{ident}}* - Optional additional metadata, in *metadata/charcoal/admin/{{type}}/{{ident}}* There are 3 main types of UI Elements: *Templates*, *Widgets* and *Property Inputs*. Templates --------- [](#templates) See the [src/Charcoal/Admin/Templates](src/Charcoal/Admin/Template) directory for the list of available Templates in this module. Note that the template views themselves (the mustache templates) are located in [templates/charcoal/admin/template/](templates/charcoal/admin/template/) directory. In addition to being standard Template Models (controllers), all *Template* of the admin module also implements the `\Charcoal\Admin\Template` class. This class provides additional controls to all templates: - `has_feedbacks` and `feedbacks` - `title`, `subtitle`, `show_title` and `show_subtitle` - `auth_required` - Protected, true by default. Set to false for templates that do not require an authenticated admin user. Widgets ------- [](#widgets) The following base widgets are available to build the various *admin* templates: - `Dashboard` - `Feedbacks` - `Form` - `FormGroup` - `FormProperty` - `Graph/Bar` - `Graph/Line` - `Graph/Pie` - Layout - MapWidget - Table - TableProperty Property Inputs --------------- [](#property-inputs) Similar to other UI elements, *Inputs* are specialized widgets that are meant to display a "form element" for a `Property`. Properties models are defined in the [charcoal-property](https://github.com/locomotivemtl/charcoal-property) package. The following property inputs are available to build forms in the *admin* module: - `Audio` - A special HTML5 widget to record an audio file from the microphone. - `Checkbox` - `DateTimePicker` - A date-time picker widget. - Requires the `` - `File` - A default `` that can be used as a base for all *File* properties. - `Image` - A specialized file input meant for uploading / previewing images. - `MapWidget` - A specialized widget to edit a point on a map. - Requires google-map. - `Number` - `Radio` - `Readonly` - `Select` - `Switch` - A specialized *Checkbox* meant to be displayed as an on/off switch. - `Text` - A default `` that can be used with most property types. - `Textarea` - A default `` editor that can be used with most textual property types. - `Tinymce` - A specialized *Textarea* wysiwyg editor. - Requires the `tinymce` javascript library. - `Selectize` - A specialized hybrid between a *Textbox* and *Select* jQuery based. - Highly customizable. - Requires the `selectize` javascript library. ### Selectize inputs options [](#selectize-inputs-options) Name Type Description Default **choice\_obj\_map** *array* Custom mapping between an object properties or callable and the selectize. It is discouraged to use renderable data. choice\_obj\_map must be a mapping with existing object properties. **value** Object property or object callable. Defines the actual value to be registered in the database **label** Object property or object callable. Defines the visible label of the input. ``` { "value" : "id", "label": "name:title:label:id" } ``` **form\_ident** *string|array* Allow to define a specific object form ident when creating or updating an object. You can specify different form idents for create and update by using the "create" and "update" array keys `"quick"` **selectize\_templates** *string|array* Allow custom rendering for selectize \[item\] and \[option\]. Overrule choice\_obj\_map\[label\]. Priotize using this for rendering custom labels instead of choice\_obj\_map. The value can either be a string with render tags, a path to a custom template or even an array mapping to handle "item", "option", "controller" and "data" individually. **item** (Can be a renderable string or template path) Custom renderable html or mustache template for the selectize item. \[Item\] is the term used to refer to a selected choice. **option** (Can be a renderable string or template path) Custom renderable html or mustache template for the selectize option. \[Option\] is the term used to refer to an available choice. **controller** Defines a rendering context (path to php controller). (optional) Default context is the object itself. **data**(array) Provides additional data to the controller `{}` **allow\_create** *bool* Display a 'create' button which triggers the selectize create functionality. `false` **allow\_update** *bool* Display an 'update' button which triggers the selectize update functionality. Applies to currently selected element. `false` **allow\_clipboard\_copy** *bool* Display a 'copy' button which allows the user to easilly copy all selected elements at once. `false` **deferred** *bool* Allow the select to load the dropdown "options" with an ajax request instead of on load. This can speed up the page load when there is a lot of "options". `false` **selectize\_options** *array* Defines the selectize js options. See the [Selectize.js doc](https://github.com/selectize/selectize.js/blob/master/docs/usage.md). Some usefull ones are : - "maxItems" - "maxOptions" - "create" - "placeholder" - "searchField" - "plugins" Also, two home made plugins are available : "btn\_remove" and "btn\_update" that are custom buttons for selected items that work well with charcoal objects and doesn't break styling. ``` { persist: true, preload: "focus", openOnFocus: true, labelField: "label", searchField: [ "value", "label" ] } ``` Usage example : ``` "categories": { "type": "object", "input_type": "charcoal/admin/property/input/selectize", "multiple": true, "deferred": true, "obj_type": "cms/object/news-category", "pattern": "title", "choice_obj_map": { "value": "ident", "label": "{{customLabelFunction}} - {{someAdditionalInfo }}" }, "selectize_templates": { "item": "project/selectize/custom-item-template", "option": "project/selectize/custom-option-template", "controller": "project/selectize/custom-template" }, "selectize_options": { "plugins": { "drag_drop": {}, "btn_remove": {}, "btn_update": {} } }, "form_ident": { "create": "quick.create", "update": "quick.update" } } ``` Selectize templates examples : ``` "selectize_templates": { "item": "{{customLabelFunction}} - {{someAdditionalInfo }}", "option": "{{customLabelFunction}} - {{someAdditionalInfo }}" }, --- "selectize_templates": "{{customLabelFunction}} - {{someAdditionalInfo }}", --- "selectize_templates": "project/selectize/custom-template", --- "selectize_templates": { "item": "project/selectize/custom-item-template", "option": "project/selectize/custom-option-template", "controller": "project/selectize/custom-template", "data": { "category": "{{selectedCategory}}" } }, ``` Actions ======= [](#actions) See the [src/Charcoal/Admin/Action/](src/Charcoal/Admin/Action/) directory for the list of availables Actions in this module. In addition to being standard Action Models (controllers), all *Action* of the admin module also implements the `\Charcoal\Admin\Action` class. Post Actions ------------ [](#post-actions) - `admin/login` - `admin/object/delete` - `admin/object/save` - `admin/object/update` - `admin/widget/load` - `admin/widget/table/inline` - `admin/widget/table/inlinue-multi` Cli Actions ----------- [](#cli-actions) See the [src/Charcoal/Admin/Action/Cli/](src/Charcoal/Admin/Action/Cli/) directory for the list of all available Cli Actions in this module. *Cli Actions* are specialized action meant to be run, interactively, from the Command Line Interface. With the Cli Actions in this module, it becomes quick and easy to manage a Charcoal project directly from a Terminal. > 👉 The [charcoal-cli](https://github.com/locomotivemtl/charcoal-project-boilerplate/blob/master/charcoal-cli.php) tool, available from `charcoal-project-boilerplate`, is the perfect tool to call the CLI Actions. Make sure it stays outside the document root! - `admin/objects` - List the object of a certain `obj-type`. - `admin/object/create` - Create a new object (and save it to storage) of a certain `obj-type` according to its metadata's properties. - `admin/object/table/alter` - Alter the existing database table of `obj-type` according to its metadata's properties. - `admin/object/table/create` - Create the database table for `obj-type` according to its metadata's properties. - `admin/user/create` Development =========== [](#development) To install the development environment: ``` $ composer install --prefer-source ``` To run the tests: ``` $ composer test ``` API documentation ----------------- [](#api-documentation) - The auto-generated `phpDocumentor` API documentation is available at - The auto-generated `apigen` API documentation is available at [https://codedoc.pub/locomotivemtl/charcoal-admin/master/](https://codedoc.pub/locomotivemtl/charcoal-admin/master/index.html) Coding style ------------ [](#coding-style) The Charcoal-Admin module follows the Charcoal coding-style: - [*PSR-1*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md), except for - Method names MUST be declared in `snake_case`. - [*PSR-2*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md), except for the PSR-1 requirement.q - [*PSR-4*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md), autoloading is therefore provided by *Composer* - [*phpDocumentor*](http://phpdoc.org/) - Add DocBlocks for all classes, methods, and functions; - For type-hinting, use `boolean` (instead of `bool`), `integer` (instead of `int`), `float` (instead of `double` or `real`); - Omit the `@return` tag if the method does not return anything. - Naming conventions - Read the [phpcs.xml](phpcs.xml) file for all the details. > Coding style validation / enforcement can be performed with `composer phpcs`. An auto-fixer is also available with `composer phpcbf`. For Javascript, the following coding style is enforced: - **todo** Every classes, methods and functions should be covered by unit tests. PHP code can be tested with *PHPUnit* and Javascript code with *QUnit*. Authors ======= [](#authors) - Mathieu Ducharme - Benjamin Roch - Dominic Lord - Chauncey McAskill - Antoine Boulanger - Joel Alphonso License ======= [](#license) Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details. ### Health Score 49 — FairBetter than 94% of packages Maintenance47 Moderate activity, may be stable Popularity30 Limited adoption so far Community33 Small or concentrated contributor base Maturity78 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~8 days Recently: every ~193 days Total 329 Last Release 676d ago PHP version history (6 changes)0.1PHP >=5.5.0 0.2PHP >=5.6.0 0.11.3PHP >=5.6.0 || >=7.0 0.22.1PHP >7.1 0.25.0PHP ^7.3 0.26.0PHP ^7.3 || ^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme) ![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill) ![](https://www.gravatar.com/avatar/b806b936695bdb12bf55e0e805bdaef15507502a07a16e34d43c5aad17390468?d=identicon)[dominiclord](/maintainers/dominiclord) --- Top Contributors [![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (1014 commits)")[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (651 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (375 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (222 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (143 commits)")[![hum-n](https://avatars.githubusercontent.com/u/4596862?v=4)](https://github.com/hum-n "hum-n (31 commits)")[![veve40](https://avatars.githubusercontent.com/u/7537381?v=4)](https://github.com/veve40 "veve40 (21 commits)")[![losted](https://avatars.githubusercontent.com/u/165665?v=4)](https://github.com/losted "losted (5 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![MouseEatsCat](https://avatars.githubusercontent.com/u/9273580?v=4)](https://github.com/MouseEatsCat "MouseEatsCat (2 commits)") --- Tags adminbackendcharcoalcmsphpcmscharcoaladmin ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/locomotivemtl-charcoal-admin/health.svg) ``` [![Health](https://phpackages.com/badges/locomotivemtl-charcoal-admin/health.svg)](https://phpackages.com/packages/locomotivemtl-charcoal-admin) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k31.1k12](/packages/tempest-framework)[symfony/symfony The Symfony PHP framework 31.4k86.9M2.2k](/packages/symfony-symfony)[aws/aws-sdk-php AWS SDK for PHP - Use Amazon Web Services in your PHP project 6.2k532.1M2.5k](/packages/aws-aws-sdk-php)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.8M715](/packages/sylius-sylius)[neuron-core/neuron-ai The PHP Agentic Framework. 2.0k496.1k34](/packages/neuron-core-neuron-ai)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 585.4M526](/packages/shopware-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)