Merge branch '5.x' into 5.next

en/appendices.rst

@@ -4,15 +4,10 @@ Appendices
 Appendices contain information regarding the new features
 introduced in each version and the migration path between versions.
 
-5.x Migration Guide
-===================
-
-.. toctree::
-    :maxdepth: 1
+Migration Guides
+================
 
-    appendices/5-0-upgrade-guide
-    appendices/5-0-migration-guide
-    appendices/5-1-migration-guide
+:doc:`appendices/migration-guides`
 
 Backwards Compatibility Shimming
 ================================

en/console-commands/option-parsers.rst

@@ -197,8 +197,8 @@ Building a ConsoleOptionParser from an Array
 Option parsers can also be defined as arrays. Within the array, you can define
 keys for ``arguments``, ``options``, ``description`` and ``epilog``.  The values
 for arguments, and options, should follow the format that
-:php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` and
-:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also
+:php:func:`\\Cake\\Console\\ConsoleOptionParser::addArguments()` and
+:php:func:`\\Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also
 use ``buildFromArray`` on its own, to build an option parser::
 
     public function getOptionParser()

en/controllers.rst

@@ -39,7 +39,7 @@ The App Controller
 
 As stated in the introduction, the ``AppController`` class is the parent class
 to all of your application's controllers.  ``AppController`` itself extends the
-:php:class:`Cake\\Controller\\Controller` class included in CakePHP.
+:php:class:`\\Cake\\Controller\\Controller` class included in CakePHP.
 ``AppController`` is defined in **src/Controller/AppController.php** as
 follows::
 
@@ -77,7 +77,7 @@ Request Flow
 ============
 
 When a request is made to a CakePHP application, CakePHP's
-:php:class:`Cake\\Routing\\Router` and :php:class:`Cake\\Routing\\Dispatcher`
+:php:class:`\\Cake\\Routing\\Router` and :php:class:`\\Cake\\Routing\\Dispatcher`
 classes use :ref:`routes-configuration` to find and create the correct
 controller instance. The request data is encapsulated in a request object.
 CakePHP puts all of the important request information into the ``$this->request``
@@ -130,7 +130,7 @@ once a controller action has completed, CakePHP will handle rendering and
 delivering the View.
 
 If for some reason you'd like to skip the default behavior, you can return a
-:php:class:`Cake\\Http\\Response` object from the action with the fully
+:php:class:`\\Cake\\Http\\Response` object from the action with the fully
 created response.
 
 In order for you to use a controller effectively in your own application, we'll
@@ -548,7 +548,7 @@ methods are implemented by your controllers
     Called during the ``Controller.beforeRender`` event which occurs after
     controller action logic, but before the view is rendered. This callback is
     not used often, but may be needed if you are calling
-    :php:meth:`~Cake\\Controller\\Controller::render()` manually before the end
+    :php:meth:`\\Cake\\Controller\\Controller::render()` manually before the end
     of a given action.
 
 .. php:method:: afterFilter(EventInterface $event)

en/controllers/components/form-protection.rst

@@ -19,8 +19,8 @@ in your ``initialize()`` method.
     your forms. In addition, you must **not** override any of the fields' "name"
     attributes. The FormProtection Component looks for certain indicators that are
     created and managed by the FormHelper (especially those created in
-    :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` and
-    :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`).  Dynamically altering
+    :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` and
+    :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`).  Dynamically altering
     the fields that are submitted in a POST request, such as disabling, deleting
     or creating new fields via JavaScript, is likely to cause the form token
     validation to fail.

en/controllers/request-response.rst

@@ -133,7 +133,7 @@ Request Body Data
 .. php:method:: getData($name, $default = null)
 
 All POST data normally available through PHP's ``$_POST`` global variable can be
-accessed using :php:meth:`Cake\\Http\\ServerRequest::getData()`. For example::
+accessed using :php:meth:`\\Cake\\Http\\ServerRequest::getData()`. For example::
 
     // An input with a name attribute equal to 'title' is accessible at
     $title = $this->request->getData('title');
@@ -160,7 +160,7 @@ If you want to access all the data parameters you can use
 File Uploads
 ------------
 
-Uploaded files can be accessed through the request body data, using the :php:meth:`Cake\\Http\\ServerRequest::getData()`
+Uploaded files can be accessed through the request body data, using the :php:meth:`\\Cake\\Http\\ServerRequest::getData()`
 method described above. For example, a file from an input element with a name attribute of ``attachment``, can
 be accessed like this::
 
@@ -195,11 +195,11 @@ origins, which makes testing file uploads possible.
 .. php:method:: getUploadedFile($path)
 
 Returns the uploaded file at a specific path. The path uses the same dot syntax as the
-:php:meth:`Cake\\Http\\ServerRequest::getData()` method::
+:php:meth:`\\Cake\\Http\\ServerRequest::getData()` method::
 
     $attachment = $this->request->getUploadedFile('attachment');
 
-Unlike :php:meth:`Cake\\Http\\ServerRequest::getData()`, :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` would
+Unlike :php:meth:`\\Cake\\Http\\ServerRequest::getData()`, :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` would
 only return data when an actual file upload exists for the given path, if there is regular, non-file request body data
 present at the given path, then this method will return ``null``, just like it would for any non-existent path.
 
@@ -244,9 +244,9 @@ replace all possibly existing uploaded files::
 .. note::
 
     Uploaded files that have been added to the request via this method, will *not* be available in the request body
-    data, ie you cannot retrieve them via :php:meth:`Cake\\Http\\ServerRequest::getData()`! If you need them in the
-    request data (too), then you have to set them via :php:meth:`Cake\\Http\\ServerRequest::withData()` or
-    :php:meth:`Cake\\Http\\ServerRequest::withParsedBody()`.
+    data, ie you cannot retrieve them via :php:meth:`\\Cake\\Http\\ServerRequest::getData()`! If you need them in the
+    request data (too), then you have to set them via :php:meth:`\\Cake\\Http\\ServerRequest::withData()` or
+    :php:meth:`\\Cake\\Http\\ServerRequest::withParsedBody()`.
 
 PUT, PATCH or DELETE Data
 -------------------------
@@ -341,7 +341,7 @@ conditions, as well as inspect other application specific request criteria::
     $isPost = $this->request->is('post');
 
 You can also extend the request detectors that are available, by using
-:php:meth:`Cake\\Http\\ServerRequest::addDetector()` to create new kinds of
+:php:meth:`\\Cake\\Http\\ServerRequest::addDetector()` to create new kinds of
 detectors. There are different types of detectors that you can create:
 
 * Environment value comparison - Compares a value fetched from :php:func:`env()`
@@ -431,9 +431,9 @@ There are several built-in detectors that you can use:
   'application/xml' or 'text/xml'.
 
 ``ServerRequest`` also includes methods like
-:php:meth:`Cake\\Http\\ServerRequest::domain()`,
-:php:meth:`Cake\\Http\\ServerRequest::subdomains()` and
-:php:meth:`Cake\\Http\\ServerRequest::host()` to make applications that use
+:php:meth:`\\Cake\\Http\\ServerRequest::domain()`,
+:php:meth:`\\Cake\\Http\\ServerRequest::subdomains()` and
+:php:meth:`\\Cake\\Http\\ServerRequest::host()` to make applications that use
 subdomains simpler.
 
 Session Data
@@ -602,7 +602,7 @@ Request cookies can be read through a number of methods::
     // Get a CookieCollection instance
     $cookies = $this->request->getCookieCollection()
 
-See the :php:class:`Cake\\Http\\Cookie\\CookieCollection` documentation for how
+See the :php:class:`\\Cake\\Http\\Cookie\\CookieCollection` documentation for how
 to work with cookie collection.
 
 
@@ -645,7 +645,7 @@ Response
 
 .. php:class:: Response
 
-:php:class:`Cake\\Http\\Response` is the default response class in CakePHP.
+:php:class:`\\Cake\\Http\\Response` is the default response class in CakePHP.
 It encapsulates a number of features and functionality for generating HTTP
 responses in your application. It also assists in testing, as it can be
 mocked/stubbed allowing you to inspect headers that will be sent.
@@ -664,7 +664,7 @@ Dealing with Content Types
 .. php:method:: withType($contentType = null)
 
 You can control the Content-Type of your application's responses with
-:php:meth:`Cake\\Http\\Response::withType()`. If your application needs to deal
+:php:meth:`\\Cake\\Http\\Response::withType()`. If your application needs to deal
 with content types that are not built into Response, you can map them with
 ``setTypeMap()`` as well::
 
@@ -686,7 +686,7 @@ Sending Files
 .. php:method:: withFile(string $path, array $options = [])
 
 There are times when you want to send files as responses for your requests.
-You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`::
+You can accomplish that by using :php:meth:`\\Cake\\Http\\Response::withFile()`::
 
     public function sendFile($id)
     {
@@ -700,8 +700,8 @@ You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`::
 As shown in the above example, you must pass the file path to the method.
 CakePHP will send a proper content type header if it's a known file type listed
 in `Cake\\Http\\Response::$_mimeTypes`. You can add new types prior to calling
-:php:meth:`Cake\\Http\\Response::withFile()` by using the
-:php:meth:`Cake\\Http\\Response::withType()` method.
+:php:meth:`\\Cake\\Http\\Response::withFile()` by using the
+:php:meth:`\\Cake\\Http\\Response::withType()` method.
 
 If you want, you can also force a file to be downloaded instead of displayed in
 the browser by specifying the options::
@@ -749,7 +749,7 @@ Setting Headers
 
 .. php:method:: withHeader($header, $value)
 
-Setting headers is done with the :php:meth:`Cake\\Http\\Response::withHeader()`
+Setting headers is done with the :php:meth:`\\Cake\\Http\\Response::withHeader()`
 method. Like all of the PSR-7 interface methods, this method returns a *new*
 instance with the new header::
 
@@ -767,7 +767,7 @@ Headers are not sent when set. Instead, they are held until the response is
 emitted by ``Cake\Http\Server``.
 
 You can now use the convenience method
-:php:meth:`Cake\\Http\\Response::withLocation()` to directly set or get the
+:php:meth:`\\Cake\\Http\\Response::withLocation()` to directly set or get the
 redirect location header.
 
 Setting the Body
@@ -833,7 +833,7 @@ Interacting with Browser Caching
 .. php:method:: withDisabledCache()
 
 You sometimes need to force browsers not to cache the results of a controller
-action. :php:meth:`Cake\\Http\\Response::withDisabledCache()` is intended for just
+action. :php:meth:`\\Cake\\Http\\Response::withDisabledCache()` is intended for just
 that::
 
     public function index()
@@ -850,7 +850,7 @@ that::
 .. php:method:: withCache($since, $time = '+1 day')
 
 You can also tell clients that you want them to cache responses. By using
-:php:meth:`Cake\\Http\\Response::withCache()`::
+:php:meth:`\\Cake\\Http\\Response::withCache()`::
 
     public function index()
     {
@@ -878,7 +878,7 @@ Rather than forcing you to code the logic for caching and for invalidating
 (refreshing) it once the data has changed, HTTP uses two models, expiration and
 validation, which usually are much simpler to use.
 
-Apart from using :php:meth:`Cake\\Http\\Response::withCache()`, you can also use
+Apart from using :php:meth:`\\Cake\\Http\\Response::withCache()`, you can also use
 many other methods to fine-tune HTTP cache headers to take advantage of browser
 or reverse proxy caching.
 
@@ -1040,7 +1040,7 @@ the response content, and sends the `304 Not Modified` header::
 Setting Cookies
 ---------------
 
-Cookies can be added to response using either an array or a :php:class:`Cake\\Http\\Cookie\\Cookie`
+Cookies can be added to response using either an array or a :php:class:`\\Cake\\Http\\Cookie\\Cookie`
 object::
 
     use Cake\Http\Cookie\Cookie;

en/core-libraries/caching.rst

@@ -36,7 +36,7 @@ build your own backend. The built-in caching engines are:
   operations.
 
 Regardless of the CacheEngine you choose to use, your application interacts with
-:php:class:`Cake\\Cache\\Cache`.
+:php:class:`\\Cake\\Cache\\Cache`.
 
 .. _cache-configuration:
 
@@ -110,8 +110,8 @@ You can also configure Cache engines at runtime::
     Cache::setConfig('other', $object);
 
 The name of these engine configurations ('short' and 'long') are used as the ``$config``
-parameter for :php:meth:`Cake\\Cache\\Cache::write()` and
-:php:meth:`Cake\\Cache\\Cache::read()`. When configuring cache engines you can
+parameter for :php:meth:`\\Cake\\Cache\\Cache::write()` and
+:php:meth:`\\Cake\\Cache\\Cache::read()`. When configuring cache engines you can
 refer to the class name using the following syntaxes::
 
     // Short name (in App\ or Cake namespaces)
@@ -243,8 +243,8 @@ Removing Configured Cache Engines
 .. php:staticmethod:: drop($key)
 
 Once a configuration is created you cannot change it. Instead you should drop
-the configuration and re-create it using :php:meth:`Cake\\Cache\\Cache::drop()` and
-:php:meth:`Cake\\Cache\\Cache::setConfig()`. Dropping a cache engine will remove
+the configuration and re-create it using :php:meth:`\\Cake\\Cache\\Cache::drop()` and
+:php:meth:`\\Cake\\Cache\\Cache::setConfig()`. Dropping a cache engine will remove
 the config and destroy the adapter if it was constructed.
 
 Writing to a Cache
@@ -488,7 +488,7 @@ Using Cache to Store Common Query Results
 You can greatly improve the performance of your application by putting results
 that infrequently change, or that are subject to heavy reads into the cache.
 A perfect example of this are the results from
-:php:meth:`Cake\\ORM\\Table::find()`. The Query object allows you to cache
+:php:meth:`\\Cake\\ORM\\Table::find()`. The Query object allows you to cache
 results using the ``cache()`` method. See the :ref:`caching-query-results` section
 for more information.
 
@@ -594,7 +594,7 @@ dot syntax::
         // ...
     ]);
 
-Custom Cache engines must extend :php:class:`Cake\\Cache\\CacheEngine` which
+Custom Cache engines must extend :php:class:`\\Cake\\Cache\\CacheEngine` which
 defines a number of abstract methods as well as provides a few initialization
 methods.
 

en/core-libraries/collections.rst

@@ -169,7 +169,7 @@ This last example uses ``toList()`` unlike other examples, which is important
 when we're getting results with possibly duplicate keys. By using ``toList()``
 we'll be guaranteed to get all values even if there are duplicate keys.
 
-Unlike :php:meth:`Cake\\Utility\\Hash::extract()` this method only supports the
+Unlike :php:meth:`\\Cake\\Utility\\Hash::extract()` this method only supports the
 ``{*}`` wildcard. All other wildcard and attributes matchers are not supported.
 
 .. php:method:: combine($keyPath, $valuePath, $groupPath = null)

en/core-libraries/events.rst

@@ -152,6 +152,43 @@ application.
 * :ref:`Controller events <controller-life-cycle>`
 * :ref:`View events <view-events>`
 
+``Server.terminate``
+--------------------
+
+The ``Server.terminate`` event is triggered after the response has been sent to the
+client. This event is useful for performing tasks that should be done after the
+response has been sent, such as logging or sending emails.
+
+You can listen to this event using an event manager instance::
+
+    use Cake\Event\EventManager;
+
+    EventManager::instance()->on('Server.terminate', function ($event) {
+        // Perform tasks that should be done after the response has been
+        // sent to the client.
+    });
+
+Or using the ``events`` hook in your Application/Plugin class::
+
+    use Cake\Event\EventManagerInterface;
+
+    public function events(EventManagerInterface $eventManager): EventManagerInterface
+    {
+        $eventManager->on('Server.terminate', function ($event) {
+            // Perform tasks that should be done after the response has been
+            // sent to the client.
+        });
+
+        return $eventManager;
+    }
+
+.. tip::
+    This is called even if an exception is thrown during the request, e.g. on 404 pages.
+
+.. note::
+    The ``Server.terminate`` event only works for PHP-FPM implementations which
+    support the ``fastcgi_finish_request`` function.
+
 .. _registering-event-listeners:
 
 Registering Listeners
@@ -204,7 +241,7 @@ of the ``EventListener`` interface. Internally, the event manager will use
 As of CakePHP 5.1 it is recommended to register event listeners by adding them via the ``events`` hook in your application or plugin class::
 
     namespace App;
-    
+
     use App\Event\UserStatistic;
     use Cake\Event\EventManagerInterface;
     use Cake\Http\BaseApplication;

en/core-libraries/form.rst

@@ -53,7 +53,7 @@ In the above example we see the 3 hook methods that forms provide:
 
 * ``_buildSchema`` is used to define the schema data that is used by FormHelper
   to create an HTML form. You can define field type, length, and precision.
-* ``validationDefault`` Gets a :php:class:`Cake\\Validation\\Validator` instance
+* ``validationDefault`` Gets a :php:class:`\\Cake\\Validation\\Validator` instance
   that you can attach validators to.
 * ``_execute`` lets you define the behavior you want to happen when
   ``execute()`` is called and the data is valid.

en/core-libraries/global-constants-and-functions.rst

@@ -105,7 +105,7 @@ aliases for *all* functions listed below.
 
 .. php:function:: collection(mixed $items)
 
-    Convenience wrapper for instantiating a new :php:class:`Cake\\Collection\\Collection`
+    Convenience wrapper for instantiating a new :php:class:`\\Cake\\Collection\\Collection`
     object, wrapping the passed argument. The ``$items`` parameter takes either
     a ``Traversable`` object or an array.