Merge branch '5.x' into 5.next

Author: ADmad

en/controllers/request-response.rst

@@ -251,20 +251,24 @@ replace all possibly existing uploaded files::
 PUT, PATCH or DELETE Data
 -------------------------
 
-.. php:method:: input($callback, [$options])
+.. php:method:: getBody()
 
 When building REST services, you often accept request data on ``PUT`` and
 ``DELETE`` requests. Any ``application/x-www-form-urlencoded`` request body data
-will automatically be parsed and set to ``$this->data`` for ``PUT`` and
-``DELETE`` requests. If you are accepting JSON or XML data, see below for how
-you can access those request bodies.
+will automatically be parsed and available via ``$request->getData()`` for ``PUT`` and
+``DELETE`` requests. If you are accepting JSON or XML data, you can
+access the raw data with ``getBody()``::
 
-When accessing the input data, you can decode it with an optional function.
-This is useful when interacting with XML or JSON request body content.
-Additional parameters for the decoding function can be passed as arguments to
-``input()``::
+    // Get the stream wrapper on the request body
+    $body = $request->getBody();
 
-    $jsonData = $this->request->input('json_decode');
+    // Get the request body as a string
+    $bodyString = (string)$request->getBody();
+
+If your requests contain XML or JSON request content, you should consider using
+:ref:`body-parser-middleware` to have CakePHP automatically parse those content
+types making the parsed data available in ``$request->getData()`` and
+``$request->getParsedBody()``.
 
 Environment Variables (from $_SERVER and $_ENV)
 -----------------------------------------------
@@ -953,7 +957,7 @@ that uniquely identifies the requested resource, as a checksum does for a file,
 in order to determine whether it matches a cached resource.
 
 To take advantage of this header, you must either call the
-``checkNotModified()`` method manually or include the
+``isNotModified()`` method manually or include the
 :doc:`/controllers/components/check-http-cache` in your controller::
 
     public function index()
@@ -966,7 +970,7 @@ To take advantage of this header, you must either call the
         $checksum = md5(json_encode($articles));
 
         $response = $this->response->withEtag($checksum);
-        if ($response->checkNotModified($this->request)) {
+        if ($response->isNotModified($this->request)) {
             return $response;
         }
 
@@ -990,14 +994,14 @@ last time. Setting this header helps CakePHP tell caching clients whether the
 response was modified or not based on their cache.
 
 To take advantage of this header, you must either call the
-``checkNotModified()`` method manually or include the
+``isNotModified()`` method manually or include the
 :doc:`/controllers/components/check-http-cache` in your controller::
 
     public function view()
     {
         $article = $this->Articles->find()->first();
         $response = $this->response->withModified($article->modified);
-        if ($response->checkNotModified($this->request)) {
+        if ($response->isNotModified($this->request)) {
             return $response;
         }
         $this->response;
@@ -1021,14 +1025,14 @@ header::
 Sending Not-Modified Responses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. php:method:: checkNotModified(Request $request)
+.. php:method:: isNotModified(Request $request)
 
 Compares the cache headers for the request object with the cache header from the
 response and determines whether it can still be considered fresh. If so, deletes
 the response content, and sends the `304 Not Modified` header::
 
     // In a controller action.
-    if ($this->response->checkNotModified($this->request)) {
+    if ($this->response->isNotModified($this->request)) {
         return $this->response;
     }
 

en/core-libraries/time.rst

@@ -31,19 +31,18 @@ use the ``DateTime`` class::
 
 Under the hood, CakePHP uses `Chronos <https://github.com/cakephp/chronos>`_
 to power its ``DateTime`` utility. Anything you can do with ``Chronos`` and
-PHP's ``DateTime``, you can do with ``DateTime`` and ``Date``.
+PHP's ``DateTimeImmutable``, you can do with ``DateTime``.
 
 For more details on Chronos please see `the API documentation
-<https://api.cakephp.org/chronos/1.0/>`_.
+<https://api.cakephp.org/chronos/>`_.
 
 .. start-time
 
 Creating DateTime Instances
-=============================
+===========================
 
-``DateTime`` are immutable objects that are useful when you want to prevent
-accidental changes to data, or when you want to avoid order based dependency
-issues.
+``DateTime`` are immutable objects as immutability prevents accidental changes
+to data, and avoids order based dependency issues.
 
 There are a few ways to create ``DateTime`` instances::
 
@@ -407,85 +406,25 @@ You can also compare a ``DateTime`` instance within a range in the past::
 Date
 ====
 
-.. php:class: Date
-
-The immutable ``Date`` class in CakePHP implements a similar API and methods as
-:php:class:`Cake\\I18n\\DateTime` does. The main difference between ``DateTime``
-and ``Date`` is that ``Date`` does not track time components. As an example::
-
-    use Cake\I18n\Date;
-
-    $date = new Date('2021-01-31');
-
-    $newDate = $date->modify('+2 hours');
-    // Outputs '2021-01-31 00:00:00'
-    echo $newDate->format('Y-m-d H:i:s');
-
-    $newDate = $date->addHours(36);
-    // Outputs '2021-01-31 00:00:00'
-    echo $newDate->format('Y-m-d H:i:s');
-
-    $newDate = $date->addDays(10);
-    // Outputs '2021-02-10 00:00:00'
-    echo $newDate->format('Y-m-d H:i:s');
-
-
-Attempts to modify the timezone on a ``Date`` instance are also ignored::
-
-    use Cake\I18n\Date;
-    $date = new Date('2021-01-31', new \DateTimeZone('America/New_York'));
-    $newDate = $date->setTimezone(new \DateTimeZone('Europe/Berlin'));
-
-    // Outputs 'America/New_York'
-    echo $newDate->format('e');
-
-.. _mutable-time:
-
-Mutable Dates and Times
-=======================
-
-.. php:class:: Time
 .. php:class:: Date
 
-CakePHP uses mutable date and time classes that implement the same interface
-as their immutable siblings. Immutable objects are useful when you want to prevent
-accidental changes to data, or when you want to avoid order based dependency
-issues. Take the following code::
-
-    use Cake\I18n\Time;
-    $time = new Time('2015-06-15 08:23:45');
-    $time->modify('+2 hours');
-
-    // This method also modifies the $time instance
-    $this->someOtherFunction($time);
-
-    // Output here is unknown.
-    echo $time->format('Y-m-d H:i:s');
-
-If the method call was re-ordered, or if ``someOtherFunction`` changed the
-output could be unexpected. The mutability of our object creates temporal
-coupling. If we were to use immutable objects, we could avoid this issue::
+The immutable ``Date`` class in CakePHP represents calendar dates unaffected by
+time and timezones. The ``Date`` class wraps the ``Cake\\Chronos\\ChronosDate`` class.
 
-    use Cake\I18n\DateTime;
-    $time = new DateTime('2015-06-15 08:23:45');
-    $time = $time->modify('+2 hours');
-
-    // This method's modifications don't change $time
-    $this->someOtherFunction($time);
+.. note::
 
-    // Output here is known.
-    echo $time->format('Y-m-d H:i:s');
+    Unlike the ``DateTime`` class, ``Date`` does not extends the ``DateTimeInterface``.
+    So you cannot cannot directly compare a ``Date`` instance with a ``DateTime`` instance.
+    But you can do comparisons like ``$dateTime->toNative() > $date->toNative()``.
 
-Immutable dates and times are useful in entities as they prevent
-accidental modifications, and force changes to be explicit. Using
-immutable objects helps the ORM to more easily track changes, and ensure that
-date and datetime columns are persisted correctly::
+Time
+====
 
-    // This change will be lost when the article is saved.
-    $article->updated->modify('+1 hour');
+.. php:class:: Time
 
-    // By replacing the time object the property will be saved.
-    $article->updated = $article->updated->modify('+1 hour');
+The ``Time`` class represents clock times independent of date or time zones
+Similar to the ``DateTime`` and ```Date`` classes, the ``Time`` class is also immutable.
+It wraps the ``Cake\\Chronos\\ChronosTime`` class.
 
 Accepting Localized Request Data
 ================================

en/index.rst

@@ -5,7 +5,7 @@ CakePHP 5 is a web development framework running on PHP |phpversion| (min. PHP
 |minphpversion|). Read :doc:`CakePHP at a Glance </intro>` to get an
 introduction to the fundamentals of CakePHP.
 
-The CakePHP cookbook is an openly developed and community editable documentation
+The CakePHP book is an openly developed and community editable documentation
 project. Notice the pencil icon button fixated against the right wall; it will
 direct you to the GitHub online editor of the active page, allowing you to
 contribute any additions, deletions, or corrections to the documentation.
@@ -16,7 +16,7 @@ contribute any additions, deletions, or corrections to the documentation.
 
     .. image:: /_static/img/read-the-book.jpg
 
-    Enjoy the CakePHP cookbook almost anywhere. Available as both a PDF and
+    Enjoy the CakePHP book almost anywhere. Available as both a PDF and
     EPUB, you can now read it on more devices, as well as offline.
 
     - `PDF <../_downloads/en/CakePHPBook.pdf>`_
@@ -53,5 +53,5 @@ elements in a CakePHP application:
   validation, and domain logic within your application.
 
 .. meta::
-    :title lang=en: .. CakePHP Cookbook documentation master file, created by
-    :keywords lang=en: doc models,documentation master,presentation layer,documentation project,quickstart,original source,sphinx,liking,cookbook,validity,conventions,validation,cakephp,accuracy,storage and retrieval,heart,blog,project hope
+    :title lang=en: .. CakePHP book documentation master file, created by
+    :keywords lang=en: doc models,documentation master,presentation layer,documentation project,quickstart,original source,sphinx,liking,book,validity,conventions,validation,cakephp,accuracy,storage and retrieval,heart,blog,project hope

en/tutorials-and-examples/cms/articles-model.rst

@@ -59,12 +59,15 @@ look like this::
     class Article extends Entity
     {
         protected array $_accessible = [
+            'user_id' => true,
             'title' => true,
+            'slug' => true,
             'body' => true,
             'published' => true,
             'created' => true,
             'modified' => true,
-            'users' => true,
+            'user' => true,
+            'tags' => true,
         ];
     }