Charcoal User

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

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

...

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.