https://github.com/locomotivemtl/charcoal-user
User definition, authentication and authorization
https://github.com/locomotivemtl/charcoal-user
authentication authorization charcoal php user
Last synced: 10 months ago
JSON representation
User definition, authentication and authorization
- Host: GitHub
- URL: https://github.com/locomotivemtl/charcoal-user
- Owner: locomotivemtl
- License: mit
- Created: 2017-01-18T03:17:41.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-05-06T20:26:10.000Z (about 4 years ago)
- Last Synced: 2025-06-30T18:50:22.471Z (12 months ago)
- Topics: authentication, authorization, charcoal, php, user
- Language: PHP
- Size: 178 KB
- Stars: 0
- Watchers: 13
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Charcoal User
=============
User defintion (as Charcoal Model), authentication and authorization (with Laminas ACL).
# Table of content
- [How to install](#how-to-install)
- [Dependencies](#dependencies)
- [The User object](#the-user-object)
- [Authentication](#authentication)
- [Authorization](#authorization)
- [Development](#development)
- [Development dependencies](#development-dependencies)
- [Continuous Integration](#continuous-integration)
- [Coding Style](#coding-style)
- [Authors](#authors)
# How to install
The preferred (and only supported) way of installing _charcoal-user_ is with **composer**:
```shell
★ 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`](https://github.com/laminas/laminas-permissions-acl) for the ACL logic. It is recommended to read the [Laminas ACL documentation](https://docs.laminas.dev/laminas-permissions-acl/) 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
```json
{
"acl": {
"permissions": {
"superuser": {
"superuser": true
},
"author": {
"allowed": {},
"denied": {}
}
}
}
}
```
```php
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:
```shell
★ composer install --prefer-source
```
To run the scripts (phplint, phpcs and phpunit):
```shell
★ composer test
```
## API documentation
- The auto-generated `phpDocumentor` API documentation is available at [https://locomotivemtl.github.io/charcoal-user/docs/master/](https://locomotivemtl.github.io/charcoal-user/docs/master/)
- The auto-generated `apigen` API documentation is available at [https://codedoc.pub/locomotivemtl/charcoal-user/master/](https://codedoc.pub/locomotivemtl/charcoal-user/master/index.html)
## Development dependencies
- `phpunit/phpunit`
- `squizlabs/php_codesniffer`
- `satooshi/php-coveralls`
## Continuous Integration
| Service | Badge | Description |
| ------- | ----- | ----------- |
| [Travis](https://travis-ci.org/locomotivemtl/charcoal-user) | [](https://travis-ci.org/locomotivemtl/charcoal-user) | Runs code sniff check and unit tests. Auto-generates API documentation. |
| [Scrutinizer](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-user/) | [](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-user/?branch=master) | Code quality checker. Also validates API documentation quality. |
| [Coveralls](https://coveralls.io/github/locomotivemtl/charcoal-user) | [](https://coveralls.io/github/locomotivemtl/charcoal-user?branch=master) | Unit Tests code coverage. |
| [Sensiolabs](https://insight.sensiolabs.com/projects/533b5796-7e69-42a7-a046-71342146308a) | [](https://insight.sensiolabs.com/projects/5b05fad5-5e2d-41d3-acd3-12822b354892) | Another code quality checker, focused on PHP. |
## Coding Style
The charcoal-user module follows the Charcoal coding-style:
- [_PSR-1_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)
- [_PSR-2_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
- [_PSR-4_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md), autoloading is therefore provided by _Composer_.
- [_phpDocumentor_](http://phpdoc.org/) comments.
- Read the [phpcs.xml](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](https://locomotive.ca)
# License
Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.