User definition, authentication and authorization.


The User package provides abstract tools for defining user models, authenticating and authorizating users from an integration with Laminas Permissions ACL.


composer require charcoal/user


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 charcoal/object), which extends \Charcoal\Model\ModelInterface (from 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 ''




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 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 Charcoal\User\Acl\Manager as AclManager;
use Laminas\Permissions\Acl\Acl;
use Laminas\Permissions\Acl\Resource\GenericResource as AclResource;

$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' ]);