locomotivemtl/charcoal-city-boilerplate

Boilerplate, a Charcoal City Project

Charcoal City Boilerplate

The goal of this project is to provide a fully working "boilerplate" (empty skeleton project) for a City project using the Charcoal framework. The installation is fully automated., _(*1)

Table of Content

• How to Install
  • 1. Create / clone the city boilerplate
  • 2. Installation process
  • 3. Ready to go
  • 4. Basic debug
  • 5. Set up charcoal-admin
• Going further
  • More config customizations
  • Creating a custom template
  • Using objects
  • Customizing the backend
• Dependencies and requirements
  • The charcoal modules
• What's inside the Boilerplate
• Development
  • Development dependencies
  • Continuous Integration
  • Coding Style
  • Authors
  • Changelog

How to Install

To start a Charcoal project with this Boilerplate, simply:, _(*2)

1. Create / clone the city boilerplate

$ composer create-project locomotivemtl/charcoal-city-boilerplate [path] --prefer-source -s dev

The --prefer-source argument ensure you have the possibility to edit vendors while the -s dev argument specifies composer to user the latest development boilerplate., _(*3)

About the Document Root, _(*4)

👉 The project should not be cloned directly in a web-accessible directory. The web server should be configured to serve the www/ folder directly. The other folders (vendor/, src/, templates/, metadata/, config/, etc.) should therefore not be available from the web server (kept outside the document root)., _(*5)

2. Installation process

Create-project setup

• Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]?
  • Yes. This will remove the charcoal-city-boilerplate repository informations.

Project setup

The project setup uses the given name to rename all files to the currently choosen namespace., _(*6)

Manual call:, _(*7)

$ ./vendor/bin/charcoal city/setup

• What is the name of the project?, _(*8)

  • Could be bascily any valid string that is not charcoal or city which are the 2 already used namespaces.

• What is the namespace of the project?, _(*9)

  • Default will be the name of the project with a capital letter. Everything will be renamed accordingly.

Composer setup

The composer setup updates the composer.json file to match the current project informations., _(*10)

• What is the VCS repository of the project? (let blank to use an already installed VCS), _(*11)

  • The repository in which the project will be held. If specified, the script will ensure to git init and git remote add origin [specified repository]

• What is the project website url? (optional), _(*12)

  • Updates the composer.json file with the given information.

City config script

The city config script generates a database and a config.local.json file matching the given informations., _(*13)

Manual call:, _(*14)

$ ./vendor/bin/charcoal city/config

• Database name (Database will be created or overwritten, let blank to user another database)
  • Database name. If not specified, you will have to manually edit the config.local.json file automatically generated.
• Database username : [default: root]
  • Database username (usually root)
• Database password : [default: '']
  • Database password (default to empty string)
• Database hostname : [default: 127.0.0.1]
  • Database hostname which could be either 127.0.0.1 or localhost.

3. Ready to go

You can now visit the local webpage and access the home template, default news and default events. Depending on your installation, you might have to update the hosts file., _(*15)

4. Basic debug

If you can't see the home page with all these steps successfully completed, make sure you changed the hosts file accordingly. Then, you can manually composer update the project, which will rebuild the autoload and update to the latest package. When all else fails, ask for Joel or Bene., _(*16)

5. Set up charcoal-admin

This step is now completely automated., _(*17)

First, ensure the admin module (the backend) is properly set up and ready:, _(*18)

$ cd vendor/locomotivemtl/charcoal-admin
$ npm install
$ bower install
$ grunt
$ cd -

Then create the first admin user, to be able to login into the backend:, _(*19)

$ ./vendor/bin/charcoal admin/user/create

👉 The ./vendor/bin/charcoal CLI tool, provided by charcoal-app is required to run various scripts, many of which are provided by the charcoal-admin and charcoal-base modules., _(*20)

Point your browser to http://localhost:8080/ and you should see the boilerplate's default home page., _(*21)

, _(*22)

The next step to customize the backend is to configure the main menu, as well as the various, _(*23)

Dependencies and Requirements

• PHP 5.5+
  • ext-json
  • ext-pdo
  • ext-spl
  • ext-mbstring

The Charcoal modules

• charcoal-admin
  • The backend, or control panel.
• charcoal-app
  • App components based on Slim.
• charcoal-base
  • Base objects and behaviors.
• charcoal-cms
  • CMS objects (Section, News, Events, etc.)
• charcoal-core
  • Core objects, Model, Source.
• charcoal-config
  • Base configuration system.
• charcoal-email
  • Email utilities, based on phpmailer.
• charcoal-factory
  • Dynamic objects creation.
• charcoal-image
  • Image manipulation and effects.
• charcoal-property
  • Metadata's properties.
• charcoal-translation
  • Translation utilities.
• charcoal-ui
  • Ui objects (Form, Menu, Dashboard, Layout, etc.)
• charcoal-view
  • View renderer. (mustache, twig, etc.)

Status matrix

| Module | Version | Travis | Scrutinizer | Insights | Coveralls | PHPDoc | ApiGen | | ------------------------ | ------- | ------ | ----------- | -------- | --------- | ------ | ------ | | admin | | | | | | PHPDoc | ApiGen | | app | | | | | | PHPDoc | ApiGen | base | | | | | | PHPDoc | ApiGen | | cms | | | | | | PHPDoc | ApiGen | | config | | | | | | PHPDoc | ApiGen | | core | | | | | | PHPDoc | ApiGen | | email | | | | | | PHPDoc | ApiGen | | factory | | | | | | PHPDoc | ApiGen | | image | | | | | | - | - | | property | | | | | | PHPDoc | ApiGen | | translation | | | | | | - | - | | ui | | | | | | PHPDoc | ApiGen | | view | | | | | | - | - |, _(*24)

What's inside this Boilerplate?

Like all Charcoal projects / modules, the main components are:, _(*25)

• Autoloader
  • Provided by Composer.
• Config
  • As JSON or PHP files in the config/ directory.
  • Use locomotivemtl/charcoal-config
• Front Controller
  • See www/.htaccess and www/index.php for details.
  • Route dispatcher
• Script Controller (Charoal Binary)
  • Installed from charcoal-app as vendor/bin/charcoal.
• PHP scripts
  • PSR-1, PSR2 and PSR-4 compliant scripts are located in src/
  • There are typically 3 types of controllers:
    • Templates
    • Actions
    • Scripts
  • ... 2 types of object
    • Objects based on Content
    • Objects based on UserData
  • ... and all other types of scripts (services, helpers, configs, factories, etc.)
• 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/

Development

To install the development environment:, _(*26)

★ composer install --prefer-source

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

★ composer test

API documentation

• The auto-generated phpDocumentor API documentation is available at https://locomotivemtl.github.io/charcoal-base/docs/master/
• The auto-generated apigen API documentation is available at https://codedoc.pub/locomotivemtl/charcoal-base/master/

Development dependencies

• phpunit/phpunit
• squizlabs/php_codesniffer
• satooshi/php-coveralls

Continuous Integration

Service	Badge	Description
Travis		Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer		Code quality checker. Also validates API documentation quality.
Coveralls		Unit Tests code coverage.
Sensiolabs		Another code quality checker, focused on PHP.

Coding Style

The charcoal-base module follows the Charcoal coding-style:, _(*28)

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• Read the phpcs.xml file for all the details on code style.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf., _(*29)

Authors

• Mathieu Ducharme, mat@locomotive.ca
• Joel Alphonso, joel@locomotive.ca

Changelog

Unreleased, _(*30)