PHPackages                             locomotivemtl-charcoal/charcoal - 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. [Framework](/categories/framework)
4. /
5. locomotivemtl-charcoal/charcoal

Abandoned → [charcoal/charcoal](/?search=charcoal%2Fcharcoal)Library[Framework](/categories/framework)

locomotivemtl-charcoal/charcoal
===============================

The Charcoal Framework monorepo

v5.1.0(1y ago)83[12 issues](https://github.com/charcoalphp/charcoal/issues)[5 PRs](https://github.com/charcoalphp/charcoal/pulls)MITPHPPHP ^7.4 || ^8.0CI passing

Since May 27Pushed 2mo ago7 watchersCompare

[ Source](https://github.com/charcoalphp/charcoal)[ Packagist](https://packagist.org/packages/locomotivemtl-charcoal/charcoal)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/locomotivemtl-charcoal-charcoal/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (35)Versions (112)Used By (0)

 [![Charcoal](assets/docs/images/charcoal-logo-full.svg)](assets/docs/images/charcoal-logo-full.svg)
 by [Locomotive](https://locomotive.ca) 🚂

---

[![License](https://camo.githubusercontent.com/1a298fe9e4dbad64491cd9f7cfeae8e4e36442acbc5664712bac35705e52505f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f63686172636f616c2f63686172636f616c2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Latest Stable Version](https://camo.githubusercontent.com/5ec367ea338611ab524ad8ec1081ec27221749b4921a16506a671c2e3db8ec44/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63686172636f616c2f63686172636f616c2e7376673f7374796c653d666c61742d737175617265266c6f676f3d7061636b6167697374)](https://packagist.org/packages/charcoal/charcoal)[![Uses Semantic Release with Conventional Commits](https://camo.githubusercontent.com/ad41e342861cfdbf96b7d40b1f11da6a3a7a9cfdcbe76c7c37e49cf3e8bc37e3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f73656d616e7469632d2d72656c656173652d636f6e76656e74696f6e616c636f6d6d6974732d6531303037393f6c6f676f3d73656d616e7469632d72656c65617365267374796c653d666c61742d737175617265)](https://github.com/semantic-release/semantic-release)[![Commitizen-friendly](https://camo.githubusercontent.com/d92fffaee8115c3287f01f070320a571b55d12ed331751e157f2f8c3ac361b76/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f6d6d6974697a656e2d667269656e646c792d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/commitizen/cz-cli)[![Supported PHP Version](https://camo.githubusercontent.com/03998d43a5ee66f0266594dbc1d221896d389b7ab45ffe9130aa726e778f0835/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f63686172636f616c2f63686172636f616c3f7374796c653d666c61742d737175617265266c6f676f3d706870)](composer.json)

Charcoal is a web framework and content management system that adapts to all of your project's needs.

This repository is a monorepo containing the entirety of the web framework. Charcoal can be used as a full stack framework or as standalone packages which can be used independently.

Charcoal packages
-----------------

[](#charcoal-packages)

Core packages can be found in the [`packages`](packages/) directory.

DirectoryDistributionDescription[`admin`](packages/admin)[charcoal/admin](https://github.com/charcoalphp/admin)The administration dashboard for Charcoal.[`app`](packages/app)[charcoal/app](https://github.com/charcoalphp/app)The web application layer (container, routing, controllers,…), based on [Slim](https://github.com/slimphp/slim).[`attachment`](packages/attachment)[charcoal/attachment](https://github.com/charcoalphp/attachment)Provides support for working with relationships between models.[`cache`](packages/cache)[charcoal/cache](https://github.com/charcoalphp/cache)The cache layer, based on [Stash](https://github.com/tedious/Stash).[`cms`](packages/cms)[charcoal/cms](https://github.com/charcoalphp/cms)Provides content management system (CMS) tools and extensions.[`config`](packages/config)[charcoal/config](https://github.com/charcoalphp/config)The base configuration and entity layer most packages build upon.[`core`](packages/core)[charcoal/core](https://github.com/charcoalphp/core)The model, repository, and database layer.[`email`](packages/email)[charcoal/email](https://github.com/charcoalphp/email)Provides support for sending emails, based on [PHPMailer](https://github.com/PHPMailer/PHPMailer).[`factory`](packages/factory)[charcoal/factory](https://github.com/charcoalphp/factory)Provides support for object creation (factory, builder, class resolution,…).[`image`](packages/image)[charcoal/image](https://github.com/charcoalphp/image)Provides support for image handling and manipulation.[`object`](packages/object)[charcoal/object](https://github.com/charcoalphp/object)Provides support for advanced modeling (routable, revisionable, authoriship,…).[`property`](packages/property)[charcoal/property](https://github.com/charcoalphp/property)The model metadata layer.[`queue`](packages/queue)[charcoal/queue](https://github.com/charcoalphp/queue)Provides support for building queues.[`translator`](packages/translator)[charcoal/translator](https://github.com/charcoalphp/translator)Provides support for internationalization, based on [Symfony](https://github.com/symfony/translation).[`ui`](packages/ui)[charcoal/ui](https://github.com/charcoalphp/ui)Provides layout tools (dashboards, layouts, forms, menus,…).[`user`](packages/user)[charcoal/user](https://github.com/charcoalphp/user)The user modeling, authentication, and authorization layer.[`view`](packages/view)[charcoal/view](https://github.com/charcoalphp/view)The view layer with support for [Mustache](https://github.com/bobthecow/mustache.php), [Twig](https://github.com/twigphp/Twig),…Installation
------------

[](#installation)

The preferred (and only supported) method is with Composer:

```
composer require charcoal/charcoal
```

To start from a working skeleton:

```
composer create-project charcoal/boilerplate
```

### Standalone packages

[](#standalone-packages)

The Charcoal framework is split into standalone packages which can be used independently. For example, a project might not need an administration panel, a queue system, or to send emails.

```
composer require charcoal/app charcoal/api custom/admin
```

### Migrate a project to `charcoal/charcoal`

[](#migrate-a-project-to-charcoalcharcoal)

The following will aide with converting a project from `locomotivemtl/charcoal-*` to `charcoal/*`.

> ℹ️ Previously all core packages maintained their own version numbering independently.
>
> The monorepo framework uses a shared version number for all core packages for consistent and expected interoperability.

> ℹ️ The contrib packages continue to maintain their existing independent version numbering.

 Option A — If you want to replace all packages with the full-stack framework package:1. Remove requirements for core packages (`locomotivemtl/charcoal-*`) in your `composer.json` file.
2. Replace requirements for contrib packages (`locomotivemtl/charcoal-contrib-*`), in your `composer.json` file, with equivalents from [`charcoal/contrib-*`](https://github.com/charcoalphp).
3. Run `composer require charcoal/charcoal` to install the framework.
4. Run `composer update` to ensure all requirements are up-to-date.
5. Run the following migration script:

    ```
    ./vendor/charcoal/charcoal/build/script/migrate-project
    ```

    The `migrate-project` script will update all metadata paths in your project's configuration files. Afterwards, it will edit or create a `.env` environment variable file with the key `PACKAGES_PATH` set to: `vendor/charcoal/charcoal/packages`.

    This allows the `%packages.path%` string template to expand to the packages location within `charcoal/charcoal`, otherwise it will lead in the `vendor`directory.

 Option B — If you want to replace all packages with new standalone packages:1. Replace requirements for core packages (`locomotivemtl/charcoal-*`), in your `composer.json` file.
2. Replace requirements for contrib packages (`locomotivemtl/charcoal-contrib-*`), in your `composer.json` file, with equivalents from [`charcoal/contrib-*`](https://github.com/charcoalphp).
3. Run `composer require charcoal/config charcoal/core…` to install the packages.
4. Run `composer update` to ensure all requirements are up-to-date.
5. Replace occurrences of `vendor/locomotivemtl/charcoal-*` in your configuration files with `vendor/charcoal/*`.

### Dependencies

[](#dependencies)

#### ⚠️ Required

[](#️-required)

- [PHP](https://php.net) 7.4 or 8.0

⚙️ Configuration
----------------

[](#️-configuration)

\[TODO\]

Usage
-----

[](#usage)

\[TODO\]

Development
-----------

[](#development)

Development is made in a seperate branch from the `main` branch.

> ⚠️ The `main` branch is protected and doesn't allow pushing changes directly into.

To install the development environment:

```
composer install
```

To run the scripts (phplint, phpcs, and phpunit):

```
composer test
```

### Commit message format

[](#commit-message-format)

Charcoal uses [semantic-release](https://github.com/semantic-release/semantic-release) to handle the release process.

It uses the commit messages to determine the consumer impact of changes in the codebase. Following formalized conventions for commit messages, [semantic-release](https://github.com/semantic-release/semantic-release) automatically determines the next [Semantic Version](https://semver.org)number, generates a changelog, and publishes the release.

The current setup uses the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. You can consult it for further information.

This repository is [Commitizen](https://github.com/commitizen/cz-cli) friendly and is configured to use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, therfore you can install it globally to ease the process of writting commits.

Alternatively, there is some code editor plugins that can help with the creation of conventional commits:

- `vscode`
    - [VSCode Conventional Commits](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits#:~:text=You%20can%20access%20VSCode%20Conventional,on%20the%20Source%20Control%20menu.)
- `phpstrom`
    - [Conventional Commit](https://plugins.jetbrains.com/plugin/13389-conventional-commit)
    - [Git Commit Template](https://plugins.jetbrains.com/plugin/9861-git-commit-template)

Here is an example of release types based on some commit messages:

- Patch (Fix) release:

    ```
    fix(pencil): stop graphite breaking when too much pressure applied
    ```
- Minor (Feature) release:

    ```
    feat(pencil): add 'graphiteWidth' option
    ```
- Major (Breaking) release:

    ```
    perf(pencil): remove graphiteWidth option

    BREAKING CHANGE: The graphiteWidth option has been removed.
    The default graphite width of 10mm is always used for performance reasons.
    ```

    > ✍🏻 Note that the `BREAKING CHANGE: ` token must be in the foot of the commit.

### Development guidelines

[](#development-guidelines)

Development should be branch-based and commit messages should following Conventional Commits.

StepsNotes1. Branch from `main` or checkout `develop`Make sure the `develop` branch is up to date with `main`. You should favor a new branch if the needed work time is not short. On a personal branch, favor using the `rebase` method to keep up to date with the `main` branch2. Do your thingWrite some code3. Commit your changes using the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standardYou can use [Commitizen](https://github.com/commitizen/cz-cli) or a code editor plugin to help with this process. See the [Commit message format](#commit-message-format) section for more information.4. Push to a remote branch and run the `./create-pr` script.Using the `./create-pr` to script to create a PR is not mandatory. You could always create it manually, but the script will be faster, generates a changelog message and assigns a reviewer from the [@charcoalphp/reviewers](https://github.com/orgs/charcoalphp/teams/reviewers)5. Wait for a review and a merge to happenDrink ☕️ and eat 🍕6. After the merge is done, github workflows will handle the release process, tagging, updating dependencies and updatting the changelog.Good Job ! 🤘### Maintenance and automations

[](#maintenance-and-automations)

Symplify's [MonorepoBuilder](https://github.com/symplify/monorepo-builder) is used to handle the conformity between the core repo and it's packages. It will sync `composer.json`files and packages versions.

\[TODO\] Semantic release config in .releaserc

\[TODO\] [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)

\[TODO\] [Commitizen](https://github.com/commitizen/cz-cli)

### Development Dependencies

[](#development-dependencies)

- [symplify/monorepo-builder](https://github.com/symplify/monorepo-builder)
    - Keeps packages versions in sync.
    - Config is located in [**monorepo-builder**](monorepo-builder.php). It allows to define more dependencies
- [semantic-release](https://github.com/semantic-release/semantic-release)
    - Handle the release process from a [Github action](https://github.com/cycjimmy/semantic-release-action).

### Development History

[](#development-history)

This monorepo was created with a many to mono aproach using this guide and tool:

- [hraban/tomono](https://github.com/hraban/tomono)

### Github Actions

[](#github-actions)

ActionsTriggerDescription[Release](.github/workflows/release.yml)Push on supported branchesTrigger a Github release using [semantic-release](https://github.com/marketplace/actions/action-for-semantic-release)[Split Monorepo](.github/workflows/split_monorepo.yml)Release on `main`The split action splits the packages into individual repositories. Only triggered when a tag is pushed. Based on [symplify/monorepo-split-github-action](https://github.com/symplify/monorepo-split-github-action)[Update Changelog](.github/workflows/update-changelog.yml)Release on `main`Uses [changelog-updater-action](https://github.com/stefanzweifel/changelog-updater-action) to update the changelog of the `main` branch### Scripts

[](#scripts)

#### **create-pr**

[](#create-pr)

This script streamlines the process of creating a Pull Request. When your branch is ready to be pulled into the `main` or another `[target]` branch, this tool will generate it for you, request review form [@charcoalphp/reviewers](https://github.com/orgs/charcoalphp/teams/reviewers) and add a beautiful and readable release note generated from the differences between the two breanches.

Documentation

```
Description
  Create a pull request on the github repository on the requested branch.
  Default branch: main

Usage
  ./create-pr

Options
  -b, --base          The base branch to merge into for the pull request. [Default: main]
  -h, --head          The branch to compare against the base branch. [Default: The current branch]
```

Example

```
# target: the target branch for the pull request. Defaults to [main]
./create-pr -b main -h user:feat-branch
```

#### **create-release-notes** (*optional tool*)

[](#create-release-notes-optional-tool)

This script generates release notes on request, returning a changelog based on the requested `range of commits` or `branches`.

Documentation:

```
./build/script/create-release-notes --help
```

Example:

```
./build/script/create-release-notes -g --from main
```

Output:

> ## Changes:
>
> [](#changes)
>
> ### Features
>
> [](#features)
>
> - **create-pr:** add a script to trigger a pull request on the remote ([3016115](https://github.com/charcoalphp/charcoal/commit/3016115d4f7c919261c54e3a17ae6c36552e532a))
>
> ### Bug Fixes
>
> [](#bug-fixes)
>
> - **create-pr:** remove Personal access token from script and replace with `$GITHUB_TOKEN` instead ([f2aaac6](https://github.com/charcoalphp/charcoal/commit/f2aaac6dbd630f0f8fa759e49f9f41c957e3868a))
> - **package:** add missing semantic-release plugin ([59bd1b1](https://github.com/charcoalphp/charcoal/commit/59bd1b1798e4e7b6bf874c7ba8ecbae19d76342b))

Contributing
------------

[](#contributing)

Everyone interacting with Charcoal is expected to follow the [code of conduct](https://github.com/charcoalphp/.github/blob/main/CODE_OF_CONDUCT.md).

Please see our [contribution guide](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)on how to contribute to Charcoal.

If you are tying to report a possible security vulnerability in Charcoal, please see our [security policy](https://github.com/charcoalphp/charcoal/security/policy) for more information.

✍🏻 Authors
----------

[](#-authors)

- [Locomotive](https://locomotive.ca) 🚂
- [Mathieu Ducharme](mailto:mat@locomotive.ca) 👨🏻‍💻
- [Chauncey McAskill](mailto:chauncey@locomotive.ca) 👨🏻‍💻
- [Joel Alphonso](mailto:joel@locomotive.ca) 👨🏻‍💻
- [Dominic Lord](mailto:dom@locomotive.ca) 👨🏻‍💻
- [Benjamin Roch](mailto:ben@locomotive.ca) 👨🏻‍💻

🎉 Contributors
--------------

[](#-contributors)

[![List of contributors](https://camo.githubusercontent.com/c2a6b1dc3395a9bac80a6a53f693d0620ca29504bbec88daa38b14b61e5ce2f4/68747470733a2f2f636f6e747269622e726f636b732f696d6167653f7265706f3d63686172636f616c7068702f63686172636f616c)](https://github.com/charcoalphp/charcoal/graphs/contributors)

Made with [contrib.rocks](https://contrib.rocks).

Changelog
---------

[](#changelog)

View [CHANGELOG](CHANGELOG.md).

The changelog is compliant with [*Keep a Changelog*](https://keepachangelog.com/en/1.0.0/) and is autogenerated from autoreleases.

License
-------

[](#license)

Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance50

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity70

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 ~11 days

Recently: every ~113 days

Total

96

Last Release

397d ago

Major Versions

v1.3.4 → v2.0.02022-06-08

v2.3.0 → v3.0.02022-07-20

v3.1.7 → v4.0.02022-09-21

v4.1.0 → v5.0.02024-03-13

### Community

Maintainers

![](https://www.gravatar.com/avatar/f3f29e38395113e2400bdd7e51bea982b17f120d4d5a53d4473b53118ee46f8d?d=identicon)[JoelAlphonso](/maintainers/JoelAlphonso)

---

Top Contributors

[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (2305 commits)")[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (2278 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (1036 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (322 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (283 commits)")[![semantic-release-bot](https://avatars.githubusercontent.com/u/32174276?v=4)](https://github.com/semantic-release-bot "semantic-release-bot (74 commits)")[![veve40](https://avatars.githubusercontent.com/u/7537381?v=4)](https://github.com/veve40 "veve40 (68 commits)")[![hum-n](https://avatars.githubusercontent.com/u/4596862?v=4)](https://github.com/hum-n "hum-n (31 commits)")[![charcoal-butler[bot]](https://avatars.githubusercontent.com/in/214014?v=4)](https://github.com/charcoal-butler[bot] "charcoal-butler[bot] (29 commits)")[![losted](https://avatars.githubusercontent.com/u/165665?v=4)](https://github.com/losted "losted (23 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)")[![pascalrioux](https://avatars.githubusercontent.com/u/36555872?v=4)](https://github.com/pascalrioux "pascalrioux (1 commits)")

---

Tags

charcoalcms-frameworkmonorepophpphp7php8frameworkcmscharcoal

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/locomotivemtl-charcoal-charcoal/health.svg)

```
[![Health](https://phpackages.com/badges/locomotivemtl-charcoal-charcoal/health.svg)](https://phpackages.com/packages/locomotivemtl-charcoal-charcoal)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.6k509.9M17.0k](/packages/laravel-framework)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[silverstripe/framework

The SilverStripe framework

7213.5M2.5k](/packages/silverstripe-framework)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)