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.8k6[4 issues](https://github.com/locomotivemtl/charcoal-admin/issues)[6 PRs](https://github.com/locomotivemtl/charcoal-admin/pulls)8MITPHPPHP ^7.3 || ^8.0 Since Sep 14Pushed 1mo 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 2mo ago READMEChangelog (10)Dependencies (27)Versions (354)Used By (8) 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 50 — FairBetter than 95% of packages Maintenance52 Moderate activity, may be stable Popularity30 Limited adoption so far Community32 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 626d 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 [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[shopware/platform The Shopware e-commerce core 3.3k1.5M3](/packages/shopware-platform)[tempest/framework The PHP framework that gets out of your way. 2.1k23.1k9](/packages/tempest-framework)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core)[ec-cube/ec-cube EC-CUBE EC open platform. 78527.0k1](/packages/ec-cube-ec-cube)[kunstmaan/admin-bundle The Kunstmaan Admin bundle supplies your project with a basic, elegant backend interface you can modify and extend so you can make your perfect admin module. The clean interface makes it straightforward for you and the people working with it to change settings and modify content. 58149.5k20](/packages/kunstmaan-admin-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)