User definition, authentication and authorization.


User defintion (as Charcoal Model), authentication and authorization (with Laminas ACL).

Table of content

How to install

The preferred (and only supported) way of installing charcoal-user is with composer:

★ composer require locomotivemtl/charcoal-user


  • PHP 7.1+
  • laminas/laminas-permissions-acl
  • locomotivemtl/charcoal-object

The User object

At the core of this module is the definition of a "User" object. The contract can be found as \Charcoal\User\UserInterface. This interfaces extends \Charcoal\Object\ContentInterface (from locomotivemtl/charcoal-object), which extends \Charcoal\Model\ModelInterface (from locomotivemtl/charcoal-core).

The preferred way of using this module is by defining your own User class in your project and extending the provided \Charcoal\User\AbstractUser class.

For quick prototypes or small projects, a full concrete class is provided as \Charcoal\User\GenericUser.

User properties

Property Type Default Description
username string true
password string null
email string null
roles string[] [] ACL roles, which define user permissions.
last_login_date date-time null
last_login_ip string ''
last_password_date date-time null
last_password_ip string ''
login_token string null

Note that the key of the User is the username. Therefore, id() returns the username. It must be unique.

Properties inherited from Content-Interface:

Property Type Default Description
active boolean true
position number null
created date-time null
created_by string ''
last_modified date-time null
last_modified_by string ''



Authentication Examples



User authorization is managed with a role-based Access Control List (ACL). Internally, it uses laminas/laminas-permissions-acl for the ACL logic. It is recommended to read the Laminas ACL documentation to learn more about how it all works.

There are 2 main concepts that must be managed, either from JSON config files or in the database (which works well with locomotivemtl/charcoal-admin), roles and permissions.

ACL Configuration

To set up ACL, it is highly recommended to use the \Charcoal\User\Acl\Manager.

ACL Example

    "acl": {
        "permissions": {
            "superuser": {
                "superuser": true
            "author": {
                "allowed": {},
                "denied": {}
use Laminas\Permissions\Acl\Acl;
use Laminas\Permissions\Acl\Resource\GenericResource as AclResource;

// Dependencies from `charcoal-user`
use Charcoal\User\Acl\Manager as AclManager;

$acl = new Acl();

 // Add resource for ACL
$acl->addResource(new AclResource($resourceName));

$aclManager = new AclManager([
    'logger' => $logger,
$aclManager->loadPermissions($acl, $config['acl.permissions'], $resourceName);

$authorizer = new Authorizer([
    'logger'   => $logger,
    'acl'      => $acl,
    'resource' => $resourceName,

$isAllowed = $authorizer->userAllowed($user, [ 'permssion' ]);


To install the development environment:

★ composer install --prefer-source

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

★ composer test

API documentation

Development dependencies

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

Continuous Integration

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

Coding Style

The charcoal-user module follows the Charcoal coding-style:

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

This module should also throw no error when running phpstan analyse -l7 src/ 👍.



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