Skip to content

Commit 49ad1f7

Browse files
dereuromarkdereuromark
committed
Resolve merge conflicts with 4.x branch
2 parents 0d2e3fc + 85076bf commit 49ad1f7

45 files changed

Lines changed: 1259 additions & 1236 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
"issues": "https://github.com/cakephp/authentication/issues",
2121
"forum": "https://discourse.cakephp.org/",
2222
"source": "https://github.com/cakephp/authentication",
23-
"docs": "https://book.cakephp.org/authentication/3/en/"
23+
"docs": "https://book.cakephp.org/authentication/4/en/"
2424
},
2525
"require": {
2626
"php": ">=8.1",

‎docs/en/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Project's ROOT directory (where the **composer.json** file is located)
88
99
php composer.phar require cakephp/authentication
1010
11-
Version 3 of the Authentication Plugin is compatible with CakePHP 5.
11+
Version 4 of the Authentication Plugin is compatible with CakePHP 5.
1212

1313
Load the plugin by adding the following statement in your project's ``src/Application.php``::
1414

‎docs/en/upgrade-3-to-4.rst‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
Upgrade Guide 3.x to 4.x
2+
#########################
3+
4+
Version 4.0 is a major release with several breaking changes focused on
5+
simplifying the API and removing deprecated code.
6+
7+
Breaking Changes
8+
================
9+
10+
IdentifierCollection Removed
11+
-----------------------------
12+
13+
The deprecated ``IdentifierCollection`` has been removed. Authenticators now
14+
accept a nullable ``IdentifierInterface`` directly.
15+
16+
**Before (3.x):**
17+
18+
.. code-block:: php
19+
20+
use Authentication\Identifier\IdentifierCollection;
21+
22+
$identifiers = new IdentifierCollection([
23+
'Authentication.Password',
24+
]);
25+
26+
$authenticator = new FormAuthenticator($identifiers);
27+
28+
**After (4.x):**
29+
30+
.. code-block:: php
31+
32+
use Authentication\Identifier\IdentifierFactory;
33+
34+
// Option 1: Pass identifier directly
35+
$identifier = IdentifierFactory::create('Authentication.Password');
36+
$authenticator = new FormAuthenticator($identifier);
37+
38+
// Option 2: Pass null and let authenticator create default
39+
$authenticator = new FormAuthenticator(null);
40+
41+
// Option 3: Configure identifier in authenticator config
42+
$service->loadAuthenticator('Authentication.Form', [
43+
'identifier' => 'Authentication.Password',
44+
]);
45+
46+
AuthenticationService Changes
47+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
48+
49+
The ``loadIdentifier()`` method has been removed from ``AuthenticationService``.
50+
Identifiers are now managed by individual authenticators.
51+
52+
**Before (3.x):**
53+
54+
.. code-block:: php
55+
56+
$service = new AuthenticationService();
57+
$service->loadIdentifier('Authentication.Password');
58+
$service->loadAuthenticator('Authentication.Form');
59+
60+
**After (4.x):**
61+
62+
.. code-block:: php
63+
64+
$service = new AuthenticationService();
65+
$service->loadAuthenticator('Authentication.Form', [
66+
'identifier' => 'Authentication.Password',
67+
]);
68+
69+
CREDENTIAL Constants Moved
70+
---------------------------
71+
72+
The ``CREDENTIAL_USERNAME`` and ``CREDENTIAL_PASSWORD`` constants have been
73+
moved from ``AbstractIdentifier`` to specific identifier implementations.
74+
75+
**Before (3.x):**
76+
77+
.. code-block:: php
78+
79+
use Authentication\Identifier\AbstractIdentifier;
80+
81+
$fields = [
82+
AbstractIdentifier::CREDENTIAL_USERNAME => 'email',
83+
AbstractIdentifier::CREDENTIAL_PASSWORD => 'password',
84+
];
85+
86+
**After (4.x):**
87+
88+
.. code-block:: php
89+
90+
use Authentication\Identifier\PasswordIdentifier;
91+
92+
$fields = [
93+
PasswordIdentifier::CREDENTIAL_USERNAME => 'email',
94+
PasswordIdentifier::CREDENTIAL_PASSWORD => 'password',
95+
];
96+
97+
For LDAP authentication:
98+
99+
.. code-block:: php
100+
101+
use Authentication\Identifier\LdapIdentifier;
102+
103+
$fields = [
104+
LdapIdentifier::CREDENTIAL_USERNAME => 'uid',
105+
LdapIdentifier::CREDENTIAL_PASSWORD => 'password',
106+
];
107+
108+
URL Checker Renamed and Restructured
109+
-------------------------------------
110+
111+
URL checkers have been completely restructured:
112+
113+
- ``CakeRouterUrlChecker`` has been renamed to ``DefaultUrlChecker``
114+
- The old ``DefaultUrlChecker`` has been renamed to ``StringUrlChecker``
115+
- Auto-detection has been removed - ``DefaultUrlChecker`` is now hardcoded
116+
117+
**Before (3.x):**
118+
119+
.. code-block:: php
120+
121+
// Using CakeRouterUrlChecker explicitly
122+
$service->loadAuthenticator('Authentication.Form', [
123+
'urlChecker' => 'Authentication.CakeRouter',
124+
'loginUrl' => [
125+
'controller' => 'Users',
126+
'action' => 'login',
127+
],
128+
]);
129+
130+
// Using DefaultUrlChecker explicitly
131+
$service->loadAuthenticator('Authentication.Form', [
132+
'urlChecker' => 'Authentication.Default',
133+
'loginUrl' => '/users/login',
134+
]);
135+
136+
// Auto-detection (picks CakeRouter if available, otherwise Default)
137+
$service->loadAuthenticator('Authentication.Form', [
138+
'loginUrl' => '/users/login',
139+
]);
140+
141+
**After (4.x):**
142+
143+
.. code-block:: php
144+
145+
// DefaultUrlChecker is now hardcoded (formerly CakeRouterUrlChecker)
146+
$service->loadAuthenticator('Authentication.Form', [
147+
'loginUrl' => [
148+
'controller' => 'Users',
149+
'action' => 'login',
150+
],
151+
]);
152+
153+
// For string-only URL checking, explicitly use StringUrlChecker
154+
$service->loadAuthenticator('Authentication.Form', [
155+
'urlChecker' => 'Authentication.String',
156+
'loginUrl' => '/users/login',
157+
]);
158+
159+
Simplified URL Checker API
160+
---------------------------
161+
162+
URL checkers now accept a single URL in either string or array format.
163+
For multiple URLs, you must explicitly use ``MultiUrlChecker``.
164+
165+
**Multiple URLs - Before (3.x):**
166+
167+
.. code-block:: php
168+
169+
// This would auto-select the appropriate checker
170+
$service->loadAuthenticator('Authentication.Form', [
171+
'loginUrl' => [
172+
'/en/users/login',
173+
'/de/users/login',
174+
],
175+
]);
176+
177+
**Multiple URLs - After (4.x):**
178+
179+
.. code-block:: php
180+
181+
// Must explicitly configure MultiUrlChecker
182+
$service->loadAuthenticator('Authentication.Form', [
183+
'urlChecker' => 'Authentication.Multi',
184+
'loginUrl' => [
185+
'/en/users/login',
186+
'/de/users/login',
187+
],
188+
]);
189+
190+
Single URLs work the same in both versions:
191+
192+
.. code-block:: php
193+
194+
// String URL
195+
$service->loadAuthenticator('Authentication.Form', [
196+
'loginUrl' => '/users/login',
197+
]);
198+
199+
// Array URL (CakePHP route)
200+
$service->loadAuthenticator('Authentication.Form', [
201+
'loginUrl' => ['controller' => 'Users', 'action' => 'login'],
202+
]);
203+
204+
Auto-Detection Removed
205+
----------------------
206+
207+
URL Checkers
208+
^^^^^^^^^^^^
209+
210+
**Important:** Auto-detection has been removed. ``DefaultUrlChecker`` is now hardcoded.
211+
212+
- **4.x default:** Always uses ``DefaultUrlChecker`` (formerly ``CakeUrlChecker``)
213+
- **String URLs only:** Must explicitly configure ``StringUrlChecker``
214+
- **Multiple URLs:** Must explicitly configure ``MultiUrlChecker``
215+
216+
DefaultUrlChecker is Now CakePHP-Based
217+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
218+
219+
``DefaultUrlChecker`` is now the CakePHP checker (formerly ``CakeRouterUrlChecker``).
220+
It requires CakePHP Router and supports both string and array URLs.
221+
222+
The 3.x ``DefaultUrlChecker`` has been renamed to ``StringUrlChecker``.
223+
224+
.. code-block:: php
225+
226+
// DefaultUrlChecker now requires CakePHP Router
227+
$checker = new DefaultUrlChecker();
228+
$checker->check($request, ['controller' => 'Users', 'action' => 'login']); // Works
229+
$checker->check($request, '/users/login'); // Also works
230+
231+
// For string URL only usage:
232+
$checker = new StringUrlChecker();
233+
$checker->check($request, '/users/login'); // Works
234+
$checker->check($request, ['controller' => 'Users']); // Throws exception
235+
236+
New Features
237+
============
238+
239+
IdentifierFactory
240+
-----------------
241+
242+
New factory class for creating identifiers from configuration:
243+
244+
.. code-block:: php
245+
246+
use Authentication\Identifier\IdentifierFactory;
247+
248+
// Create from string
249+
$identifier = IdentifierFactory::create('Authentication.Password');
250+
251+
// Create with config
252+
$identifier = IdentifierFactory::create('Authentication.Password', [
253+
'fields' => [
254+
'username' => 'email',
255+
'password' => 'password',
256+
],
257+
]);
258+
259+
// Pass existing instance (returns as-is)
260+
$identifier = IdentifierFactory::create($existingIdentifier);
261+
262+
MultiUrlChecker
263+
---------------
264+
265+
New dedicated checker for multiple login URLs:
266+
267+
.. code-block:: php
268+
269+
$service->loadAuthenticator('Authentication.Form', [
270+
'urlChecker' => 'Authentication.Multi',
271+
'loginUrl' => [
272+
'/en/login',
273+
'/de/login',
274+
['lang' => 'fr', 'controller' => 'Users', 'action' => 'login'],
275+
],
276+
]);
277+
278+
Migration Tips
279+
==============
280+
281+
1. **Search and Replace**:
282+
283+
- ``AbstractIdentifier::CREDENTIAL_`` → ``PasswordIdentifier::CREDENTIAL_``
284+
- ``IdentifierCollection`` → ``IdentifierFactory``
285+
- ``'Authentication.CakeRouter'`` → Remove (no longer needed, default is now CakePHP-based)
286+
- ``CakeRouterUrlChecker`` → ``DefaultUrlChecker``
287+
- Old 3.x ``DefaultUrlChecker`` → ``StringUrlChecker``
288+
289+
2. **String URL Checking**:
290+
291+
If you want to use string-only URL checking, explicitly configure
292+
``StringUrlChecker``:
293+
294+
.. code-block:: php
295+
296+
$service->loadAuthenticator('Authentication.Form', [
297+
'urlChecker' => 'Authentication.String',
298+
'loginUrl' => '/users/login',
299+
]);
300+
301+
3. **Multiple Login URLs**:
302+
303+
If you have multiple login URLs, add ``'urlChecker' => 'Authentication.Multi'``
304+
to your authenticator configuration.
305+
306+
4. **Custom Identifier Setup**:
307+
308+
If you were passing ``IdentifierCollection`` to authenticators, switch to
309+
either passing a single identifier or null (to use defaults).
310+
311+
5. **Test Thoroughly**:
312+
313+
The changes to identifier management and URL checking are significant.
314+
Test all authentication flows after upgrading.

0 commit comments

Comments
 (0)