Merge branch '4.next' into 5.x

src/Controller/Component/PaginatorComponent.php

@@ -18,8 +18,8 @@ namespace Cake\Controller\Component;
 
 use Cake\Controller\Component;
 use Cake\Controller\ComponentRegistry;
-use Cake\Datasource\Exception\PageOutOfBoundsException;
-use Cake\Datasource\Paginator;
+use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
+use Cake\Datasource\Paging\Paginator;
 use Cake\Datasource\ResultSetInterface;
 use Cake\Http\Exception\NotFoundException;
 use InvalidArgumentException;
@@ -34,15 +34,15 @@ use UnexpectedValueException;
  * You configure pagination when calling paginate(). See that method for more details.
  *
  * @link https://book.cakephp.org/4/en/controllers/components/pagination.html
- * @mixin \Cake\Datasource\Paginator
- * @deprecated 4.4.0 Use Cake\Datasource\Paginator directly. Will be removed in 6.0.
+ * @mixin \Cake\Datasource\Paging\Paginator
+ * @deprecated 4.4.0 Use Cake\Datasource\Paging\Paginator directly. Will be removed in 6.0.
  */
 class PaginatorComponent extends Component
 {
     /**
      * Datasource paginator instance.
      *
-     * @var \Cake\Datasource\Paginator
+     * @var \Cake\Datasource\Paging\Paginator
      */
     protected Paginator $_paginator;
 
@@ -226,7 +226,7 @@ class PaginatorComponent extends Component
     /**
      * Set paginator instance.
      *
-     * @param \Cake\Datasource\Paginator $paginator Paginator instance.
+     * @param \Cake\Datasource\Paging\Paginator $paginator Paginator instance.
      * @return $this
      */
     public function setPaginator(Paginator $paginator)
@@ -239,7 +239,7 @@ class PaginatorComponent extends Component
     /**
      * Get paginator instance.
      *
-     * @return \Cake\Datasource\Paginator
+     * @return \Cake\Datasource\Paging\Paginator
      */
     public function getPaginator(): Paginator
     {

src/Controller/Controller.php

@@ -18,8 +18,8 @@ namespace Cake\Controller;
 
 use Cake\Controller\Exception\MissingActionException;
 use Cake\Core\App;
-use Cake\Datasource\Exception\PageOutOfBoundsException;
-use Cake\Datasource\Paginator;
+use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
+use Cake\Datasource\Paging\Paginator;
 use Cake\Datasource\QueryInterface;
 use Cake\Datasource\RepositoryInterface;
 use Cake\Datasource\ResultSetInterface;
@@ -835,7 +835,7 @@ class Controller implements EventListenerInterface, EventDispatcherInterface
 
         $settings += $this->paginate;
 
-        /** @var \Cake\Datasource\PaginatorInterface|class-string<\Cake\Datasource\PaginatorInterface> $paginator */
+        /** @var \Cake\Datasource\Paging\PaginatorInterface|class-string<\Cake\Datasource\Paging\PaginatorInterface> $paginator */
         $paginator = $settings['paginator'] ?? Paginator::class;
         unset($settings['paginator']);
         if (is_string($paginator)) {

src/Core/Container.php

@@ -22,9 +22,6 @@ use League\Container\Container as LeagueContainer;
  * Dependency Injection container
  *
  * Based on the container out of League\Container
- *
- * @experimental This class' interface is not stable and may change
- *   in future minor releases.
  */
 class Container extends LeagueContainer implements ContainerInterface
 {

src/Core/ContainerApplicationInterface.php

@@ -18,9 +18,6 @@ namespace Cake\Core;
 
 /**
  * Interface for applications that configure and use a dependency injection container.
- *
- * @experimental This interface is not final and can have additional
- *   methods and parameters added in future minor releases.
  */
 interface ContainerApplicationInterface
 {

src/Core/ContainerInterface.php

@@ -26,9 +26,6 @@ use League\Container\DefinitionContainerInterface;
  *
  * The methods defined in this interface use the conventions provided
  * by league/container as that is the library that CakePHP uses.
- *
- * @experimental This interface is not final and can have additional
- *   methods and parameters added in future minor releases.
  */
 interface ContainerInterface extends DefinitionContainerInterface
 {

src/Core/ServiceProvider.php

@@ -28,9 +28,6 @@ use RuntimeException;
  * to organize your application's dependencies. They also help
  * improve performance of applications with many services by
  * allowing service registration to be deferred until services are needed.
- *
- * @experimental This class' interface is not stable and may change
- *   in future minor releases.
  */
 abstract class ServiceProvider extends AbstractServiceProvider implements BootableServiceProviderInterface
 {

src/Database/Query.php

@@ -842,15 +842,18 @@ class Query implements ExpressionInterface, IteratorAggregate, Stringable
      *
      * See `join()` for further details on conditions and types.
      *
-     * @param array<string>|string $table The table to join with
-     * @param \Cake\Database\ExpressionInterface|array|string $conditions The conditions
+     * @param array<string, mixed>|string $table The table to join with
+     * @param \Cake\Database\ExpressionInterface|\Closure|array|string $conditions The conditions
      * to use for joining.
      * @param array $types a list of types associated to the conditions used for converting
      * values to the corresponding database representation.
      * @return $this
      */
-    public function leftJoin(array|string $table, ExpressionInterface|array|string $conditions = [], array $types = [])
-    {
+    public function leftJoin(
+        array|string $table,
+        ExpressionInterface|Closure|array|string $conditions = [],
+        array $types = []
+    ) {
         $this->join($this->_makeJoin($table, $conditions, static::JOIN_TYPE_LEFT), $types);
 
         return $this;
@@ -864,15 +867,18 @@ class Query implements ExpressionInterface, IteratorAggregate, Stringable
      * The arguments of this method are identical to the `leftJoin()` shorthand, please refer
      * to that methods description for further details.
      *
-     * @param array<string>|string $table The table to join with
-     * @param \Cake\Database\ExpressionInterface|array|string $conditions The conditions
+     * @param array<string, mixed>|string $table The table to join with
+     * @param \Cake\Database\ExpressionInterface|\Closure|array|string $conditions The conditions
      * to use for joining.
      * @param array $types a list of types associated to the conditions used for converting
      * values to the corresponding database representation.
      * @return $this
      */
-    public function rightJoin(array|string $table, ExpressionInterface|array|string $conditions = [], array $types = [])
-    {
+    public function rightJoin(
+        array|string $table,
+        ExpressionInterface|Closure|array|string $conditions = [],
+        array $types = []
+    ) {
         $this->join($this->_makeJoin($table, $conditions, static::JOIN_TYPE_RIGHT), $types);
 
         return $this;
@@ -886,7 +892,7 @@ class Query implements ExpressionInterface, IteratorAggregate, Stringable
      * The arguments of this method are identical to the `leftJoin()` shorthand, please refer
      * to that method's description for further details.
      *
-     * @param array|string $table The table to join with
+     * @param array<string, mixed>|string $table The table to join with
      * @param \Cake\Database\ExpressionInterface|\Closure|array|string $conditions The conditions
      * to use for joining.
      * @param array<string, string> $types a list of types associated to the conditions used for converting
@@ -906,7 +912,7 @@ class Query implements ExpressionInterface, IteratorAggregate, Stringable
     /**
      * Returns an array that can be passed to the join method describing a single join clause
      *
-     * @param array<string>|string $table The table to join with
+     * @param array<string, mixed>|string $table The table to join with
      * @param \Cake\Database\ExpressionInterface|\Closure|array|string $conditions The conditions
      * to use for joining.
      * @param string $type the join type to use

src/Datasource/EntityTrait.php

@@ -406,7 +406,7 @@ trait EntityTrait
     }
 
     /**
-     * Checks tha a field has a value.
+     * Checks that a field has a value.
      *
      * This method will return true for
      *

src/Datasource/Exception/PageOutOfBoundsException.php

@@ -1,28 +1,7 @@
 <?php
 declare(strict_types=1);
 
-/**
- * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
- * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
- *
- * Licensed under The MIT License
- * Redistributions of files must retain the above copyright notice.
- *
- * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
- * @since         3.5.0
- * @license       http://www.opensource.org/licenses/mit-license.php MIT License
- */
-namespace Cake\Datasource\Exception;
-
-use Cake\Core\Exception\CakeException;
-
-/**
- * Exception raised when requested page number does not exist.
- */
-class PageOutOfBoundsException extends CakeException
-{
-    /**
-     * @inheritDoc
-     */
-    protected string $_messageTemplate = 'Page number %s could not be found.';
-}
+class_alias(
+    'Cake\Datasource\Paging\Exception\PageOutOfBoundsException',
+    'Cake\Datasource\Exception\PageOutOfBoundsException'
+);

src/Datasource/Paging/Exception/PageOutOfBoundsException.php

@@ -0,0 +1,28 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
+ * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
+ * @since         3.5.0
+ * @license       http://www.opensource.org/licenses/mit-license.php MIT License
+ */
+namespace Cake\Datasource\Paging\Exception;
+
+use Cake\Core\Exception\CakeException;
+
+/**
+ * Exception raised when requested page number does not exist.
+ */
+class PageOutOfBoundsException extends CakeException
+{
+    /**
+     * @inheritDoc
+     */
+    protected string $_messageTemplate = 'Page number %s could not be found.';
+}

src/Datasource/Paginator.php

@@ -14,11 +14,14 @@ declare(strict_types=1);
  * @since         3.5.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Datasource;
+namespace Cake\Datasource\Paging;
 
 use Cake\Core\Exception\CakeException;
 use Cake\Core\InstanceConfigTrait;
-use Cake\Datasource\Exception\PageOutOfBoundsException;
+use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
+use Cake\Datasource\QueryInterface;
+use Cake\Datasource\RepositoryInterface;
+use Cake\Datasource\ResultSetInterface;
 
 /**
  * This class is used to handle automatic model data pagination.

src/Datasource/PaginatorInterface.php

@@ -14,7 +14,11 @@ declare(strict_types=1);
  * @since         3.5.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Datasource;
+namespace Cake\Datasource\Paging;
+
+use Cake\Datasource\QueryInterface;
+use Cake\Datasource\RepositoryInterface;
+use Cake\Datasource\ResultSetInterface;
 
 /**
  * This interface describes the methods for paginator instance.

src/Datasource/SimplePaginator.php

@@ -14,7 +14,9 @@ declare(strict_types=1);
  * @since         3.9.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Datasource;
+namespace Cake\Datasource\Paging;
+
+use Cake\Datasource\QueryInterface;
 
 /**
  * Simplified paginator which avoids potentially expensives queries

src/Error/ExceptionRenderer.php

@@ -25,8 +25,8 @@ use Cake\Core\Configure;
 use Cake\Core\Container;
 use Cake\Core\Exception\CakeException;
 use Cake\Core\Exception\MissingPluginException;
-use Cake\Datasource\Exception\PageOutOfBoundsException;
 use Cake\Datasource\Exception\RecordNotFoundException;
+use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
 use Cake\Event\Event;
 use Cake\Http\Exception\HttpException;
 use Cake\Http\Exception\MissingControllerException;

src/Http/Response.php

@@ -1317,36 +1317,6 @@ class Response implements ResponseInterface, Stringable
     /**
      * Get a CorsBuilder instance for defining CORS headers.
      *
-     * This method allow multiple ways to setup the domains, see the examples
-     *
-     * ### Full URI
-     * ```
-     * cors($request, 'https://www.cakephp.org');
-     * ```
-     *
-     * ### URI with wildcard
-     * ```
-     * cors($request, 'https://*.cakephp.org');
-     * ```
-     *
-     * ### Ignoring the requested protocol
-     * ```
-     * cors($request, 'www.cakephp.org');
-     * ```
-     *
-     * ### Any URI
-     * ```
-     * cors($request, '*');
-     * ```
-     *
-     * ### Allowed list of URIs
-     * ```
-     * cors($request, ['http://www.cakephp.org', '*.google.com', 'https://myproject.github.io']);
-     * ```
-     *
-     * *Note* The `$allowedDomains`, `$allowedMethods`, `$allowedHeaders` parameters are deprecated.
-     * Instead the builder object should be used.
-     *
      * @param \Cake\Http\ServerRequest $request Request object
      * @return \Cake\Http\CorsBuilder A builder object the provides a fluent interface for defining
      *   additional CORS headers.

src/ORM/Table.php

@@ -1396,7 +1396,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
      * ```
      * $table->find('threaded', [
      *  'keyField' => 'id',
-     *  'parentField' => 'ancestor_id'
+     *  'parentField' => 'ancestor_id',
      *  'nestingKey' => 'children'
      * ]);
      * ```

tests/TestCase/Controller/Component/PaginatorComponentTest.php

@@ -21,7 +21,7 @@ use Cake\Controller\ComponentRegistry;
 use Cake\Controller\Controller;
 use Cake\Datasource\ConnectionManager;
 use Cake\Datasource\EntityInterface;
-use Cake\Datasource\Exception\PageOutOfBoundsException;
+use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
 use Cake\Datasource\RepositoryInterface;
 use Cake\Event\EventInterface;
 use Cake\Http\Exception\NotFoundException;
@@ -32,7 +32,7 @@ use Cake\TestSuite\TestCase;
 use InvalidArgumentException;
 use stdClass;
 use TestApp\Controller\Component\CustomPaginatorComponent;
-use TestApp\Datasource\CustomPaginator;
+use TestApp\Datasource\Paging\CustomPaginator;
 use UnexpectedValueException;
 
 class PaginatorComponentTest extends TestCase
@@ -115,7 +115,7 @@ class PaginatorComponentTest extends TestCase
     public function testInvalidPaginatorOption(): void
     {
         $this->expectException(InvalidArgumentException::class);
-        $this->expectExceptionMessage('Paginator must be an instance of Cake\Datasource\Paginator');
+        $this->expectExceptionMessage('Paginator must be an instance of Cake\Datasource\Paging\Paginator');
         new PaginatorComponent($this->registry, [
             'paginator' => new stdClass(),
         ]);

tests/TestCase/Datasource/PaginatorTest.php

@@ -14,7 +14,7 @@ declare(strict_types=1);
  * @since         3.5.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Test\TestCase\Datasource;
+namespace Cake\Test\TestCase\Datasource\Paging;
 
 use Cake\ORM\Entity;
 use Cake\TestSuite\TestCase;

tests/TestCase/Datasource/PaginatorTestTrait.php

@@ -14,13 +14,13 @@ declare(strict_types=1);
  * @since         3.9.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Test\TestCase\Datasource;
+namespace Cake\Test\TestCase\Datasource\Paging;
 
 use Cake\Core\Configure;
 use Cake\Datasource\ConnectionManager;
 use Cake\Datasource\EntityInterface;
-use Cake\Datasource\Exception\PageOutOfBoundsException;
-use Cake\Datasource\Paginator;
+use Cake\Datasource\Paging\Exception\PageOutOfBoundsException;
+use Cake\Datasource\Paging\Paginator;
 use Cake\Datasource\RepositoryInterface;
 
 trait PaginatorTestTrait

tests/TestCase/Datasource/SimplePaginatorTest.php

@@ -14,10 +14,10 @@ declare(strict_types=1);
  * @since         3.9.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Test\TestCase\Datasource;
+namespace Cake\Test\TestCase\Datasource\Paging;
 
 use Cake\Core\Configure;
-use Cake\Datasource\SimplePaginator;
+use Cake\Datasource\Paging\SimplePaginator;
 use Cake\ORM\Entity;
 
 class SimplePaginatorTest extends PaginatorTest

tests/TestCase/ExceptionsTest.php

@@ -148,8 +148,8 @@ class ExceptionsTest extends TestCase
             ['Cake\Datasource\Exception\MissingDatasourceConfigException', 0],
             ['Cake\Datasource\Exception\MissingDatasourceException', 0],
             ['Cake\Datasource\Exception\MissingModelException', 0],
-            ['Cake\Datasource\Exception\PageOutOfBoundsException', 0],
             ['Cake\Datasource\Exception\RecordNotFoundException', 0],
+            ['Cake\Datasource\Paging\Exception\PageOutOfBoundsException', 0],
             ['Cake\Mailer\Exception\MissingActionException', 0],
             ['Cake\Mailer\Exception\MissingMailerException', 0],
             ['Cake\Http\Exception\BadRequestException', 400],

tests/test_app/TestApp/Datasource/CustomPaginator.php

@@ -1,9 +1,9 @@
 <?php
 declare(strict_types=1);
 
-namespace TestApp\Datasource;
+namespace TestApp\Datasource\Paging;
 
-use Cake\Datasource\Paginator;
+use Cake\Datasource\Paging\Paginator;
 
 class CustomPaginator extends Paginator
 {