CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Users plugin 9.x for CakePHP4

Written by Jorge on January 17, 2020
17667 VIEWS

CakePHP 4 is out for some time (4.0.2 at the time of writing this post) and some of you already asked "Is there a cakedc/users version for cake4?" a couple times...

The answer is YES!.

We had a meeting after we realized AuthComponent was going to be deprecated, the authentication/authorization layer was leaning towards
Middlewares and getting a new Plugin home ourside of the core.
We decided to embrace the new middlewares and provide native compatibility from version 9.x of the plugin.

Before we explain how is it going to work, and proceed to setup a project from scratch a couple answers to potential questions:

* Are you going to maintain cakedc/users 8.x for CakePHP 3.x?
  * Yes, as long as you use it, we'll keep it maintained. Version 8.x will be a LTS version. We'll consider backporting some features from 9.x but the
  main objective of 8.x is to provide stability over time to existing CakePHP 3 projects.
* I'm planning to migrate my project from CakePHP 3 to CakePHP 4, what's the migration path for cakedc/users?
  * Keep the version 8.x of the plugin for some time. Complete your upgrade and then decide if you want to migrate to cakedc/users 9.x.
  We wrote a migration guide here when you decide it's time to move forward.
* AuthComponent is going to explode in CakePHP 4.x ?
  * No, it's deprecated, but deprecated also means it's completely functional. Just keep it until you decide to upgrade it.
 
This blog post is the first of a series of articles about cakedc/users 9.x where we'll explain how to use the plugin from scratch, it's benefits and
also the way the new authentication & authorization layers work for a CakePHP 4.x application.

We've kept our main objectives for this plugin: provide a quick, easy, flexible users management plugin to help you build awesome products on top of CakePHP 4.

So let's create a new project

* Ensure you have a working develop environment, download a development vagrant machine or pick some other's environment.

composer create-project cakephp/app:^4 users9

Now we have a new CakePHP 4 project skeleton created under folder users9.
Test it using bin/cake server then go to http://localhost:8765 and check it's all green.

 

all green checks for cakephp 4

 

* Install the plugin using
composer require cakedc/users:^9

* Now configure your application to use the plugin in your src/Application.php bootstrap() method, add
$this->addPlugin(\CakeDC\Users\Plugin::class);

* Create the required tables in your configured Datasource using Migrations:
bin/cake migrations migrate -p CakeDC/Users

This will create an empty `users` table and `social_accounts` to hold your authenticatio data.

* Now create a superadmin user
bin/cake users addSuperuser

It will create a superadmin user and a random password, copy the user and password to a safe place.

Now start the standalone server using bin/cake server again, and go to the home page http://localhost:8765... you'll see the login form.

 

login form cakephp 4 and cakedc/users


If you use the superadmin credentials previously generated, you'll be able to login and continue to the home page.

Total setup process, possibly less than 5 minutes if your network allows it...

How is it actually working?

* Once the plugin is added to you Application class through the Plugin class, we implement the  `AuthenticationService` and `AuthorizationService` provider interfaces, and use
the `middleware()` plugin callback to inject the configured middlewares into the Application middleware queue, see the `MiddlewareQueueLoader`.
We do it to keep the loading and configuration of the middlewares in one place, and decide the middlewares needed based on your configuration, for example if you are using
social login with Facebook, we configure which middlewares you need loaded and the correct order.
Check LINK for customization options of the plugin. We'll deal with customization in other articles of this series.

* CakePHP core Authentication and Authorization middlewares are also loaded, with the provided configuration. Check file vendor/cakedc/users/config/users.php for the
default configuratio used. You'll see there we're using by default Session, Form, Token, Cookie and Social. Depending on your configuration we'll check if you're authenticated in the following order:
  * Your identity already in the session
  * You've posted login form and your credentials are in the request data
  * There is a token present we can retrieve, usually for API stateless token based auth
  * There is a remember me cookie present
  * Your identity is available after social login, and we can use it to login into the app
 
If all these methods fail, you're redirected to the login page, `/login` by default (configurable, of course).  

* But that's the first step, once we can identify who are you, the next step (Authorization) is to determine if you're allowed to access the page you're trying to open. The plugin default configuration has 2
Authorization methods, superuser and rbac.
  * If you're user is a superuser, you are granted
  * If there is a rule in the rbac configuration to match your role and the current page, you are granted
 
If none of the above, you are not authorized, and redirected to the home page.

One of the important concepts about the new authentication layer in CakePHP is: "Authentication happens before you hit AppController".
So when you get to your Controller, CakePHP alreay knows you're an existing user and you have permission to access the page. All the abstraction and complexity
of maintaining the authentication is now extracted and managed OUTSIDE of your controllers, reducing their complexity.

Give it a try in your next project! Let us know how it goes and share you experiences with us, we'll be happy to help in the community channels.

 

Latest articles

36 Views

Goodbye to 2025!

Well bakers… another advent calendar is coming to an end. I hope you enjoyed all of the topics covered each day. We are also closing the year with so much gratitude.    2025 was the 20th year of CakePHP, can you believe it? We had an amazing year with our team, the community and the CakePHP core. It was great connecting with those who attended CakeFest in Madrid, and we hope to have the opportunity to see more of you in 2026.    I cannot let the year end without getting a little sentimental. There is no better way to say it… THANK YOU. Thank you to the team who worked so hard, the core team that keeps pumping out releases, and most of all … thank you to our clients that trust us with their projects. CakeDC is successful because of the strong relationships we build with our network, and we hope to continue working with all of you for many years.    There are a lot of great things still to come in year 21! Could 2026 will be bringing us CakePHP 6?! Considering 2 is rhe legal drinking age in the US, maybe CakePHP 6 should be beer cake? Delicious. Stay tuned to find out.    Before I go, I am leaving you with something special. A note from Larry!   As we close out this year, I just want to say thank you from the bottom of my heart. Twenty years ago, CakePHP started as a simple idea shared by a few of us who wanted to make building on the web easier and more enjoyable. Seeing how far it has come, and more importantly, seeing how many lives and careers it has impacted, is something I never take for granted. I am deeply grateful for our team, the core contributors, the community, and our clients who continue to believe in what we do. You are the reason CakePHP and CakeDC are still here, still growing, and still relevant after two decades. Here is to what we have built together, and to what is still ahead. Thank you for being part of this journey. Larry

Written by Amanda on December 24, 2025

38 Views

Pagination of multiple queries in CakePHP

Pagination of multiple queries in CakePHP

A less typical use case for pagination in an appication is the need to paginate multiples queries. In CakePHP you can achieve this with pagination scopes.

Users list

Lest use as an example a simple users list. // src/Controller/UsersController.php class UsersController extends AppController { protected array $paginate = [ 'limit' => 25, ]; public function index() { // Default model pagination $this->set('users', $this->paginate($this->Users)); } } // templates/Users/index.php <h2><?= __('Users list') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($users as $user): ?> <tr> <td><?= h($user->name) ?></td> <td><?= h($user->email) ?></td> <td><?= $user->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?>

Pagination of multiple queries

Now, we want to display two paginated tables, one with the active users and the other with the inactive ones. // src/Controller/UsersController.php class UsersController extends AppController { protected array $paginate = [ 'Users' => [ 'scope' => 'active_users', 'limit' => 25, ], 'InactiveUsers' => [ 'scope' => 'inactive_users', 'limit' => 10, ], ]; public function index() { $activeUsers = $this->paginate( $this->Users->find()->where(['active' => true]), [scope: 'active_users'] ); // Load an additional table object with the custom alias set in the paginate property $inactiveUsersTable = $this->fetchTable('InactiveUsers', [ 'className' => \App\Model\Table\UsersTable::class, 'table' => 'users', 'entityClass' => 'App\Model\Entity\User', ]); $inactiveUsers = $this->paginate( $inactiveUsersTable->find()->where(['active' => false]), [scope: 'inactive_users'] ); $this->set(compact('users', 'inactiveUsers')); } } // templates/Users/index.php <?php // call `setPaginated` first with the results to be displayed next, so the paginator use the correct scope for the links $this->Paginator->setPaginated($users); ?> <h2><?= __('Active Users') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($users as $user): ?> <tr> <td><?= h($user->name) ?></td> <td><?= h($user->email) ?></td> <td><?= $user->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?> <?php // call `setPaginated` first with the results to be displayed next, so the paginator use the correct scope for the links $this->Paginator->setPaginated($inactiveUsers); ?> <h2><?= __('Inactive Users') ?>/h2> <table> <thead> <tr> <th><?= $this->Paginator->sort('name', __('Name')) ?></th> <th><?= $this->Paginator->sort('email', __('Email')) ?></th> <th><?= $this->Paginator->sort('active', __('Active')) ?></th> </tr> </thead> <tbody> <?php foreach ($inactiveUsers as $inactiveUser): ?> <tr> <td><?= h($inactiveUser->name) ?></td> <td><?= h($inactiveUser->email) ?></td> <td><?= $inactiveUser->active ? 'Yes' : 'No' ?></td> </tr> <?php endforeach; ?> </tbody> </table> <?= $this->Paginator->counter() ?> <?= $this->Paginator->prev('« Previous') ?> <?= $this->Paginator->numbers() ?> <?= $this->Paginator->next('Next »') ?> And with this you have two paginated tables in the same request.

Written by Rperez on December 23, 2025

106 Views

Clean DI in CakePHP 5.3: Say Goodbye to fetchTable()

This article is part of the CakeDC Advent Calendar 2025 (December 23rd, 2025)

Introduction: The Death of the "Hidden" Dependency

For years, accessing data in CakePHP meant "grabbing" it from the global state. Whether using TableRegistry::getTableLocator()->get() or the LocatorAwareTrait’s $this->fetchTable(), your classes reached out to a locator to find what they needed. While convenient, this created hidden dependencies. A class constructor might look empty, despite the class being secretly reliant on multiple database tables. This made unit testing cumbersome, forcing you to stub the global TableLocator just to inject a mock. CakePHP 5.3 changes the game with Inversion of Control. With the framework currently in its Release Candidate (RC) stage and a stable release expected soon, now is the perfect time to explore these architectural improvements. By using the new TableContainer as a delegate for your PSR-11 container, tables can now be automatically injected directly into your constructors. This shift to explicit dependencies makes your code cleaner, fully type-hinted, and ready for modern testing standards. The Old Way (Hidden Dependency): public function execute() { $users = $this->fetchTable('Users'); // Where did this come from? } The 5.3 Way (Explicit Dependency): public function __construct(protected UsersTable $users) {} public function execute() { $this->users->find(); // Explicit and testable. }

Enabling the Delegate

Open src/Application.php and update the services() method by delegating table resolution to the TableContainer. // src/Application.php use Cake\ORM\TableContainer; public function services(ContainerInterface $container): void { // Register the TableContainer as a delegate $container->delegate(new TableContainer()); }

How it works under the hood

When you type-hint a class ending in Table (e.g., UsersTable), the main PSR-11 container doesn't initially know how to instantiate it. Because you've registered a delegate, it passes the request to the TableContainer, which then:
  1. Validates: It verifies the class name and ensures it is a subclass of \Cake\ORM\Table.
  2. Locates: It uses the TableLocator to fetch the correct instance (handling all the usual CakePHP ORM configuration behind the scenes).
  3. Resolves: It returns the fully configured Table object back to the main container to be injected.
Note: The naming convention is strict. The TableContainer specifically looks for the Table suffix. If you have a custom class that extends the base Table class but is named UsersRepository, the delegate will skip it, and the container will fail to resolve the dependency.

Practical Example: Cleaner Services

Now, your domain services no longer need to know about the LocatorAwareTrait. They simply ask for what they need. namespace App\Service; use App\Model\Table\UsersTable; class UserManagerService { // No more TableRegistry::get() or $this->fetchTable() public function __construct( protected UsersTable $users ) {} public function activateUser(int $id): void { $user = $this->users->get($id); // ... logic } } Next, open src/Application.php and update the services() method by delegating table resolution to the TableContainer. // src/Application.php use App\Model\Table\UsersTable; use App\Service\UserManagerService; use Cake\ORM\TableContainer; public function services(ContainerInterface $container): void { // Register the TableContainer as a delegate $container->delegate(new TableContainer()); // Register your service with the table as constructor argument $container ->add(UserManagerService::class) ->addArgument(UsersTable::class); }

Why this is a game changer for Testing

Because the table is injected via the constructor, you can now swap it for a mock effortlessly in your test suite without touching the global state of the application. $mockUsers = $this->createMock(UsersTable::class); $service = new UserManagerService($mockUsers); // Pure injection!

Conclusion: Small Change, Big Impact

At first glance, adding a single line to your Application::services() method might seem like a minor update. However, TableContainer represents a significant shift in how we approach CakePHP architecture. By delegating table resolution to the container, we gain:
  • True Type-Safety: Your IDE and static analysis tools now recognize the exact Table class being used. This is a massive win for PHPStan users—no more "Call to an undefined method" errors or messy @var docblock workarounds just to prove to your CI that a method exists.
  • Zero-Effort Mocking: Testing a service no longer requires manipulating the global TableRegistry state. Simply pass a mock object into the constructor and move on.
  • Standardization: Your CakePHP code now aligns with modern PHP practices found in any PSR-compliant ecosystem, making your application more maintainable and easier for new developers to understand.
If you plan to upgrade to CakePHP 5.3 upon its release, this is one of the easiest wins for your codebase. It’s time to stop fetching your tables and start receiving them. This article is part of the CakeDC Advent Calendar 2025 (December 23rd, 2025)

Written by Arusinowski on December 23, 2025

We Bake with CakePHP