PHPackages                             bishwopl/zf3-circlical-user - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. bishwopl/zf3-circlical-user

ActiveLibrary[Authentication & Authorization](/categories/authentication)

bishwopl/zf3-circlical-user
===========================

Complete user entity, rights, and access module for Laminas

v2.0.1(5y ago)0371MPL-2.0PHPPHP ^7

Since Jul 18Pushed 3y agoCompare

[ Source](https://github.com/bishwopl/zf3-circlical-user)[ Packagist](https://packagist.org/packages/bishwopl/zf3-circlical-user)[ Docs](https://github.com/bishwopl/zf3-circlical-user)[ RSS](/packages/bishwopl-zf3-circlical-user/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (14)Versions (19)Used By (1)

Authentication, Identity, and RBAC for the Laminas Framework
============================================================

[](#authentication-identity-and-rbac-for-the-laminas-framework)

[![Codacy Badge](https://camo.githubusercontent.com/a651a50e91dce1e7a98e745021a7abc830bd072d31cba51d21e34d00a37a7eca/68747470733a2f2f6170702e636f646163792e636f6d2f70726f6a6563742f62616467652f47726164652f6564386537316361366562303466633038306338653634616635313632396239)](https://www.codacy.com/gh/Saeven/zf3-circlical-user/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Saeven/zf3-circlical-user&utm_campaign=Badge_Grade)[![Codacy Badge](https://camo.githubusercontent.com/510eebad58ea68da18c419da4ca189433c1f93531b45349406be1943265959d3/68747470733a2f2f6170702e636f646163792e636f6d2f70726f6a6563742f62616467652f436f7665726167652f6564386537316361366562303466633038306338653634616635313632396239)](https://www.codacy.com/gh/Saeven/zf3-circlical-user/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Saeven/zf3-circlical-user&utm_campaign=Badge_Coverage)[![Latest Stable Version](https://camo.githubusercontent.com/76a63cfc9cc9a487a2976159c16b20ecd16309aaf79510d9c1d47dc1da148354/68747470733a2f2f706f7365722e707567782e6f72672f73616576656e2f7a66332d636972636c6963616c2d757365722f762f737461626c65)](https://packagist.org/packages/saeven/zf3-circlical-user)[![Total Downloads](https://camo.githubusercontent.com/abcc4b4f2f4ae713ea4b6a8b2926961a9f73bec541b4a8eb39b2a0c79679ae00/68747470733a2f2f706f7365722e707567782e6f72672f73616576656e2f7a66332d636972636c6963616c2d757365722f646f776e6c6f616473)](https://packagist.org/packages/saeven/zf3-circlical-user)[![Quality Gate Status](https://camo.githubusercontent.com/030ff17ded5d530e87069e38bdeb49bb601cac3832e44c21aa127ebd3f9e268e/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d53616576656e5f7a66332d636972636c6963616c2d75736572266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/dashboard?id=Saeven_zf3-circlical-user)[![Gitter](https://camo.githubusercontent.com/df9d0c892139a505a554ad3feff70ec53a20705cfc256a23ab2826c5b7237b4a/68747470733a2f2f6261646765732e6769747465722e696d2f67697474657248512f6769747465722e737667)](https://gitter.im/Circlical/zf3-circlical-user?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

Plug and play authentication, roles, resource, and action control for Laminas.

Quickly Installs:

- cookie based authentication (using halite and its authenticated encryption)
- role-based access control (RBAC) with guards at the controller and action level
- user-based access control to complement RBAC
- resource-based permissions, giving you 'resource' and 'verb' control at the role and user level, e.g. (all administrators can 'add' a server, only Pete can 'delete')

You can see it in action, in this [ready-to-use skeleton](https://github.com/Saeven/laminas-mvc-skeleton).

### Missive

[](#missive)

Sure - there are other Authentication, ACL, and User modules out there. This one comes with out-of-the-box support for **Doctrine** - just plug in your user entity and go.

Authentication is persisted using cookies, meaning no session usage at all. This was done because I develop for circumstances where this is preferable, removing any need for complex or error-prone solutions for session management on an EC2 auto-scale group for example.

Lastly, authenticated encryption is handled using the well-trusted [Halite](https://github.com/paragonie/halite), and password hashing is properly done with PHP's new password functions. [Feedback always solicited on r/php.](https://www.reddit.com/r/PHP/comments/4r84jn/need_reviews_of_cookiebased_authentication_service/). If you are a paranoid fellow like me, this library should serve well!

This library works on a deny-first basis. Everything defined by its parts below, are 'allow' grants.

User Authentication
-------------------

[](#user-authentication)

The module provides full identity/auth management, starting at the user-level. A design goal was to connect this to registration or login processes with little more than one-liners.

#### Login

[](#login)

Validate your submitted Login form, and then execute this to get your user through the door:

```
$user = $this->auth()->authenticate( $emailOrUsername, $password );

```

Successful authentication, will drop cookies that satisfy subsequent identity retrieval.

#### Logout

[](#logout)

Trash cookies and regenerate the session key for that user, using this command:

```
 $this->auth()->clearIdentity();

```

Pluggable Deny Strategy
-----------------------

[](#pluggable-deny-strategy)

Someone trying to do something they shouldn't? It's easy to control what happens with a pluggable DenyStrategy. Create a class that implements DenyStrategyInterface and plug it into your config. This module comes with a default **RedirectStrategy** that will send users to a login page, if the problem was that there was no auth, and it wasn't an XHTTP request. Easy to use, you'd configure it like so:

```
'deny_strategy' => [

    'class' => \CirclicalUser\Strategy\RedirectStrategy::class,

    'options' => [
        'controller' => \Application\Controller\LoginController::class,
        'action' => 'index',
    ],
],

```

Writing your own should be very simple, see provided tests.

Pluggable Password Strength Checker
-----------------------------------

[](#pluggable-password-strength-checker)

You can use the built-in support for [paragonie/passwdqc](https://github.com/paragonie/passwdqc) by uncommenting the password\_strength\_checker config key. You can also roll your own if you have more complex needs; uncomment the key and specify your own implementation of [PasswordCheckerInterface](src/CirclicalUser/Provider/PasswordCheckerInterface.php). This will cause the password input routines to throw WeakPasswordExceptions when weak input is received.

Configuration of the password checker can be done two ways:

#### Class without options

[](#class-without-options)

```
'password_strength_checker' => \CirclicalUser\Service\PasswordChecker\Passwdqc::class,

```

#### Class with options

[](#class-with-options)

```
'password_strength_checker' => [
    'implementation' => \CirclicalUser\Service\PasswordChecker\Zxcvbn::class,
    'config' => [
        'required_strength' => 3,
    ],
],

```

Creating Access For Your Users
------------------------------

[](#creating-access-for-your-users)

Your app needs to be modified to create a distinct auth record for each user. It's very simple.

#### create & authenticate

[](#create--authenticate)

During user registration routines, you probably want to create the records and also log them in. To accomplish this, you can use the helper or the 'create' method on AccessService.

From a Controller, you can use the auth plugin:

```
 $this->auth()->create(User $user, string $usernameOrEmail, string $password); // controller helper

```

or, the AuthenticationService:

```
$container->get(AuthenticationService::class)->create($user, $usernameOrEmail, $password);

```

#### create only

[](#create-only)

Otherwise, if you simply want to create a user auth record but not log them in, use:

```
$container->get(AuthenticationService::class)->registerAuthenticationRecord(User $user, string $username, string $password)

```

Roles
-----

[](#roles)

Your users belong to hierarchical roles that are configured in the database. *The default guest user, is group-less.*
Roles are used to restrict access to **controllers**, **actions**, or **resources**.

Guards
------

[](#guards)

Guards are conditions on **controllers** & **actions** -- or **middleware** -- that examine **group** or **user** privileges to permit/decline attempted access. It works very similarly to [BjyAuthorize](https://github.com/bjyoungblood/BjyAuthorize)(a great module I used for years).

Configuring guards is very simple. Your module's config would look like so:

```
 return [
    'circlical' => [
        'user' => [
            'guards' => [
                'ModuleName' => [
                    "controllers" => [
                        \Application\Controller\IndexController::class => [
                            'default' => [], // anyone can access
                        ],
                        \Application\Controller\MemberController::class => [
                            'default' => ['user'], // specific role access
                        ],
                        \Application\Controller\AdminController::class => [
                            'default' => ['admin'],
                            'actions' => [  // action-level guards
                                'list' => [ 'user' ], // role 'user' can access 'listAction' on AdminController
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
 ];

```

If you are defining access for [middleware route definitions](https://docs.zendframework.com/zend-mvc/middleware/#mapping-routes-to-middleware), then you don't need to configure the 'actions' section above. Further, the Module is then ignored, so you can place your middleware handler's class in any module; example:

```
 return [
    'circlical' => [
        'user' => [
            'guards' => [
                'Middleware' => [
                    "controllers" => [
                        \Application\Middleware\MiddlewareHandler::class => [
                            'default' => [], // anyone can access
                        ],
                    ],
                ],
            ],
        ],
    ],
 ];

```

Resources & Permissions
---------------------------

[](#resources--permissions)

Resources can be:

- simple strings, or
- anything you have that implements [ResourceInterface](src/CirclicalUser/Provider/ResourceInterface.php)

Both these usages are valid from a controller:

```
$this->auth()->isAllowed('door','open');

```

or if an object:

```
// server implements ResourceInterface
$server = $serverMapper->get(142);
$this->auth()->isAllowed($server,'shutdown');

```

The AccessService is also similarly usable. See [AccessService tests](bundle/Spec/Service/AccessServiceSpec.php) for more usage examples.

Granting a **role** a **permission** is done through the AccessService

### User Permissions

[](#user-permissions)

You can also give individual users, access to specific actions on resources as well. This library provides **Doctrine** entities and a mapper to make this happen -- but you could wire your own [UserPermissionProviderInterface](src/CirclicalUser/Provider/UserPermissionProviderInterface.php)very easily. In short, this lets the AccessService use the authenticated user to determine whether or not the logged-in individual can perform an action that supersedes what his role permissions otherwise grant. User Permissions are meant to be more permissive, not restrictive.

### User API Tokens

[](#user-api-tokens)

This module also provides a utility with which to generate UserApiToken objects. See tests for usage.

Adding the mapping for this entity to your User entity is very trivial

```
/**
 * @ORM\OneToMany(targetEntity="CirclicalUser\Entity\UserApiToken", mappedBy="user");
 */
private $api_tokens;

```

Pulling a token to perform your own logic with it, is done with UserApiTokenMapper, e.g.

```
$token = $this->userApiTokenMapper->get('d0cad39b-f269-405e-b3f9-d45b349c0587');

```

When it is used/consumed, you can tag it:

```
$token->tagUse();

```

Scope (as defined by your application) is defined with bit flags

```
$token->addScope(FooApi::SCOPE_QUERY);

```

Cookie Security
===============

[](#cookie-security)

You can configure whether or not your cookies should have the secure flag set to 'true' by adjusting the auth/secure\_cookies configuration value. This value accepts a boolean or closure if you need to run a discovery method on your server, perhaps, for example, to check if the current request is coming through SSL.

Installation
============

[](#installation)

- Working with Doctrine? [Click Here](INSTALL_DOCTRINE.md)
- Want to roll your own Providers? [Click Here](INSTALL_CUSTOM.md)

Composer Tune-Ups
=================

[](#composer-tune-ups)

This package's dependency chain depends on `doctrine/doctrine-module`, which in turn depends on `laminas/laminas-cache`.

Laminas cache is wired in a strange way, and might attempt to install a ton of problematic adapters (depending on your PHP version). It is recommended that you use composer's replace to keep that mess out of your application, like so:

```
  "replace": {
    "laminas/laminas-cache-storage-adapter-apc": "*",
    "laminas/laminas-cache-storage-adapter-apcu": "*",
    "laminas/laminas-cache-storage-adapter-blackhole": "*",
    "laminas/laminas-cache-storage-adapter-dba": "*",
    "laminas/laminas-cache-storage-adapter-ext-mongodb": "*",
    "laminas/laminas-cache-storage-adapter-filesystem": "*",
    "laminas/laminas-cache-storage-adapter-memcache": "*",
    "laminas/laminas-cache-storage-adapter-memcached": "*",
    "laminas/laminas-cache-storage-adapter-mongodb": "*",
    "laminas/laminas-cache-storage-adapter-redis": "*",
    "laminas/laminas-cache-storage-adapter-session": "*",
    "laminas/laminas-cache-storage-adapter-wincache": "*",
    "laminas/laminas-cache-storage-adapter-xcache": "*",
    "laminas/laminas-cache-storage-adapter-zend-server": "*",
  },

```

What's more, since you are using this library, you probably aren't using `laminas/laminas-authentication`, which is also installed by doctrine-module. You can go ahead and throw this line into your replace block as well:

```
"laminas/laminas-authentication": "*",

```

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 92.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~104 days

Recently: every ~2 days

Total

16

Last Release

2026d ago

Major Versions

0.0.2 → 1.0.02020-10-14

v1.0.2 → v2.0.02020-10-24

PHP version history (3 changes)0.1.5PHP ^7.0.0

0.2.5PHP ^7.2.0

v1.0.2PHP ^7

### Community

Maintainers

![](https://www.gravatar.com/avatar/f065e591158a458e4a1889d08eb628be8785eaefc4f0fef3ab5e8ab11f44f923?d=identicon)[bishwopl](/maintainers/bishwopl)

---

Top Contributors

[![Saeven](https://avatars.githubusercontent.com/u/887224?v=4)](https://github.com/Saeven "Saeven (273 commits)")[![CreativeNative](https://avatars.githubusercontent.com/u/1124960?v=4)](https://github.com/CreativeNative "CreativeNative (11 commits)")[![Koopzington](https://avatars.githubusercontent.com/u/3015529?v=4)](https://github.com/Koopzington "Koopzington (3 commits)")[![vojtabiberle](https://avatars.githubusercontent.com/u/528942?v=4)](https://github.com/vojtabiberle "vojtabiberle (3 commits)")[![kersten](https://avatars.githubusercontent.com/u/487289?v=4)](https://github.com/kersten "kersten (2 commits)")[![Gamewalker](https://avatars.githubusercontent.com/u/241821?v=4)](https://github.com/Gamewalker "Gamewalker (1 commits)")[![Tigerman55](https://avatars.githubusercontent.com/u/7062093?v=4)](https://github.com/Tigerman55 "Tigerman55 (1 commits)")

---

Tags

authuserauthorizationaclUser managementzf3bjyauthorize

### Embed Badge

![Health badge](/badges/bishwopl-zf3-circlical-user/health.svg)

```
[![Health](https://phpackages.com/badges/bishwopl-zf3-circlical-user/health.svg)](https://phpackages.com/packages/bishwopl-zf3-circlical-user)
```

###  Alternatives

[saeven/zf3-circlical-user

Complete user entity, rights, and access module for Laminas

3718.7k](/packages/saeven-zf3-circlical-user)[kokspflanze/bjy-authorize

Laminas\\Acl based firewall system for Laminas dispatch protection

20178.2k4](/packages/kokspflanze-bjy-authorize)[2amigos/yii2-usuario

Highly customizable and extensible user management, authentication, and authorization Yii2 extension

298275.5k14](/packages/2amigos-yii2-usuario)[saeven/zf3-circlical-autowire

Annotation based routing, and magic Controller creation for Laminas and ZF3.

1430.0k](/packages/saeven-zf3-circlical-autowire)[arcanedev/laravel-auth

Laravel Authorization package.

294.8k1](/packages/arcanedev-laravel-auth)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)