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
  • Development dependencies
  • Continuous Integration
  • Coding Style
  • Authors

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

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