Merge remote-tracking branch 'upstream/develop' into 4.4

app/Config/Cache.php

@@ -53,12 +53,12 @@ class Cache extends BaseConfig
      * Whether to take the URL query string into consideration when generating
      * output cache files. Valid options are:
      *
-     *    false      = Disabled
-     *    true       = Enabled, take all query parameters into account.
-     *                 Please be aware that this may result in numerous cache
-     *                 files generated for the same page over and over again.
-     *    array('q') = Enabled, but only take into account the specified list
-     *                 of query parameters.
+     *    false = Disabled
+     *    true  = Enabled, take all query parameters into account.
+     *            Please be aware that this may result in numerous cache
+     *            files generated for the same page over and over again.
+     *    ['q'] = Enabled, but only take into account the specified list
+     *            of query parameters.
      *
      * @var bool|string[]
      */

phpstan-baseline.neon.dist

@@ -155,11 +155,6 @@ parameters:
 			count: 1
 			path: system/Helpers/filesystem_helper.php
 
-		-
-			message: "#^Binary operation \"\\+\" between 0 and string results in an error\\.$#"
-			count: 1
-			path: system/Helpers/number_helper.php
-
 		-
 			message: "#^Property CodeIgniter\\\\Images\\\\Handlers\\\\BaseHandler\\:\\:\\$image \\(CodeIgniter\\\\Images\\\\Image\\) in empty\\(\\) is not falsy\\.$#"
 			count: 1

system/Format/FormatterInterface.php

@@ -19,7 +19,7 @@ interface FormatterInterface
     /**
      * Takes the given data and formats it.
      *
-     * @param array|string $data
+     * @param array|object|string $data
      *
      * @return false|string
      */

system/HTTP/ResponseTrait.php

@@ -239,7 +239,7 @@ public function setContentType(string $mime, string $charset = 'UTF-8')
     /**
      * Converts the $body into JSON and sets the Content Type header.
      *
-     * @param array|string $body
+     * @param array|object|string $body
      *
      * @return $this
      */
@@ -304,8 +304,8 @@ public function getXML()
      * Handles conversion of the data into the appropriate format,
      * and sets the correct Content-Type header for our response.
      *
-     * @param array|string $body
-     * @param string       $format Valid: json, xml
+     * @param array|object|string $body
+     * @param string              $format Valid: json, xml
      *
      * @return mixed
      *

system/Helpers/array_helper.php

@@ -41,7 +41,7 @@ function dot_array_search(string $index, array $array)
      *
      * @internal This should not be used on its own.
      *
-     * @return mixed
+     * @return array|bool|float|int|object|string|null
      */
     function _array_search_dot(array $indexes, array $array)
     {
@@ -103,9 +103,9 @@ function _array_search_dot(array $indexes, array $array)
     /**
      * Returns the value of an element at a key in an array of uncertain depth.
      *
-     * @param mixed $key
+     * @param int|string $key
      *
-     * @return mixed|null
+     * @return array|bool|float|int|object|string|null
      */
     function array_deep_search($key, array $array)
     {

system/Helpers/cookie_helper.php

@@ -83,7 +83,7 @@ function get_cookie($index, bool $xssClean = false, ?string $prefix = '')
     /**
      * Delete a cookie
      *
-     * @param mixed  $name
+     * @param string $name
      * @param string $domain the cookie domain. Usually: .yourdomain.com
      * @param string $path   the cookie path
      * @param string $prefix the cookie prefix

system/Helpers/filesystem_helper.php

@@ -292,8 +292,8 @@ function get_dir_file_info(string $sourceDir, bool $topLevelOnly = true, bool $r
      * Options are: name, server_path, size, date, readable, writable, executable, fileperms
      * Returns false if the file cannot be found.
      *
-     * @param string $file           Path to file
-     * @param mixed  $returnedValues Array or comma separated string of information returned
+     * @param string       $file           Path to file
+     * @param array|string $returnedValues Array or comma separated string of information returned
      *
      * @return array|null
      */

system/Helpers/number_helper.php

@@ -15,8 +15,8 @@
     /**
      * Formats a numbers as bytes, based on size, and adds the appropriate suffix
      *
-     * @param mixed  $num    Will be cast as int
-     * @param string $locale
+     * @param int|string $num    Will be cast as int
+     * @param string     $locale
      *
      * @return bool|string
      */
@@ -69,14 +69,15 @@ function number_to_size($num, int $precision = 1, ?string $locale = null)
      *
      * @see https://simple.wikipedia.org/wiki/Names_for_large_numbers
      *
-     * @param string $num
+     * @param int|string $num
      *
      * @return bool|string
      */
     function number_to_amount($num, int $precision = 0, ?string $locale = null)
     {
         // Strip any formatting & ensure numeric input
         try {
+            // @phpstan-ignore-next-line
             $num = 0 + str_replace(',', '', $num);
         } catch (ErrorException $ee) {
             return false;

system/Helpers/text_helper.php

@@ -410,10 +410,10 @@ function word_wrap(string $str, int $charlim = 76): string
      *
      * This function will strip tags from a string, split it at its max_length and ellipsize
      *
-     * @param string $str       String to ellipsize
-     * @param int    $maxLength Max length of string
-     * @param mixed  $position  int (1|0) or float, .5, .2, etc for position to split
-     * @param string $ellipsis  ellipsis ; Default '...'
+     * @param string    $str       String to ellipsize
+     * @param int       $maxLength Max length of string
+     * @param float|int $position  int (1|0) or float, .5, .2, etc for position to split
+     * @param string    $ellipsis  ellipsis ; Default '...'
      *
      * @return string Ellipsized string
      */
@@ -446,9 +446,9 @@ function ellipsize(string $str, int $maxLength, $position = 1, string $ellipsis
      *
      * Removes slashes contained in a string or in an array
      *
-     * @param mixed $str string or array
+     * @param array|string $str string or array
      *
-     * @return mixed string or array
+     * @return array|string string or array
      */
     function strip_slashes($str)
     {

tests/system/Test/FeatureTestTraitTest.php

@@ -390,20 +390,6 @@ public function testCallWithJsonRequest()
         $response->assertJSONExact(['foo' => 'bar']);
     }
 
-    public function testCallWithJsonRequestObject()
-    {
-        $this->withRoutes([
-            [
-                'post',
-                'home',
-                '\Tests\Support\Controllers\Popcorn::echoJson',
-            ],
-        ]);
-        $response = $this->withBodyFormat('json')->call('post', 'home', ['foo' => 'bar']);
-        $response->assertOK();
-        $response->assertJSONExact((object) ['foo' => 'bar']);
-    }
-
     public function testSetupRequestBodyWithParams()
     {
         $request = $this->setupRequest('post', 'home');

tests/system/Test/TestResponseTest.php

@@ -299,13 +299,15 @@ public function testAssertCookieExpired()
 
     public function testGetJSON()
     {
-        $this->getTestResponse(['foo' => 'bar']);
-        $formatter = Services::format()->getFormatter('application/json');
+        $data = ['foo' => 'bar'];
+        $this->getTestResponse('');
+        $this->response->setJSON($data, true);
 
-        $this->assertSame($formatter->format(['foo' => 'bar']), $this->testResponse->getJSON());
+        $formatter = Services::format()->getFormatter('application/json');
+        $this->assertSame($formatter->format($data), $this->testResponse->getJSON());
     }
 
-    public function testEmptyJSON()
+    public function testGetJSONEmptyJSON()
     {
         $this->getTestResponse('<h1>Hello World</h1>');
         $this->response->setJSON('', true);
@@ -314,7 +316,7 @@ public function testEmptyJSON()
         $this->assertSame('""', $this->testResponse->getJSON());
     }
 
-    public function testFalseJSON()
+    public function testGetJSONFalseJSON()
     {
         $this->getTestResponse('<h1>Hello World</h1>');
         $this->response->setJSON(false, true);
@@ -323,7 +325,7 @@ public function testFalseJSON()
         $this->assertSame('false', $this->testResponse->getJSON());
     }
 
-    public function testTrueJSON()
+    public function testGetJSONTrueJSON()
     {
         $this->getTestResponse('<h1>Hello World</h1>');
         $this->response->setJSON(true, true);
@@ -332,7 +334,7 @@ public function testTrueJSON()
         $this->assertSame('true', $this->testResponse->getJSON());
     }
 
-    public function testInvalidJSON()
+    public function testGetJSONInvalidJSON()
     {
         $tmp = ' test " case ';
         $this->getTestResponse('<h1>Hello World</h1>');
@@ -344,30 +346,36 @@ public function testInvalidJSON()
 
     public function testGetXML()
     {
-        $this->getTestResponse(['foo' => 'bar']);
-        $formatter = Services::format()->getFormatter('application/xml');
+        $data = ['foo' => 'bar'];
+        $this->getTestResponse('');
+        $this->response->setXML($data);
 
-        $this->assertSame($formatter->format(['foo' => 'bar']), $this->testResponse->getXML());
+        $formatter = Services::format()->getFormatter('application/xml');
+        $this->assertSame($formatter->format($data), $this->testResponse->getXML());
     }
 
-    public function testJsonFragment()
+    public function testAssertJSONFragment()
     {
-        $this->getTestResponse([
+        $data = [
             'config' => [
                 'key-a',
                 'key-b',
             ],
-        ]);
+        ];
+        $this->getTestResponse('');
+        $this->response->setJSON($data, true);
 
         $this->testResponse->assertJSONFragment(['config' => ['key-a']]);
         $this->testResponse->assertJSONFragment(['config' => ['key-a']], true);
     }
 
     public function testAssertJSONFragmentFollowingAssertArraySubset()
     {
-        $this->getTestResponse([
+        $data = [
             'config' => '124',
-        ]);
+        ];
+        $this->getTestResponse('');
+        $this->response->setJSON($data, true);
 
         $this->testResponse->assertJSONFragment(['config' => 124]); // must fail on strict
         $this->testResponse->assertJSONFragment(['config' => '124'], true);
@@ -383,36 +391,50 @@ public function testAssertJSONFragmentFailsGracefullyWhenNotGivenJson()
         $this->testResponse->assertJSONFragment(['foo' => 'bar']);
     }
 
-    public function testJsonExact()
+    public function testAssertJsonExactArray()
     {
         $data = [
             'config' => [
                 'key-a',
                 'key-b',
             ],
         ];
+        $this->getTestResponse('');
+        $this->response->setJSON($data, true);
+
+        $this->testResponse->assertJSONExact($data);
+    }
 
-        $this->getTestResponse($data);
+    public function testAssertJsonExactObject()
+    {
+        $data = (object) [
+            'config' => [
+                'key-a',
+                'key-b',
+            ],
+        ];
+        $this->getTestResponse('');
+        $this->response->setJSON($data, true);
 
         $this->testResponse->assertJSONExact($data);
     }
 
-    public function testJsonExactString()
+    public function testAssertJsonExactString()
     {
         $data = [
             'config' => [
                 'key-a',
                 'key-b',
             ],
         ];
+        $this->getTestResponse('');
+        $this->response->setJSON($data, true);
 
-        $this->getTestResponse($data);
         $formatter = Services::format()->getFormatter('application/json');
-
         $this->testResponse->assertJSONExact($formatter->format($data));
     }
 
-    protected function getTestResponse($body = null, array $responseOptions = [], array $headers = [])
+    protected function getTestResponse(?string $body = null, array $responseOptions = [], array $headers = [])
     {
         $this->response = new Response(new App());
         $this->response->setBody($body);

user_guide_src/source/general/caching.rst

@@ -21,15 +21,42 @@ How Does Caching Work?
 
 Caching can be enabled on a per-page basis, and you can set the length
 of time that a page should remain cached before being refreshed. When a
-page is loaded for the first time, the file will be cached using the
-currently configured cache engine. On subsequent page loads, the cache file
+page is loaded for the first time, the page will be cached using the
+currently configured cache engine. On subsequent page loads, the cache
 will be retrieved and sent to the requesting user's browser. If it has
 expired, it will be deleted and refreshed before being sent to the
 browser.
 
 .. note:: The Benchmark tag is not cached so you can still view your page
     load speed when caching is enabled.
 
+Configuring Caching
+===================
+
+Setting Cache Engine
+--------------------
+
+Before using Web Page Caching, you must set the cache engine up by editing
+**app/Config/Cache.php**. See :ref:`libraries-caching-configuring-the-cache`
+for details.
+
+Setting $cacheQueryString
+-------------------------
+
+You can set whether or not to include the query string when generating the cache
+with ``Config\Cache::$cacheQueryString``.
+
+Valid options are:
+
+- ``false``: (default) Disabled. The query string is not taken into account; the
+  same cache is returned for requests with the same URI path but different query
+  strings.
+- ``true``: Enabled, take all query parameters into account. Be aware that this
+  may result in numerous cache generated for the same page over and over
+  again.
+- **array**: Enabled, but only take into account the specified list of query
+  parameters. E.g., ``['q', 'page']``.
+
 Enabling Caching
 ================
 
@@ -46,15 +73,12 @@ the order that it appears, so place it wherever it seems most logical to
 you. Once the tag is in place, your pages will begin being cached.
 
 .. important:: If you change configuration options that might affect
-    your output, you have to manually delete your cache files.
-
-.. note:: Before the cache files can be written you must set the cache
-    engine up by editing **app/Config/Cache.php**.
+    your output, you have to manually delete your cache.
 
 Deleting Caches
 ===============
 
-If you no longer wish to cache a file you can remove the caching tag and
+If you no longer wish to cache a page you can remove the caching tag and
 it will no longer be refreshed when it expires.
 
 .. note:: Removing the tag will not delete the cache immediately. It will

user_guide_src/source/libraries/caching.rst

@@ -23,6 +23,8 @@ You can grab an instance of the cache engine directly through the Services class
 
 .. literalinclude:: caching/002.php
 
+.. _libraries-caching-configuring-the-cache:
+
 *********************
 Configuring the Cache
 *********************