Merge branch 'cakephp:5.x' into m1

en/appendices/5-0-migration-guide.rst

@@ -28,9 +28,6 @@ Global
 - Type declarations were added to all class properties where possible. These also include some fixes for
   incorrect annotations.
 - The ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``,  ``WEEK``, ``MONTH``, ``YEAR`` constants were removed.
-- Global functions are now opt-in. If your application uses global function
-  aliases be sure to add ``require CAKE . 'functions.php'`` to you application's
-  ``config/bootstrap.php``.
 - Use of ``#[\AllowDynamicProperties]`` removed everywhere. It was used for the following classes:
    - ``Command/Command``
    - ``Console/Shell``

en/controllers.rst

@@ -282,14 +282,14 @@ This would render **plugins/Users/templates/UserDetails/custom_file.php**
 Content Type Negotiation
 ========================
 
-.. php:method:: viewClasses()
+.. php:method:: addViewClasses()
 
 Controllers can define a list of view classes they support. After the
 controller's action is complete CakePHP will use the view list to perform
-content-type negotiation with either :ref:`file-extensions` or ``Content-Type``
+content-type negotiation with either :ref:`file-extensions` or ``Accept``
 headers. This enables your application to re-use the same controller action to
 render an HTML view or render a JSON or XML response. To define the list of
-supported view classes for a controller is done with the ``viewClasses()``
+supported view classes for a controller is done with the ``addViewClasses()``
 method::
 
     namespace App\Controller;
@@ -299,25 +299,25 @@ method::
 
     class PostsController extends AppController
     {
-        public function viewClasses(): array
+        public function initialize(): void
         {
-            return [JsonView::class, XmlView::class];
+            parent::initialize();
+
+            $this->addViewClasses([JsonView::class, XmlView::class]);
         }
     }
 
 The application's ``View`` class is automatically used as a fallback when no
 other view can be selected based on the request's ``Accept`` header or routing
 extension. If your application only supports content types for a specific
-actions, you can define that logic within ``viewClasses()``::
+actions, you can call ``addClasses()`` within your action too::
 
-    public function viewClasses(): array
+    public function export(): void
     {
-        if ($this->request->getParam('action') === 'export') {
-            // Use a custom CSV view for data exports.
-            return [CsvView::class];
-        }
+        // Use a custom CSV view for data exports.
+        $this->addViewClasses([CsvView::class]);
 
-        return [JsonView::class];
+        // Rest of the action code
     }
 
 If within your controller actions you need to process the request or load data
@@ -331,9 +331,9 @@ differently based on the content type you can use
         $query->contain('Authors');
     }
 
-You can also set your controllers' supported view classes
-using the ``addViewClasses()`` method which will merge the provided views with
-those held in the ``viewClasses`` property.
+In case your app need more complex logic to decide which view classes to use
+then you can override the ``Controller::viewClasses()`` method and return
+an array of view classes as required.
 
 .. note::
     View classes must implement the static ``contentType()`` hook method to
@@ -344,13 +344,15 @@ Content Type Negotiation Fallbacks
 
 If no View can be matched with the request's content type preferences, CakePHP
 will use the base ``View`` class. If you want to require content-type
-negotiation, you can use the ``NegotiationRequiredView`` which sets a 406 status
+negotiation, you can use the ``NegotiationRequiredView`` which sets a ``406`` status
 code::
 
-    public function viewClasses(): array
+    public function initialize(): void
     {
+        parent::initialize();
+
         // Require Accept header negotiation or return a 406 response.
-        return [JsonView::class, NegotiationRequiredView::class];
+        $this->addViewClasses([JsonView::class, NegotiationRequiredView::class]);
     }
 
 You can use the ``TYPE_MATCH_ALL`` content type value to build your own fallback
@@ -372,6 +374,22 @@ view logic::
 It is important to remember that match-all views are applied only *after*
 content-type negotiation is attempted.
 
+Using AjaxView
+==============
+
+In applications that use hypermedia or AJAX clients, you often need to render
+view contents without the wrapping layout. You can use the ``AjaxView`` that
+is bundled with the application skeleton::
+
+    // In a controller action, or in beforeRender.
+    if ($this->request->is('ajax')) {
+        $this->viewBuilder()->setClassName('Ajax');
+    }
+
+``AjaxView`` will respond as ``text/html`` and use the ``ajax`` layout.
+Generally this layout is minimal or contains client specific markup. This
+replaces usage of ``RequestHandlerComponent`` automatically using the
+``AjaxView`` in 4.x.
 
 Redirecting to Other Pages
 ==========================

en/controllers/components.rst

@@ -233,7 +233,7 @@ You can load other components by adding them to the `$components` property::
     class CustomComponent extends Component
     {
         // The other component your component uses
-        protected $components = ['Existing'];
+        protected array $components = ['Existing'];
 
         // Execute any other additional setup for your component.
         public function initialize(array $config): void

en/development/errors.rst

@@ -140,7 +140,7 @@ Custom Templates
 ================
 
 The default exception trap renders all uncaught exceptions your application
-raises with the help of ``Cake\Error\WebExceptionRenderer``, and your application's
+raises with the help of ``Cake\Error\Renderer\WebExceptionRenderer``, and your application's
 ``ErrorController``.
 
 The error page views are located at **templates/Error/**. All 4xx errors use
@@ -229,7 +229,7 @@ error pages when this error is handled::
     // In src/Error/AppExceptionRenderer.php
     namespace App\Error;
 
-    use Cake\Error\WebExceptionRenderer;
+    use Cake\Error\Renderer\WebExceptionRenderer;
 
     class AppExceptionRenderer extends WebExceptionRenderer
     {
@@ -259,7 +259,7 @@ additional logic when handling CakePHP errors::
     // In src/Error/AppExceptionRenderer.php
     namespace App\Error;
 
-    use Cake\Error\WebExceptionRenderer;
+    use Cake\Error\Renderer\WebExceptionRenderer;
 
     class AppExceptionRenderer extends WebExceptionRenderer
     {
@@ -281,7 +281,7 @@ override the ``_getController()`` method in your exception renderer::
 
     use App\Controller\SuperCustomErrorController;
     use Cake\Controller\Controller;
-    use Cake\Error\WebExceptionRenderer;
+    use Cake\Error\Renderer\WebExceptionRenderer;
 
     class AppExceptionRenderer extends WebExceptionRenderer
     {

en/development/testing.rst

@@ -324,12 +324,12 @@ file:
 
     <testsuites>
         <testsuite name="app">
-            <directory>./tests/TestCase/</directory>
+            <directory>tests/TestCase/</directory>
         </testsuite>
 
         <!-- Add your plugin suites -->
         <testsuite name="forum">
-            <directory>./plugins/Forum/tests/TestCase/</directory>
+            <directory>plugins/Forum/tests/TestCase/</directory>
         </testsuite>
     </testsuites>
 
@@ -412,7 +412,7 @@ contains the fixture extension:
     <!-- in phpunit.xml -->
     <!-- Setup the extension for fixtures -->
     <extensions>
-        <extension class="\Cake\TestSuite\Fixture\PHPUnitExtension" />
+        <extension class="\Cake\TestSuite\Fixture\PHPUnitExtension"/>
     </extensions>
 
 The extension is included in your application and plugins generated by ``bake``
@@ -442,7 +442,7 @@ database schema as well::
     // Simple setup for with no plugins
     $migrator->run();
 
-    // Run migrations for multiple plugins
+    // Run migrations for a plugin
     $migrator->run(['plugin' => 'Contacts']);
 
     // Run the Documents migrations on the test_docs connection.

en/orm/database-basics.rst

@@ -757,23 +757,6 @@ The above class does a few interesting things:
 Once we've built our custom type, we'll need to :ref:`connect our type
 to our table class <saving-complex-types>`.
 
-.. _immutable-datetime-mapping:
-
-Enabling Immutable DateTime Objects
------------------------------------
-
-Because Date/Time objects are easily mutated in place, CakePHP allows you to
-enable immutable value objects. This is best done in your application's
-**config/bootstrap.php** file::
-
-    TypeFactory::build('datetime')->useImmutable();
-    TypeFactory::build('date')->useImmutable();
-    TypeFactory::build('time')->useImmutable();
-    TypeFactory::build('timestamp')->useImmutable();
-
-.. note::
-    New applications will have immutable objects enabled by default.
-
 Connection Classes
 ==================
 

en/orm/retrieving-data-and-resultsets.rst

@@ -41,9 +41,7 @@ viewing entities and their related data. You can do this by using ``get()``::
     $article = $articles->get($id);
 
     // Get a single article, and related comments
-    $article = $articles->get($id, [
-        'contain' => ['Comments'],
-    ]);
+    $article = $articles->get($id, contain: ['Comments']);
 
 If the get operation does not find any results a
 ``Cake\Datasource\Exception\RecordNotFoundException`` will be raised. You can
@@ -56,27 +54,19 @@ Like ``find()``, ``get()`` also has caching integrated. You can use the
     // In a controller or table method.
 
     // Use any cache config or CacheEngine instance & a generated key
-    $article = $articles->get($id, [
-        'cache' => 'custom',
-    ]);
+    $article = $articles->get($id, cache: 'custom');
 
     // Use any cache config or CacheEngine instance & specific key
-    $article = $articles->get($id, [
-        'cache' => 'custom', 'key' => 'mykey'
-    ]);
+    $article = $articles->get($id, cache: 'custom', key: 'mykey');
 
     // Explicitly disable caching
-    $article = $articles->get($id, [
-        'cache' => false
-    ]);
+    $article = $articles->get($id, cache: false);
 
 Optionally you can ``get()`` an entity using :ref:`custom-find-methods`. For
 example you may want to get all translations for an entity. You can achieve that
 by using the ``finder`` option::
 
-    $article = $articles->get($id, [
-        'finder' => 'translations',
-    ]);
+    $article = $articles->get($id, 'translations');
 
 The list of options supported by get() are:
 

en/plugins.rst

@@ -176,7 +176,7 @@ classes::
     $plugin->enable('routes');
     $this->addPlugin($plugin);
 
-Plugin objects also know their names and path information::
+Plugin classes also know their names and path information::
 
     $plugin = new ContactManagerPlugin();
 
@@ -290,12 +290,12 @@ autoloader once you've created your plugin:
 
 .. _plugin-objects:
 
-Plugin Objects
+Plugin Classes
 ==============
 
-Plugin Objects allow a plugin author to define set-up logic, define default
-hooks, load routes, middleware and console commands. Plugin objects live in
-**src/<PluginName>Plugin.php**. For our ContactManager plugin, our plugin class could look
+Plugin classes allow a plugin author to define set-up logic, define default
+hooks, load routes, middleware and console commands. Plugin classes live in
+**src/{PluginName}Plugin.php**. For our ContactManager plugin, our plugin class could look
 like::
 
     namespace ContactManager;
@@ -309,7 +309,6 @@ like::
 
     class ContactManagerPlugin extends BasePlugin
     {
-
         /**
          * @inheritDoc
          */

en/tutorials-and-examples/blog-auth-example/auth.rst

@@ -134,7 +134,7 @@ install the Authentication Plugin:
 
 .. code-block:: console
 
-    composer require "cakephp/authentication:^2.0"
+    php composer.phar require "cakephp/authentication:^2.0"
 
 Then add the following to your application's ``bootstrap()`` method::
 
@@ -150,7 +150,7 @@ Next, we'll create the ``User`` entity and add password hashing.  Create the
     // src/Model/Entity/User.php
     namespace App\Model\Entity;
 
-    use Cake\Auth\DefaultPasswordHasher;
+    use Authentication\PasswordHasher\DefaultPasswordHasher;
     use Cake\ORM\Entity;
 
     class User extends Entity

en/tutorials-and-examples/cms/database.rst

@@ -130,34 +130,28 @@ with those that apply to your setup. A sample completed configuration array
 might look something like the following::
 
     <?php
+    // config/app_local.php
     return [
         // More configuration above.
         'Datasources' => [
             'default' => [
-                'className' => 'Cake\Database\Connection',
-                // Replace Mysql with Postgres if you are using PostgreSQL
-                'driver' => 'Cake\Database\Driver\Mysql',
-                'persistent' => false,
                 'host' => 'localhost',
                 'username' => 'cakephp',
                 'password' => 'AngelF00dC4k3~',
                 'database' => 'cake_cms',
-                // Comment out the line below if you are using PostgreSQL
-                'encoding' => 'utf8mb4',
-                'timezone' => 'UTC',
-                'cacheMetadata' => true,
+                'url' => env('DATABASE_URL', null),
             ],
         ],
         // More configuration below.
     ];
 
-Once you've saved your **config/app.php** file, you should see that the 'CakePHP is
+Once you've saved your **config/app_local.php** file, you should see that the 'CakePHP is
 able to connect to the database' section has a green chef hat.
 
 .. note::
 
-    If you have **config/app_local.php** in your app folder, you need to
-    configure your database connection in that file instead.
+    The file **config/app_local.php** in your is a local override of the file **config/app_local.php**
+    used to configure your development environment quickly.
 
 Creating our First Model
 ========================
@@ -175,6 +169,8 @@ this::
 
     <?php
     // src/Model/Table/ArticlesTable.php
+    declare(strict_types=1);
+
     namespace App\Model\Table;
 
     use Cake\ORM\Table;
@@ -183,6 +179,7 @@ this::
     {
         public function initialize(array $config): void
         {
+            parent::initialize($config);
             $this->addBehavior('Timestamp');
         }
     }
@@ -208,16 +205,21 @@ look like this::
 
     <?php
     // src/Model/Entity/Article.php
+    declare(strict_types=1);
+
     namespace App\Model\Entity;
 
     use Cake\ORM\Entity;
 
     class Article extends Entity
     {
         protected array $_accessible = [
-            '*' => true,
-            'id' => false,
-            'slug' => false,
+            'title' => true,
+            'body' => true,
+            'published' => true,
+            'created' => true,
+            'modified' => true,
+            'users' => true,
         ];
     }