https://github.com/charcoalphp/user
[READ-ONLY] User definition, authentication and authorization
https://github.com/charcoalphp/user
authentication authorization charcoal php read-only-repository user
Last synced: 11 months ago
JSON representation
[READ-ONLY] User definition, authentication and authorization
- Host: GitHub
- URL: https://github.com/charcoalphp/user
- Owner: charcoalphp
- License: mit
- Created: 2022-06-21T15:45:47.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-13T15:05:17.000Z (over 2 years ago)
- Last Synced: 2025-06-02T17:28:37.601Z (about 1 year ago)
- Topics: authentication, authorization, charcoal, php, read-only-repository, user
- Language: PHP
- Homepage: https://github.com/charcoalphp/charcoal
- Size: 198 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Charcoal User
=============
The User package provides abstract tools for defining user models, authenticating and authorizating users from an integration with [Laminas Permissions ACL](https://github.com/laminas/laminas-permissions-acl).
## Installation
```shell
composer require charcoal/user
```
## Overview
### 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 `charcoal/object`), which extends `\Charcoal\Model\ModelInterface` (from `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
TODO
### 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 `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 Charcoal\User\Acl\Manager as AclManager;
use Laminas\Permissions\Acl\Acl;
use Laminas\Permissions\Acl\Resource\GenericResource as AclResource;
$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' ]);
```
## Resources
* [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)
* [Report issues](https://github.com/charcoalphp/charcoal/issues) and
[send pull requests](https://github.com/charcoalphp/charcoal/pulls)
in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)