Merge pull request #6959 from kenjis/fix-phpdoc-types

kenjis · web-flow · commit a0554f34fc32 · 2022-12-09T09:07:23.000+09:00
docs: fix phpdoc types
diff --git a/system/API/ResponseTrait.php b/system/API/ResponseTrait.php
@@ -66,7 +66,7 @@ trait ResponseTrait
     /**
      * How to format the response data.
      * Either 'json' or 'xml'. If blank will be
-     * determine through content negotiation.
+     * determined through content negotiation.
      *
      * @var string
      */
diff --git a/system/Common.php b/system/Common.php
@@ -63,6 +63,7 @@ function app_timezone(): string
      *    $foo = cache('bar');
      *
      * @return CacheInterface|mixed
+     * @phpstan-return ($key is null ? CacheInterface : mixed)
      */
     function cache(?string $key = null)
     {
@@ -196,7 +197,7 @@ function command(string $command)
     /**
      * More simple way of getting config instances from Factories
      *
-     * @return mixed
+     * @return object|null
      */
     function config(string $name, bool $getShared = true)
     {
@@ -376,7 +377,7 @@ function dd(...$vars)
      *
      * @param string|null $default
      *
-     * @return mixed
+     * @return bool|string|null
      */
     function env(string $key, $default = null)
     {
@@ -952,7 +953,7 @@ function session(?string $val = null)
      *
      * @param mixed ...$params
      *
-     * @return mixed
+     * @return object
      */
     function service(string $name, ...$params)
     {
@@ -966,7 +967,7 @@ function service(string $name, ...$params)
      *
      * @param mixed ...$params
      *
-     * @return mixed
+     * @return object|null
      */
     function single_service(string $name, ...$params)
     {
@@ -1076,7 +1077,7 @@ function stringify_attributes($attributes, bool $js = false): string
      * If no parameter is passed, it will return the timer instance,
      * otherwise will start or stop the timer intelligently.
      *
-     * @return mixed|Timer
+     * @return Timer
      */
     function timer(?string $name = null)
     {
diff --git a/system/Config/Factories.php b/system/Config/Factories.php
@@ -23,7 +23,7 @@
  * large performance boost and helps keep code clean of lengthy
  * instantiation checks.
  *
- * @method static BaseConfig config(...$arguments)
+ * @method static BaseConfig|null config(...$arguments)
  */
 class Factories
 {
diff --git a/system/Database/Database.php b/system/Database/Database.php
@@ -35,7 +35,7 @@ class Database
      * Parses the connection binds and returns an instance of the driver
      * ready to go.
      *
-     * @return mixed
+     * @return BaseConnection
      *
      * @throws InvalidArgumentException
      */
diff --git a/system/Debug/Timer.php b/system/Debug/Timer.php
@@ -34,8 +34,8 @@ class Timer
      * Multiple calls can be made to this method so that several
      * execution points can be measured.
      *
-     * @param string $name The name of this timer.
-     * @param float  $time Allows user to provide time.
+     * @param string     $name The name of this timer.
+     * @param float|null $time Allows user to provide time.
      *
      * @return Timer
      */
diff --git a/system/Email/Email.php b/system/Email/Email.php
@@ -392,7 +392,7 @@ class Email
     protected static $func_overload;
 
     /**
-     * @param array|null $config
+     * @param array|\Config\Email|null $config
      */
     public function __construct($config = null)
     {
@@ -405,7 +405,7 @@ public function __construct($config = null)
     /**
      * Initialize preferences
      *
-     * @param array|\Config\Email $config
+     * @param array|\Config\Email|null $config
      *
      * @return Email
      */
diff --git a/system/HTTP/IncomingRequest.php b/system/HTTP/IncomingRequest.php
@@ -18,6 +18,7 @@
 use Config\Services;
 use InvalidArgumentException;
 use Locale;
+use stdClass;
 
 /**
  * Class IncomingRequest
@@ -478,7 +479,7 @@ public function getDefaultLocale(): string
      * @param int|null          $filter Filter constant
      * @param mixed             $flags
      *
-     * @return mixed
+     * @return array|bool|float|int|stdClass|string|null
      */
     public function getVar($index = null, $filter = null, $flags = null)
     {
@@ -516,7 +517,7 @@ public function getVar($index = null, $filter = null, $flags = null)
      *
      * @see http://php.net/manual/en/function.json-decode.php
      *
-     * @return mixed
+     * @return array|bool|float|int|stdClass|null
      */
     public function getJSON(bool $assoc = false, int $depth = 512, int $options = 0)
     {
@@ -531,7 +532,7 @@ public function getJSON(bool $assoc = false, int $depth = 512, int $options = 0)
      * @param int|null       $filter Filter Constant
      * @param array|int|null $flags  Option
      *
-     * @return mixed
+     * @return array|bool|float|int|stdClass|string|null
      */
     public function getJsonVar(string $index, bool $assoc = false, ?int $filter = null, $flags = null)
     {
@@ -565,7 +566,7 @@ public function getJsonVar(string $index, bool $assoc = false, ?int $filter = nu
      * A convenience method that grabs the raw input stream(send method in PUT, PATCH, DELETE) and decodes
      * the String into an array.
      *
-     * @return mixed
+     * @return array
      */
     public function getRawInput()
     {
diff --git a/system/HTTP/Request.php b/system/HTTP/Request.php
@@ -98,7 +98,7 @@ public function getMethod(bool $upper = false): string
     /**
      * Sets the request method. Used when spoofing the request.
      *
-     * @return Request
+     * @return $this
      *
      * @deprecated Use withMethod() instead for immutability
      *
diff --git a/system/HTTP/URI.php b/system/HTTP/URI.php
@@ -138,11 +138,11 @@ class URI
     /**
      * Builds a representation of the string from the component parts.
      *
-     * @param string $scheme
-     * @param string $authority
-     * @param string $path
-     * @param string $query
-     * @param string $fragment
+     * @param string|null $scheme    URI scheme. E.g., http, ftp
+     * @param string      $authority
+     * @param string      $path
+     * @param string      $query
+     * @param string      $fragment
      */
     public static function createURIString(?string $scheme = null, ?string $authority = null, ?string $path = null, ?string $query = null, ?string $fragment = null): string
     {
diff --git a/system/Helpers/url_helper.php b/system/Helpers/url_helper.php
@@ -75,6 +75,7 @@ function _get_uri(string $relativePath = '', ?App $config = null): URI
      * Returns a site URL as defined by the App config.
      *
      * @param array|string $relativePath URI string or array of URI segments
+     * @param string|null  $scheme       URI scheme. E.g., http, ftp
      * @param App|null     $config       Alternate configuration to use
      */
     function site_url($relativePath = '', ?string $scheme = null, ?App $config = null): string
@@ -96,6 +97,7 @@ function site_url($relativePath = '', ?string $scheme = null, ?App $config = nul
      * Base URLs are trimmed site URLs without the index page.
      *
      * @param array|string $relativePath URI string or array of URI segments
+     * @param string|null  $scheme       URI scheme. E.g., http, ftp
      */
     function base_url($relativePath = '', ?string $scheme = null): string
     {
diff --git a/system/Model.php b/system/Model.php
@@ -623,9 +623,9 @@ public function builder(?string $table = null)
      * data here. This allows it to be used with any of the other
      * builder methods and still get validated data, like replace.
      *
-     * @param mixed     $key    Field name, or an array of field/value pairs
-     * @param mixed     $value  Field value, if $key is a single field
-     * @param bool|null $escape Whether to escape values
+     * @param array|object|string               $key    Field name, or an array of field/value pairs
+     * @param bool|float|int|object|string|null $value  Field value, if $key is a single field
+     * @param bool|null                         $escape Whether to escape values
      *
      * @return $this
      */
diff --git a/tests/system/CommonSingleServiceTest.php b/tests/system/CommonSingleServiceTest.php
@@ -36,6 +36,8 @@ public function testSingleServiceWithNoParamsSupplied(string $service): void
         $service1 = single_service($service);
         $service2 = single_service($service);
 
+        assert($service1 !== null);
+
         $this->assertInstanceOf(get_class($service1), $service2);
         $this->assertNotSame($service1, $service2);
     }
@@ -64,6 +66,8 @@ public function testSingleServiceWithAtLeastOneParamSupplied(string $service): v
         $service1 = single_service($service, ...$params);
         $service2 = single_service($service, ...$params);
 
+        assert($service1 !== null);
+
         $this->assertInstanceOf(get_class($service1), $service2);
         $this->assertNotSame($service1, $service2);
 
@@ -77,6 +81,9 @@ public function testSingleServiceWithAllParamsSupplied(): void
         $cache1 = single_service('cache', null, true);
         $cache2 = single_service('cache', null, true);
 
+        assert($cache1 !== null);
+        assert($cache2 !== null);
+
         // Assert that even passing true as last param this will
         // not create a shared instance.
         $this->assertInstanceOf(get_class($cache1), $cache2);

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ trait ResponseTrait`
`66`	`66`	`/**`
`67`	`67`	`* How to format the response data.`
`68`	`68`	`* Either 'json' or 'xml'. If blank will be`
`69`		`- * determine through content negotiation.`
	`69`	`+ * determined through content negotiation.`
`70`	`70`	`*`
`71`	`71`	`* @var string`
`72`	`72`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -63,6 +63,7 @@ function app_timezone(): string`
`63`	`63`	`* $foo = cache('bar');`
`64`	`64`	`*`
`65`	`65`	`* @return CacheInterface\|mixed`
	`66`	`+ * @phpstan-return ($key is null ? CacheInterface : mixed)`
`66`	`67`	`*/`
`67`	`68`	`function cache(?string $key = null)`
`68`	`69`	`{`
`@@ -196,7 +197,7 @@ function command(string $command)`
`196`	`197`	`/**`
`197`	`198`	`* More simple way of getting config instances from Factories`
`198`	`199`	`*`
`199`		`- * @return mixed`
	`200`	`+ * @return object\|null`
`200`	`201`	`*/`
`201`	`202`	`function config(string $name, bool $getShared = true)`
`202`	`203`	`{`
`@@ -376,7 +377,7 @@ function dd(...$vars)`
`376`	`377`	`*`
`377`	`378`	`* @param string\|null $default`
`378`	`379`	`*`
`379`		`- * @return mixed`
	`380`	`+ * @return bool\|string\|null`
`380`	`381`	`*/`
`381`	`382`	`function env(string $key, $default = null)`
`382`	`383`	`{`
`@@ -952,7 +953,7 @@ function session(?string $val = null)`
`952`	`953`	`*`
`953`	`954`	`* @param mixed ...$params`
`954`	`955`	`*`
`955`		`- * @return mixed`
	`956`	`+ * @return object`
`956`	`957`	`*/`
`957`	`958`	`function service(string $name, ...$params)`
`958`	`959`	`{`
`@@ -966,7 +967,7 @@ function service(string $name, ...$params)`
`966`	`967`	`*`
`967`	`968`	`* @param mixed ...$params`
`968`	`969`	`*`
`969`		`- * @return mixed`
	`970`	`+ * @return object\|null`
`970`	`971`	`*/`
`971`	`972`	`function single_service(string $name, ...$params)`
`972`	`973`	`{`
`@@ -1076,7 +1077,7 @@ function stringify_attributes($attributes, bool $js = false): string`
`1076`	`1077`	`* If no parameter is passed, it will return the timer instance,`
`1077`	`1078`	`* otherwise will start or stop the timer intelligently.`
`1078`	`1079`	`*`
`1079`		`- * @return mixed\|Timer`
	`1080`	`+ * @return Timer`
`1080`	`1081`	`*/`
`1081`	`1082`	`function timer(?string $name = null)`
`1082`	`1083`	`{`
Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@`
`23`	`23`	`* large performance boost and helps keep code clean of lengthy`
`24`	`24`	`* instantiation checks.`
`25`	`25`	`*`
`26`		`- * @method static BaseConfig config(...$arguments)`
	`26`	`+ * @method static BaseConfig\|null config(...$arguments)`
`27`	`27`	`*/`
`28`	`28`	`class Factories`
`29`	`29`	`{`
Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@ class Database`
`35`	`35`	`* Parses the connection binds and returns an instance of the driver`
`36`	`36`	`* ready to go.`
`37`	`37`	`*`
`38`		`- * @return mixed`
	`38`	`+ * @return BaseConnection`
`39`	`39`	`*`
`40`	`40`	`* @throws InvalidArgumentException`
`41`	`41`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -34,8 +34,8 @@ class Timer`
`34`	`34`	`* Multiple calls can be made to this method so that several`
`35`	`35`	`* execution points can be measured.`
`36`	`36`	`*`
`37`		`- * @param string $name The name of this timer.`
`38`		`- * @param float $time Allows user to provide time.`
	`37`	`+ * @param string $name The name of this timer.`
	`38`	`+ * @param float\|null $time Allows user to provide time.`
`39`	`39`	`*`
`40`	`40`	`* @return Timer`
`41`	`41`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -392,7 +392,7 @@ class Email`
`392`	`392`	`protected static $func_overload;`
`393`	`393`
`394`	`394`	`/**`
`395`		`- * @param array\|null $config`
	`395`	`+ * @param array\|\Config\Email\|null $config`
`396`	`396`	`*/`
`397`	`397`	`public function __construct($config = null)`
`398`	`398`	`{`
`@@ -405,7 +405,7 @@ public function __construct($config = null)`
`405`	`405`	`/**`
`406`	`406`	`* Initialize preferences`
`407`	`407`	`*`
`408`		`- * @param array\|\Config\Email $config`
	`408`	`+ * @param array\|\Config\Email\|null $config`
`409`	`409`	`*`
`410`	`410`	`* @return Email`
`411`	`411`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`use Config\Services;`
`19`	`19`	`use InvalidArgumentException;`
`20`	`20`	`use Locale;`
	`21`	`+use stdClass;`
`21`	`22`
`22`	`23`	`/**`
`23`	`24`	`* Class IncomingRequest`
`@@ -478,7 +479,7 @@ public function getDefaultLocale(): string`
`478`	`479`	`* @param int\|null $filter Filter constant`
`479`	`480`	`* @param mixed $flags`
`480`	`481`	`*`
`481`		`- * @return mixed`
	`482`	`+ * @return array\|bool\|float\|int\|stdClass\|string\|null`
`482`	`483`	`*/`
`483`	`484`	`public function getVar($index = null, $filter = null, $flags = null)`
`484`	`485`	`{`
`@@ -516,7 +517,7 @@ public function getVar($index = null, $filter = null, $flags = null)`
`516`	`517`	`*`
`517`	`518`	`* @see http://php.net/manual/en/function.json-decode.php`
`518`	`519`	`*`
`519`		`- * @return mixed`
	`520`	`+ * @return array\|bool\|float\|int\|stdClass\|null`
`520`	`521`	`*/`
`521`	`522`	`public function getJSON(bool $assoc = false, int $depth = 512, int $options = 0)`
`522`	`523`	`{`
`@@ -531,7 +532,7 @@ public function getJSON(bool $assoc = false, int $depth = 512, int $options = 0)`
`531`	`532`	`* @param int\|null $filter Filter Constant`
`532`	`533`	`* @param array\|int\|null $flags Option`
`533`	`534`	`*`
`534`		`- * @return mixed`
	`535`	`+ * @return array\|bool\|float\|int\|stdClass\|string\|null`
`535`	`536`	`*/`
`536`	`537`	`public function getJsonVar(string $index, bool $assoc = false, ?int $filter = null, $flags = null)`
`537`	`538`	`{`
`@@ -565,7 +566,7 @@ public function getJsonVar(string $index, bool $assoc = false, ?int $filter = nu`
`565`	`566`	`* A convenience method that grabs the raw input stream(send method in PUT, PATCH, DELETE) and decodes`
`566`	`567`	`* the String into an array.`
`567`	`568`	`*`
`568`		`- * @return mixed`
	`569`	`+ * @return array`
`569`	`570`	`*/`
`570`	`571`	`public function getRawInput()`
`571`	`572`	`{`
Original file line number	Diff line number	Diff line change
`@@ -98,7 +98,7 @@ public function getMethod(bool $upper = false): string`
`98`	`98`	`/**`
`99`	`99`	`* Sets the request method. Used when spoofing the request.`
`100`	`100`	`*`
`101`		`- * @return Request`
	`101`	`+ * @return $this`
`102`	`102`	`*`
`103`	`103`	`* @deprecated Use withMethod() instead for immutability`
`104`	`104`	`*`
Original file line number	Diff line number	Diff line change
`@@ -75,6 +75,7 @@ function _get_uri(string $relativePath = '', ?App $config = null): URI`
`75`	`75`	`* Returns a site URL as defined by the App config.`
`76`	`76`	`*`
`77`	`77`	`* @param array\|string $relativePath URI string or array of URI segments`
	`78`	`+ * @param string\|null $scheme URI scheme. E.g., http, ftp`
`78`	`79`	`* @param App\|null $config Alternate configuration to use`
`79`	`80`	`*/`
`80`	`81`	`function site_url($relativePath = '', ?string $scheme = null, ?App $config = null): string`
`@@ -96,6 +97,7 @@ function site_url($relativePath = '', ?string $scheme = null, ?App $config = nul`
`96`	`97`	`* Base URLs are trimmed site URLs without the index page.`
`97`	`98`	`*`
`98`	`99`	`* @param array\|string $relativePath URI string or array of URI segments`
	`100`	`+ * @param string\|null $scheme URI scheme. E.g., http, ftp`
`99`	`101`	`*/`
`100`	`102`	`function base_url($relativePath = '', ?string $scheme = null): string`
`101`	`103`	`{`