{"id":19110176,"url":"https://github.com/locomotivemtl/charcoal-user","last_synced_at":"2025-09-07T22:38:04.802Z","repository":{"id":62518578,"uuid":"79298662","full_name":"locomotivemtl/charcoal-user","owner":"locomotivemtl","description":"User definition, authentication and authorization","archived":false,"fork":false,"pushed_at":"2022-05-06T20:26:10.000Z","size":182,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-06-30T18:50:22.471Z","etag":null,"topics":["authentication","authorization","charcoal","php","user"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/locomotivemtl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-18T03:17:41.000Z","updated_at":"2022-05-06T20:04:35.000Z","dependencies_parsed_at":"2022-11-02T13:30:53.618Z","dependency_job_id":null,"html_url":"https://github.com/locomotivemtl/charcoal-user","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/locomotivemtl/charcoal-user","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-user","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-user/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-user/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-user/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locomotivemtl","download_url":"https://codeload.github.com/locomotivemtl/charcoal-user/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Fcharcoal-user/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274107704,"owners_count":25223451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","charcoal","php","user"],"created_at":"2024-11-09T04:24:00.284Z","updated_at":"2025-09-07T22:38:04.780Z","avatar_url":"https://github.com/locomotivemtl.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal User\n=============\n\nUser defintion (as Charcoal Model), authentication and authorization (with Laminas ACL).\n\n\n# Table of content\n-   [How to install](#how-to-install)\n    -   [Dependencies](#dependencies)\n-   [The User object](#the-user-object)\n-   [Authentication](#authentication)\n-   [Authorization](#authorization)\n-   [Development](#development)\n    -   [Development dependencies](#development-dependencies)\n    -   [Continuous Integration](#continuous-integration)\n    -   [Coding Style](#coding-style)\n    -   [Authors](#authors)\n\n# How to install\n\nThe preferred (and only supported) way of installing _charcoal-user_ is with **composer**:\n\n```shell\n★ composer require locomotivemtl/charcoal-user\n```\n\n## Dependencies\n\n- PHP 7.1+\n- `laminas/laminas-permissions-acl`\n- `locomotivemtl/charcoal-object`\n\n# The User object\n\nAt 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`).\n\nThe preferred way of using this module is by defining your own User class in your project and extending the provided `\\Charcoal\\User\\AbstractUser` class.\n\nFor quick prototypes or small projects, a full concrete class is provided as `\\Charcoal\\User\\GenericUser`.\n\n## User properties\n\n| Property                  | Type        | Default     | Description |\n| ------------------------- | ----------- | ----------- | ----------- |\n| **username**              | `string`    | `true`      | …           |\n| **password**              | `string`    | `null`      | …           |\n| **email**                 | `string`    | `null`      | …           |\n| **roles**                 | `string[]`  | `[]`        | ACL roles, which define user permissions. |\n| **last\\_login\\_date**     | `date-time` | `null`      | …           |\n| **last\\_login\\_ip**       | `string`    | `''`        | …           |\n| **last\\_password\\_date**  | `date-time` | `null`      | …           |\n| **last\\_password\\_ip**    | `string`    | `''`        | …           |\n| **login\\_token**          | `string`    | `null`      | …           |\n\n\u003e Note that the `key` of the User is the `username`. Therefore, `id()` returns the username. It must be unique.\n\n**Properties inherited from `Content-Interface`:**\n\n| Property                  | Type        | Default     | Description |\n| ------------------------- | ----------- | ----------- | ----------- |\n| **active**                | `boolean`   | `true`      | …           |\n| **position**              | `number`    | `null`      | …           |\n| **created**               | `date-time` | `null`      | …           |\n| **created\\_by**           | `string`    | `''`        | …           |\n| **last\\_modified**        | `date-time` | `null`      | …           |\n| **last\\_modified\\_by**    | `string`    | `''`        | …           |\n\n# Authentication\n\n...\n\n## Authentication Examples\n\n...\n\n# Authorization\n\nUser 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.\n\nThere 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**.\n\n## ACL Configuration\n\nTo set up ACL, it is highly recommended to use the `\\Charcoal\\User\\Acl\\Manager`.\n\n## ACL Example\n\n```json\n{\n    \"acl\": {\n        \"permissions\": {\n            \"superuser\": {\n                \"superuser\": true\n            },\n            \"author\": {\n                \"allowed\": {},\n                \"denied\": {}\n            }\n        }\n    }\n}\n```\n\n```php\nuse Laminas\\Permissions\\Acl\\Acl;\nuse Laminas\\Permissions\\Acl\\Resource\\GenericResource as AclResource;\n\n// Dependencies from `charcoal-user`\nuse Charcoal\\User\\Acl\\Manager as AclManager;\n\n$acl = new Acl();\n\n // Add resource for ACL\n$acl-\u003eaddResource(new AclResource($resourceName));\n\n$aclManager = new AclManager([\n    'logger' =\u003e $logger,\n]);\n$aclManager-\u003eloadPermissions($acl, $config['acl.permissions'], $resourceName);\n\n$authorizer = new Authorizer([\n    'logger'   =\u003e $logger,\n    'acl'      =\u003e $acl,\n    'resource' =\u003e $resourceName,\n]);\n\n$isAllowed = $authorizer-\u003euserAllowed($user, [ 'permssion' ]);\n```\n\n# Development\n\nTo install the development environment:\n\n```shell\n★ composer install --prefer-source\n```\n\nTo run the scripts (phplint, phpcs and phpunit):\n\n```shell\n★ composer test\n```\n\n## API documentation\n\n-   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/)\n-   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)\n\n## Development dependencies\n\n-   `phpunit/phpunit`\n-   `squizlabs/php_codesniffer`\n-   `satooshi/php-coveralls`\n\n## Continuous Integration\n\n| Service | Badge | Description |\n| ------- | ----- | ----------- |\n| [Travis](https://travis-ci.org/locomotivemtl/charcoal-user) | [![Build Status](https://travis-ci.org/locomotivemtl/charcoal-user.svg?branch=master)](https://travis-ci.org/locomotivemtl/charcoal-user) | Runs code sniff check and unit tests. Auto-generates API documentation. |\n| [Scrutinizer](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-user/) | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-user/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-user/?branch=master) | Code quality checker. Also validates API documentation quality. |\n| [Coveralls](https://coveralls.io/github/locomotivemtl/charcoal-user) | [![Coverage Status](https://coveralls.io/repos/github/locomotivemtl/charcoal-user/badge.svg?branch=master)](https://coveralls.io/github/locomotivemtl/charcoal-user?branch=master) | Unit Tests code coverage. |\n| [Sensiolabs](https://insight.sensiolabs.com/projects/533b5796-7e69-42a7-a046-71342146308a) | [![SensioLabsInsight](https://insight.sensiolabs.com/projects/5b05fad5-5e2d-41d3-acd3-12822b354892/mini.png)](https://insight.sensiolabs.com/projects/5b05fad5-5e2d-41d3-acd3-12822b354892) | Another code quality checker, focused on PHP. |\n\n## Coding Style\n\nThe charcoal-user module follows the Charcoal coding-style:\n\n-   [_PSR-1_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)\n-   [_PSR-2_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)\n-   [_PSR-4_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md), autoloading is therefore provided by _Composer_.\n-   [_phpDocumentor_](http://phpdoc.org/) comments.\n-   Read the [phpcs.xml](phpcs.xml) file for all the details on code style.\n\n\u003e Coding style validation / enforcement can be performed with `composer phpcs`. An auto-fixer is also available with `composer phpcbf`.\n\n\n\u003e This module should also throw no error when running `phpstan analyse -l7 src/` 👍.\n\n# Authors\n\n-   Mathieu Ducharme, mat@locomotive.ca\n-   Chauncey McAskill\n-   [Locomotive, a Montreal Web agency](https://locomotive.ca)\n\n# License\n\nCharcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocomotivemtl%2Fcharcoal-user","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocomotivemtl%2Fcharcoal-user","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocomotivemtl%2Fcharcoal-user/lists"}