README

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

Table of content

How to install
- Dependencies
The User object
Authentication
Authorization
Development

How to install

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

★ composer require locomotivemtl/charcoal-user

Dependencies

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

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

Properties inherited from Content-Interface:

Authentication

...

Authentication Examples

...

Authorization

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

Development

To install the development environment:

★ composer install --prefer-source

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

★ composer test

API documentation

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

Development dependencies

phpunit/phpunit
squizlabs/php_codesniffer
satooshi/php-coveralls

Continuous Integration

Coding Style

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

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.

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

Authors

Mathieu Ducharme, mat@locomotive.ca
Chauncey McAskill
Locomotive, a Montreal Web agency

License

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

locomotivemtl / charcoal-user

Maintainers

Details