locomotivemtl/charcoal-user

User definition, authentication and authorization.

Charcoal User

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

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:, _(*2)

★ 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)., _(*3)

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., _(*4)

For quick prototypes or small projects, a full concrete class is provided as \Charcoal\User\GenericUser., _(*5)

User properties

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

Properties inherited from Content-Interface:, _(*7)

Authentication

..., _(*8)

Authentication Examples

..., _(*9)

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., _(*10)

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., _(*11)

ACL Configuration

To set up ACL, it is highly recommended to use the \Charcoal\User\Acl\Manager., _(*12)

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:, _(*13)

★ composer install --prefer-source

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

★ 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:, _(*15)

• 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., _(*16)

This module should also throw no error when running phpstan analyse -l7 src/ 👍., _(*17)

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., _(*18)