Refined types as per laminas/laminas-coding-standard:2.3.x upgrades

In #104 (duplicate), we improved the types of internal and
public API. These were mixed with coding style improvements.

The coding style improvements have been merged separately via #103,
so this patch only includes the type/docblock improvements, which should ease the potential evolution of the
API of this package.

composer.json

@@ -19,6 +19,9 @@
         "forum": "https://discourse.laminas.dev"
     },
     "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        },
         "sort-packages": true,
         "platform": {
             "php": "7.3.99"

psalm-baseline.xml

@@ -329,18 +329,9 @@
     </RedundantConditionGivenDocblockType>
   </file>
   <file src="src/functions/create_uploaded_file.legacy.php">
-    <InvalidReturnStatement occurrences="1">
-      <code>laminas_createUploadedFile(...func_get_args())</code>
-    </InvalidReturnStatement>
-    <InvalidReturnType occurrences="1">
-      <code>UploadedFile</code>
-    </InvalidReturnType>
     <MixedArgument occurrences="1">
       <code>func_get_args()</code>
     </MixedArgument>
-    <UndefinedClass occurrences="1">
-      <code>UploadedFile</code>
-    </UndefinedClass>
   </file>
   <file src="src/functions/create_uploaded_file.php">
     <MixedArgument occurrences="4">
@@ -386,18 +377,9 @@
     </MixedArgument>
   </file>
   <file src="src/functions/marshal_uri_from_sapi.legacy.php">
-    <InvalidReturnStatement occurrences="1">
-      <code>laminas_marshalUriFromSapi(...func_get_args())</code>
-    </InvalidReturnStatement>
-    <InvalidReturnType occurrences="1">
-      <code>Uri</code>
-    </InvalidReturnType>
     <MixedArgument occurrences="1">
       <code>func_get_args()</code>
     </MixedArgument>
-    <UndefinedClass occurrences="1">
-      <code>Uri</code>
-    </UndefinedClass>
   </file>
   <file src="src/functions/marshal_uri_from_sapi.php">
     <MissingClosureParamType occurrences="3">
@@ -529,19 +511,20 @@
     </MixedOperand>
   </file>
   <file src="test/RequestTest.php">
-    <DuplicateArrayKey occurrences="1">
-      <code>'UNLOCK'    =&gt; ['UNLOCK']</code>
-    </DuplicateArrayKey>
-  </file>
-  <file src="test/Response/XmlResponseTest.php">
-    <MissingReturnType occurrences="1">
-      <code>testRaisesExceptionforNonStringNonStreamBodyContent</code>
-    </MissingReturnType>
+    <MixedArgument occurrences="1">
+      <code>$headers</code>
+    </MixedArgument>
   </file>
   <file src="test/ResponseTest.php">
+    <LessSpecificReturnStatement occurrences="1">
+      <code>$ianaCodesReasonPhrases</code>
+    </LessSpecificReturnStatement>
     <MixedAssignment occurrences="1">
       <code>$responseCode</code>
     </MixedAssignment>
+    <MoreSpecificReturnType occurrences="1">
+      <code>list&lt;array{numeric-string, non-empty-string}&gt;</code>
+    </MoreSpecificReturnType>
     <RedundantConditionGivenDocblockType occurrences="1">
       <code>assertIsInt</code>
     </RedundantConditionGivenDocblockType>

src/Exception/InvalidStreamPointerPositionException.php

@@ -9,10 +9,10 @@
 
 class InvalidStreamPointerPositionException extends RuntimeException implements ExceptionInterface
 {
-    /** @param int $code */
+    /** {@inheritDoc} */
     public function __construct(
         string $message = 'Invalid pointer position',
-        $code = 0,
+        int $code = 0,
         ?Throwable $previous = null
     ) {
         parent::__construct($message, $code, $previous);

src/Exception/UploadedFileAlreadyMovedException.php

@@ -9,10 +9,10 @@
 
 class UploadedFileAlreadyMovedException extends RuntimeException implements ExceptionInterface
 {
-    /** @param int $code */
+    /** {@inheritDoc} */
     public function __construct(
         string $message = 'Cannot retrieve stream after it has already moved',
-        $code = 0,
+        int $code = 0,
         ?Throwable $previous = null
     ) {
         parent::__construct($message, $code, $previous);

src/MessageTrait.php

@@ -303,9 +303,7 @@ public function withBody(StreamInterface $body): MessageInterface
         return $new;
     }
 
-    /**
-     * @param StreamInterface|string|resource $stream
-     */
+    /** @param StreamInterface|string|resource $stream */
     private function getStream($stream, string $modeIfNotInstance): StreamInterface
     {
         if ($stream instanceof StreamInterface) {

src/Request/ArraySerializer.php

@@ -23,6 +23,15 @@ final class ArraySerializer
 {
     /**
      * Serialize a request message to an array.
+     *
+     * @return array{
+     *     method: string,
+     *     request_target: string,
+     *     uri: string,
+     *     protocol_version: string,
+     *     headers: array<array<string>>,
+     *     body: string
+     * }
      */
     public static function toArray(RequestInterface $request): array
     {

src/Response/ArraySerializer.php

@@ -23,6 +23,14 @@ final class ArraySerializer
 {
     /**
      * Serialize a response message to an array.
+     *
+     * @return array{
+     *     status_code: int,
+     *     reason_phrase: string,
+     *     protocol_version: string,
+     *     headers: array<array<string>>,
+     *     body: string
+     * }
      */
     public static function toArray(ResponseInterface $response): array
     {

src/functions/create_uploaded_file.legacy.php

@@ -4,6 +4,8 @@
 
 namespace Zend\Diactoros;
 
+use Laminas\Diactoros\UploadedFile;
+
 use function func_get_args;
 use function Laminas\Diactoros\createUploadedFile as laminas_createUploadedFile;
 

src/functions/marshal_uri_from_sapi.legacy.php

@@ -4,6 +4,8 @@
 
 namespace Zend\Diactoros;
 
+use Laminas\Diactoros\Uri;
+
 use function func_get_args;
 use function Laminas\Diactoros\marshalUriFromSapi as laminas_marshalUriFromSapi;
 

src/functions/parse_cookie_header.legacy.php

@@ -8,9 +8,10 @@
 use function Laminas\Diactoros\parseCookieHeader as laminas_parseCookieHeader;
 
 /**
- * @deprecated Use \Laminas\Diactoros\parseCookieHeader instead
+ * @deprecated Use {@see \Laminas\Diactoros\parseCookieHeader} instead
  *
  * @param string $cookieHeader A string cookie header value.
+ * @return array<string, string> key/value cookie pairs.
  */
 function parseCookieHeader($cookieHeader): array
 {

src/functions/parse_cookie_header.php

@@ -16,7 +16,7 @@
  * overwriting. Thus, the server request should take the cookies from the request header instead.
  *
  * @param string $cookieHeader A string cookie header value.
- * @return array key/value cookie pairs.
+ * @return array<string, string> key/value cookie pairs.
  */
 function parseCookieHeader($cookieHeader): array
 {

test/CallbackStreamTest.php

@@ -11,7 +11,7 @@
 /**
  * @covers \Laminas\Diactoros\CallbackStream
  */
-class CallbackStreamTest extends TestCase
+final class CallbackStreamTest extends TestCase
 {
     public function testToString(): void
     {
@@ -173,7 +173,7 @@ public function testGetMetadata(): void
         $this->assertNull($notExists);
     }
 
-    /** @return array<string, array{0: callable, 1: string}> */
+    /** @return non-empty-array<non-empty-string, array{callable(): string, non-empty-string}> */
     public function phpCallbacksForStreams(): array
     {
         $class = TestAsset\CallbacksForCallbackStreamTest::class;
@@ -190,6 +190,8 @@ public function phpCallbacksForStreams(): array
 
     /**
      * @dataProvider phpCallbacksForStreams
+     * @param callable(): string $callback
+     * @param non-empty-string $expected
      */
     public function testAllowsArbitraryPhpCallbacks(callable $callback, string $expected): void
     {

test/HeaderSecurityTest.php

@@ -8,12 +8,12 @@
 use Laminas\Diactoros\HeaderSecurity;
 use PHPUnit\Framework\TestCase;
 
-class HeaderSecurityTest extends TestCase
+final class HeaderSecurityTest extends TestCase
 {
     /**
      * Data for filter value
      *
-     * @return array<int, array{0: string, 1: string}>
+     * @return non-empty-list<array{non-empty-string, non-empty-string}>
      */
     public function getFilterValues(): array
     {
@@ -34,42 +34,47 @@ public function getFilterValues(): array
 
     /**
      * @dataProvider getFilterValues
+     * @group ZF2015-04
+     * @param non-empty-string $value
+     * @param non-empty-string $expected
      */
     public function testFiltersValuesPerRfc7230(string $value, string $expected): void
     {
         $this->assertSame($expected, HeaderSecurity::filter($value));
     }
 
-    /** @return array<int, array{0: string, 1: string}> */
+    /** @return non-empty-list<array{non-empty-string, bool}> */
     public function validateValues(): array
     {
         return [
-            ["This is a\n test", 'assertFalse'],
-            ["This is a\r test", 'assertFalse'],
-            ["This is a\n\r test", 'assertFalse'],
-            ["This is a\r\n  test", 'assertTrue'],
-            ["This is a \r\ntest", 'assertFalse'],
-            ["This is a \r\n\n test", 'assertFalse'],
-            ["This is a\n\n test", 'assertFalse'],
-            ["This is a\r\r test", 'assertFalse'],
-            ["This is a \r\r\n test", 'assertFalse'],
-            ["This is a \r\n\r\ntest", 'assertFalse'],
-            ["This is a \r\n\n\r\n test", 'assertFalse'],
-            ["This is a \xFF test", 'assertFalse'],
-            ["This is a \x7F test", 'assertFalse'],
-            ["This is a \x7E test", 'assertTrue'],
+            ["This is a\n test", false],
+            ["This is a\r test", false],
+            ["This is a\n\r test", false],
+            ["This is a\r\n  test", true],
+            ["This is a \r\ntest", false],
+            ["This is a \r\n\n test", false],
+            ["This is a\n\n test", false],
+            ["This is a\r\r test", false],
+            ["This is a \r\r\n test", false],
+            ["This is a \r\n\r\ntest", false],
+            ["This is a \r\n\n\r\n test", false],
+            ["This is a \xFF test", false],
+            ["This is a \x7F test", false],
+            ["This is a \x7E test", true],
         ];
     }
 
     /**
      * @dataProvider validateValues
+     * @group ZF2015-04
+     * @param non-empty-string $value
      */
-    public function testValidatesValuesPerRfc7230(string $value, string $assertion): void
+    public function testValidatesValuesPerRfc7230(string $value, bool $expected): void
     {
-        $this->{$assertion}(HeaderSecurity::isValid($value));
+        self::assertSame($expected, HeaderSecurity::isValid($value));
     }
 
-    /** @return array<int, array{0: string}> */
+    /** @return non-empty-list<array{non-empty-string}> */
     public function assertValues(): array
     {
         return [
@@ -88,6 +93,8 @@ public function assertValues(): array
 
     /**
      * @dataProvider assertValues
+     * @group ZF2015-04
+     * @param non-empty-string $value
      */
     public function testAssertValidRaisesExceptionForInvalidValue(string $value): void
     {

test/Integration/RequestTest.php

@@ -7,7 +7,7 @@
 use Http\Psr7Test\RequestIntegrationTest;
 use Laminas\Diactoros\Request;
 
-class RequestTest extends RequestIntegrationTest
+final class RequestTest extends RequestIntegrationTest
 {
     public function createSubject(): Request
     {

test/Integration/ResponseTest.php

@@ -7,7 +7,7 @@
 use Http\Psr7Test\ResponseIntegrationTest;
 use Laminas\Diactoros\Response;
 
-class ResponseTest extends ResponseIntegrationTest
+final class ResponseTest extends ResponseIntegrationTest
 {
     public function createSubject(): Response
     {

test/Integration/ServerRequestFactoryTest.php

@@ -8,7 +8,7 @@
 use Laminas\Diactoros\ServerRequestFactory;
 use Psr\Http\Message\ServerRequestInterface;
 
-class ServerRequestFactoryTest extends ServerRequestIntegrationTest
+final class ServerRequestFactoryTest extends ServerRequestIntegrationTest
 {
     public function createSubject(): ServerRequestInterface
     {

test/Integration/ServerRequestTest.php

@@ -7,7 +7,7 @@
 use Http\Psr7Test\ServerRequestIntegrationTest;
 use Laminas\Diactoros\ServerRequest;
 
-class ServerRequestTest extends ServerRequestIntegrationTest
+final class ServerRequestTest extends ServerRequestIntegrationTest
 {
     public function createSubject(): ServerRequest
     {

test/Integration/StreamTest.php

@@ -8,11 +8,9 @@
 use Laminas\Diactoros\Stream;
 use Psr\Http\Message\StreamInterface;
 
-class StreamTest extends StreamIntegrationTest
+final class StreamTest extends StreamIntegrationTest
 {
-    /**
-     * @param string|resource|StreamInterface $data
-     */
+    /** {@inheritDoc} */
     public function createStream($data): StreamInterface
     {
         if ($data instanceof StreamInterface) {

test/Integration/UploadedFileTest.php

@@ -10,7 +10,7 @@
 
 use const UPLOAD_ERR_OK;
 
-class UploadedFileTest extends UploadedFileIntegrationTest
+final class UploadedFileTest extends UploadedFileIntegrationTest
 {
     public function createSubject(): UploadedFile
     {

test/Integration/UriTest.php

@@ -7,11 +7,9 @@
 use Http\Psr7Test\UriIntegrationTest;
 use Laminas\Diactoros\Uri;
 
-class UriTest extends UriIntegrationTest
+final class UriTest extends UriIntegrationTest
 {
-    /**
-     * @param string $uri
-     */
+    /** {@inheritDoc} */
     public function createUri($uri): Uri
     {
         return new Uri($uri);

test/MessageTraitTest.php

@@ -422,6 +422,7 @@ public function invalidArrayHeaderValues(): array
 
     /**
      * @dataProvider invalidArrayHeaderValues
+     * @group 99
      * @param mixed $value
      */
     public function testWithHeaderShouldRaiseExceptionForInvalidHeaderValuesInArrays($value): void
@@ -435,6 +436,7 @@ public function testWithHeaderShouldRaiseExceptionForInvalidHeaderValuesInArrays
 
     /**
      * @dataProvider invalidHeaderValueTypes
+     * @group 99
      * @param mixed $value
      */
     public function testWithHeaderShouldRaiseExceptionForInvalidHeaderScalarValues($value): void

test/PhpInputStreamTest.php

@@ -10,7 +10,7 @@
 use function file_get_contents;
 use function substr;
 
-class PhpInputStreamTest extends TestCase
+final class PhpInputStreamTest extends TestCase
 {
     /** @var string */
     protected $file;