PHPackages 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. charcoal/admin ActiveLibrary[Admin Panels](/categories/admin) charcoal/admin ============== The Charcoal Administration Dashboard v5.0.0(2y ago)073MITPHPPHP ^7.4 || ^8.0 Since Sep 14Pushed 2y ago2 watchersCompare [ Source](https://github.com/charcoalphp/admin)[ Packagist](https://packagist.org/packages/charcoal/admin)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/charcoal-admin/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (26)Versions (362)Used By (3) Charcoal Admin ============== [](#charcoal-admin) The Admin package provides a customizable administration panel to manage data for Web applications and APIs. Installation ------------ [](#installation) ``` composer require charcoal/admin ``` Overview -------- [](#overview) ### 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 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/` ### Users [](#users) Authentication is done through the `Charcoal\Admin\User` class. It reuses the authentication, authorization and user model provided by [charcoal/user](https://github.com/charcoalphp/user). UI Elements ----------- [](#ui-elements) User-Interface elements in the Admin package (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/charcoalphp/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. - `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` Resources --------- [](#resources) - [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md) - [Report issues](https://github.com/charcoalphp/charcoal/issues) and [send pull requests](https://github.com/charcoalphp/charcoal/pulls)in the [main Charcoal repository](https://github.com/charcoalphp/charcoal) ### Health Score 36 — LowBetter than 82% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity4 Limited adoption so far Community24 Small or concentrated contributor base Maturity88 Battle-tested with a long release history 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 ~7 days Recently: every ~15 days Total 348 Last Release 794d ago Major Versions 0.30.3 → v2.1.22022-06-21 v2.2.3 → v3.0.162022-08-02 v3.1.8 → v4.0.02022-09-21 v4.1.0 → v5.0.02024-03-13 PHP version history (7 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 v2.1.2PHP ^7.4 || ^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/f3f29e38395113e2400bdd7e51bea982b17f120d4d5a53d4473b53118ee46f8d?d=identicon)[JoelAlphonso](/maintainers/JoelAlphonso) ![](https://www.gravatar.com/avatar/4229f19eecd12c2b651b6502dcc5adfba48c5770db3d2dbea55fc92c7a246b2b?d=identicon)[BeneRoch](/maintainers/BeneRoch) --- Top Contributors [![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (981 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)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (17 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 adminbackendcharcoalcmsphpread-only-repositorycmscharcoaladmin ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/charcoal-admin/health.svg) ``` [![Health](https://phpackages.com/badges/charcoal-admin/health.svg)](https://phpackages.com/packages/charcoal-admin) ``` ### Alternatives [locomotivemtl/charcoal-admin The Charcoal Administration Dashboard 1110.8k8](/packages/locomotivemtl-charcoal-admin)[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) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)