Merge branch '5.x' into 5.next

Author: markstory

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

@@ -28,15 +28,21 @@ 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``
+   - ``Controller/Component``
+   - ``Controller/Controller``
+   - ``Mailer/Mailer``
+   - ``View/Cell``
+   - ``View/Helper``
+   - ``View/View``
 - The supported database engine versions were updated:
-  -  MySQL (5.7 or higher)
-  -  MariaDB (10.1 or higher)
-  -  PostgreSQL (9.6 or higher)
-  -  Microsoft SQL Server (2012 or higher)
-  -  SQLite 3
+   - MySQL (5.7 or higher)
+   - MariaDB (10.1 or higher)
+   - PostgreSQL (9.6 or higher)
+   - Microsoft SQL Server (2012 or higher)
+   - SQLite 3
 
 Auth
 ----
@@ -123,6 +129,8 @@ Database
   ``QueryExpression::case()`` or ``CaseStatementExpression``
 - ``Connection::connect()`` has been removed. Use
   ``$connection->getDriver()->connect()`` instead.
+- ``Connection::disconnect()`` has been removed. Use
+  ``$connection->getDriver()->disconnect()`` instead.
 - ``cake.database.queries`` has been added as an alternative to the ``queriesLog`` scope
 
 Datasource
@@ -385,7 +393,7 @@ A similar change has been applied to the ``RepositoryInterface::get()`` method::
     {
         $author = $this->Authors->get($id, [
             'contain' => ['Books'],
-            'finder' => 'latest'
+            'finder' => 'latest',
         ]);
     }
 

en/console-commands/commands.rst

@@ -27,7 +27,7 @@ simple Hello world command. In your application's **src/Command** directory crea
         public function execute(Arguments $args, ConsoleIo $io): int
         {
             $io->out('Hello world.');
-            
+
             return static::CODE_SUCCESS;
         }
     }
@@ -60,7 +60,7 @@ command line::
         protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
         {
             $parser->addArgument('name', [
-                'help' => 'What is your name'
+                'help' => 'What is your name',
             ]);
             return $parser;
         }
@@ -69,7 +69,7 @@ command line::
         {
             $name = $args->getArgument('name');
             $io->out("Hello {$name}.");
-            
+
             return static::CODE_SUCCESS;
         }
     }
@@ -111,11 +111,11 @@ add a ``yell`` option to our ``HelloCommand``::
     {
         $parser
             ->addArgument('name', [
-                'help' => 'What is your name'
+                'help' => 'What is your name',
             ])
             ->addOption('yell', [
                 'help' => 'Shout the name',
-                'boolean' => true
+                'boolean' => true,
             ]);
 
         return $parser;
@@ -128,7 +128,7 @@ add a ``yell`` option to our ``HelloCommand``::
             $name = mb_strtoupper($name);
         }
         $io->out("Hello {$name}.");
-        
+
         return static::CODE_SUCCESS;
     }
 
@@ -202,7 +202,7 @@ to terminate execution::
             $io->error('Name must be at least 4 characters long.');
             $this->abort();
         }
-        
+
         return static::CODE_SUCCESS;
     }
 
@@ -215,7 +215,7 @@ You can also use ``abort()`` on the ``$io`` object to emit a message and code::
             // Halt execution, output to stderr, and set exit code to 99
             $io->abort('Name must be at least 4 characters long.', 99);
         }
-        
+
         return static::CODE_SUCCESS;
     }
 
@@ -376,7 +376,7 @@ conventions. Let's continue by adding more logic to our command::
                     'modified' => new DateTime()
                 ])
                 ->execute();
-                
+
             return static::CODE_SUCCESS;
         }
     }
@@ -397,7 +397,7 @@ Modify your test case to the following snippet of code::
 
         protected $fixtures = [
             // assumes you have a UsersFixture
-            'app.Users'
+            'app.Users',
         ];
 
         public function testDescriptionOutput()
@@ -477,7 +477,7 @@ Update the command class to the following::
                     'modified' => new DateTime()
                 ])
                 ->execute();
-                
+
             return static::CODE_SUCCESS;
         }
     }

en/console-commands/option-parsers.rst

@@ -74,7 +74,7 @@ If you have an array with multiple arguments you can use
 
     $parser->addArguments([
         'node' => ['help' => 'The node to create', 'required' => true],
-        'parent' => ['help' => 'The parent node', 'required' => true]
+        'parent' => ['help' => 'The parent node', 'required' => true],
     ]);
 
 As with all the builder methods on ConsoleOptionParser, addArguments
@@ -91,7 +91,7 @@ valid choices::
     $parser->addArgument('type', [
         'help' => 'The type of node to interact with.',
         'required' => true,
-        'choices' => ['aro', 'aco']
+        'choices' => ['aro', 'aco'],
     ]);
 
 The above will create an argument that is required and has validation on the
@@ -101,7 +101,7 @@ will be raised and the shell will be stopped.
 Using Options
 =============
 
-.. php:method:: addOption($name, $options = [])
+.. php:method:: addOption($name, array $options = [])
 
 Options or flags are used in command line tools to provide unordered key/value
 arguments for your commands. Options can define both verbose and short aliases.
@@ -154,7 +154,7 @@ to add multiple options at once. ::
 
     $parser->addOptions([
         'node' => ['short' => 'n', 'help' => 'The node to create'],
-        'parent' => ['short' => 'p', 'help' => 'The parent node']
+        'parent' => ['short' => 'p', 'help' => 'The parent node'],
     ]);
 
 As with all the builder methods on ConsoleOptionParser, addOptions can be used
@@ -169,7 +169,7 @@ for an option. All other values will raise an ``InvalidArgumentException``::
 
     $parser->addOption('accept', [
         'help' => 'What version to accept.',
-        'choices' => ['working', 'theirs', 'mine']
+        'choices' => ['working', 'theirs', 'mine'],
     ]);
 
 Using Boolean Options
@@ -204,14 +204,14 @@ subcommand parsers easier, as everything is an array::
             'description' => [
                 __("Use this command to grant ACL permissions. Once executed, the "),
                 __("ARO specified (and its children, if any) will have ALLOW access "),
-                __("to the specified ACO action (and the ACO's children, if any).")
+                __("to the specified ACO action (and the ACO's children, if any)."),
             ],
             'arguments' => [
                 'aro' => ['help' => __('ARO to check.'), 'required' => true],
                 'aco' => ['help' => __('ACO to check.'), 'required' => true],
-                'action' => ['help' => __('Action to check')]
-            ]
-        ]
+                'action' => ['help' => __('Action to check')],
+            ],
+        ],
     ]);
 
 Inside the parser spec, you can define keys for ``arguments``, ``options``,
@@ -232,8 +232,8 @@ use buildFromArray on its own, to build an option parser::
             'arguments' => [
                 'aro' => ['help' => __('ARO to check.'), 'required' => true],
                 'aco' => ['help' => __('ACO to check.'), 'required' => true],
-                'action' => ['help' => __('Action to check')]
-            ]
+                'action' => ['help' => __('Action to check')],
+            ],
         ]);
     }
 

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 request or load data
@@ -331,9 +331,9 @@ differently based on the controller action 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
 ==========================
@@ -476,8 +494,8 @@ behaves::
     {
         protected array $paginate = [
             'Articles' => [
-                'conditions' => ['published' => 1]
-            ]
+                'conditions' => ['published' => 1],
+            ],
         ];
     }
 

en/controllers/components.rst

@@ -78,7 +78,7 @@ implementation::
         public function initialize(): void
         {
             $this->loadComponent('Flash', [
-                'className' => 'MyFlash'
+                'className' => 'MyFlash',
             ]);
         }
     }
@@ -212,7 +212,7 @@ the Component::
         parent::initialize();
         $this->loadComponent('Math', [
             'precision' => 2,
-            'randomGenerator' => 'srand'
+            'randomGenerator' => 'srand',
         ]);
         $this->loadComponent('Csrf');
     }
@@ -234,7 +234,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/controllers/components/flash.rst

@@ -57,8 +57,8 @@ An example of using these options::
         'clear' => true,
         'params' => [
             'name' => $user->name,
-            'email' => $user->email
-        ]
+            'email' => $user->email,
+        ],
     ]);
 
     // In your View

en/controllers/pagination.rst

@@ -45,8 +45,8 @@ from the URL::
         protected array $paginate = [
             'limit' => 25,
             'order' => [
-                'Articles.title' => 'asc'
-            ]
+                'Articles.title' => 'asc',
+            ],
         ];
     }
 
@@ -215,8 +215,8 @@ pagination query::
 
     protected array $paginate = [
         'sortableFields' => [
-            'id', 'title', 'Users.username', 'created'
-        ]
+            'id', 'title', 'Users.username', 'created',
+        ],
     ];
 
 Any requests that attempt to sort on fields not in the allowed list will be