by Locomotive 🚂

---

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

Core packages can be found in the packages directory.

Directory	Distribution	Description
admin	charcoal/admin	The administration dashboard for Charcoal.
app	charcoal/app	The web application layer (container, routing, controllers,…), based on Slim.
attachment	charcoal/attachment	Provides support for working with relationships between models.
cache	charcoal/cache	The cache layer, based on Stash.
cms	charcoal/cms	Provides content management system (CMS) tools and extensions.
config	charcoal/config	The base configuration and entity layer most packages build upon.
core	charcoal/core	The model, repository, and database layer.
email	charcoal/email	Provides support for sending emails, based on PHPMailer.
factory	charcoal/factory	Provides support for object creation (factory, builder, class resolution,…).
image	charcoal/image	Provides support for image handling and manipulation.
object	charcoal/object	Provides support for advanced modeling (routable, revisionable, authoriship,…).
property	charcoal/property	The model metadata layer.
queue	charcoal/queue	Provides support for building queues.
translator	charcoal/translator	Provides support for internationalization, based on Symfony.
ui	charcoal/ui	Provides layout tools (dashboards, layouts, forms, menus,…).
user	charcoal/user	The user modeling, authentication, and authorization layer.
view	charcoal/view	The view layer with support for Mustache, Twig,…

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

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

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-*.

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-*.
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

⚠️ Required

• PHP 7.4 or 8.0

⚙️ Configuration

[TODO]

Usage

[TODO]

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

Charcoal uses 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 automatically determines the next Semantic Version number, generates a changelog, and publishes the release.

The current setup uses the Conventional Commits for commit messages. You can consult it for further information.

This repository is Commitizen friendly and is configured to use the Conventional Commits 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
• phpstrom
  • Conventional Commit
  • 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 should be branch-based and commit messages should following Conventional Commits.

Steps	Notes
1. 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 branch
2. Do your thing	Write some code
3. Commit your changes using the Conventional Commits standard	You can use Commitizen or a code editor plugin to help with this process. See the 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
5. Wait for a review and a merge to happen	Drink ☕️ 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

Symplify's MonorepoBuilder 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

[TODO] Commitizen

Development Dependencies

• symplify/monorepo-builder
  • Keeps packages versions in sync.
  • Config is located in monorepo-builder. It allows to define more dependencies
• semantic-release
  • Handle the release process from a Github action.

Development History

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

• hraban/tomono

Github Actions

Actions	Trigger	Description
Release	Push on supported branches	Trigger a Github release using semantic-release
Split Monorepo	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
Update Changelog	Release on main	Uses changelog-updater-action to update the changelog of the main branch

Scripts

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 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)

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:

Features

• create-pr: add a script to trigger a pull request on the remote (3016115)

Bug Fixes

• create-pr: remove Personal access token from script and replace with $GITHUB_TOKEN instead (f2aaac6)
• package: add missing semantic-release plugin (59bd1b1)

Contributing

Everyone interacting with Charcoal is expected to follow the code of conduct.

Please see our contribution guide on how to contribute to Charcoal.

If you are tying to report a possible security vulnerability in Charcoal, please see our security policy for more information.

✍🏻 Authors

• Locomotive 🚂
• Mathieu Ducharme 👨🏻‍💻
• Chauncey McAskill 👨🏻‍💻
• Joel Alphonso 👨🏻‍💻
• Dominic Lord 👨🏻‍💻
• Benjamin Roch 👨🏻‍💻

🎉 Contributors

Made with contrib.rocks.

Changelog

View CHANGELOG.

The changelog is compliant with Keep a Changelog and is autogenerated from autoreleases.

License

Charcoal is licensed under the MIT license. See LICENSE for details.