Merge pull request #235 from SpencerMalone/context-docblocking

Add docblocks for \Twirp\Context array throughout codebase

Author: sagikazarmark

.php-cs-fixer.dist.php

@@ -14,6 +14,9 @@
         // until PHP 8.0
         'trailing_comma_in_multiline' => false,
         'native_function_invocation' => false,
+        'phpdoc_to_comment' => [
+            'allow_before_return_statement' => true,
+        ]
     ])
     ->setFinder(
         PhpCsFixer\Finder::create()

lib/src/Context.php

@@ -19,10 +19,12 @@ final class Context
     /**
      * Extracts the name of the method being handled in the given
      * context. If it is not known, it returns null.
+     *
+     * @param array<string, mixed> $ctx
      */
     public static function methodName(array $ctx): ?string
     {
-        if (isset($ctx[self::METHOD_NAME])) {
+        if (isset($ctx[self::METHOD_NAME]) && is_string($ctx[self::METHOD_NAME])) {
             return $ctx[self::METHOD_NAME];
         }
 
@@ -31,6 +33,10 @@ public static function methodName(array $ctx): ?string
 
     /**
      * Sets the method name in the context.
+     *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
      */
     public static function withMethodName(array $ctx, string $name): array
     {
@@ -42,10 +48,12 @@ public static function withMethodName(array $ctx, string $name): array
     /**
      * Extracts the name of the service handling the given context. If
      * it is not known, it returns null.
+     *
+     * @param array<string, mixed> $ctx
      */
     public static function serviceName(array $ctx): ?string
     {
-        if (isset($ctx[self::SERVICE_NAME])) {
+        if (isset($ctx[self::SERVICE_NAME]) && is_string($ctx[self::SERVICE_NAME])) {
             return $ctx[self::SERVICE_NAME];
         }
 
@@ -54,6 +62,10 @@ public static function serviceName(array $ctx): ?string
 
     /**
      * Sets the service name in the context.
+     *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
      */
     public static function withServiceName(array $ctx, string $name): array
     {
@@ -70,10 +82,12 @@ public static function withServiceName(array $ctx, string $name): array
      *
      * Note that the protobuf package name can be very different than the go package
      * name; the two are unrelated.
+     *
+     * @param array<string, mixed> $ctx
      */
     public static function packageName(array $ctx): ?string
     {
-        if (isset($ctx[self::PACKAGE_NAME])) {
+        if (isset($ctx[self::PACKAGE_NAME]) && is_string($ctx[self::PACKAGE_NAME])) {
             return $ctx[self::PACKAGE_NAME];
         }
 
@@ -82,6 +96,10 @@ public static function packageName(array $ctx): ?string
 
     /**
      * Sets the package name in the context.
+     *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
      */
     public static function withPackageName(array $ctx, string $name): array
     {
@@ -94,10 +112,12 @@ public static function withPackageName(array $ctx, string $name): array
      * Retrieves the status code of the response (as string like "200").
      * If it is known returns the status.
      * If it is not known, it returns null.
+     *
+     * @param array<string, mixed> $ctx
      */
     public static function statusCode(array $ctx): ?int
     {
-        if (isset($ctx[self::STATUS_CODE])) {
+        if (isset($ctx[self::STATUS_CODE]) && is_int($ctx[self::STATUS_CODE])) {
             return $ctx[self::STATUS_CODE];
         }
 
@@ -106,6 +126,10 @@ public static function statusCode(array $ctx): ?int
 
     /**
      * Sets the status code in the context.
+     *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
      */
     public static function withStatusCode(array $ctx, int $code): array
     {
@@ -117,10 +141,15 @@ public static function withStatusCode(array $ctx, int $code): array
     /**
      * Retrieves the HTTP headers sent as part of the request.
      * If there are no headers, it returns an empty array.
+     *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, string>
      */
     public static function httpRequestHeaders(array $ctx): array
     {
         if (isset($ctx[self::REQUEST_HEADER])) {
+            /** @var array{self::REQUEST_HEADER:array<string, string>} $ctx */
             return $ctx[self::REQUEST_HEADER];
         }
 
@@ -140,6 +169,11 @@ public static function httpRequestHeaders(array $ctx): array
      * Throws an exception if the provided headers
      * would overwrite a header that is needed by Twirp, like "Content-Type".
      *
+     * @param array<string, mixed>  $ctx
+     * @param array<string, string> $headers
+     *
+     * @return array<string, mixed>
+     *
      * @throws \InvalidArgumentException when any of the following headers are included: Accept, Content-Type, Twirp-Version
      */
     public static function withHttpRequestHeaders(array $ctx, array $headers): array
@@ -178,6 +212,10 @@ public static function withHttpRequestHeaders(array $ctx, array $headers): array
      * Throws an exception if the provided headers
      * would overwrite a header that is needed by Twirp, like "Content-Type".
      *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
+     *
      * @throws \InvalidArgumentException when any of the following headers are included: Content-Type
      */
     public static function withHttpResponseHeader(array $ctx, string $key, string $value): array
@@ -186,6 +224,10 @@ public static function withHttpResponseHeader(array $ctx, string $key, string $v
             throw new \InvalidArgumentException('header key can not be Content-Type');
         }
 
+        if (!isset($ctx[self::RESPONSE_HEADER]) || !is_array($ctx[self::RESPONSE_HEADER])) {
+            $ctx[self::RESPONSE_HEADER] = [];
+        }
+
         $ctx[self::RESPONSE_HEADER][$key] = $value;
 
         return $ctx;

lib/src/ServerHooks.php

@@ -28,6 +28,10 @@ interface ServerHooks
      * Called as soon as a request enters the Twirp
      * server at the earliest available moment.
      *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
+     *
      * @throws \Throwable
      */
     public function requestReceived(array $ctx): array;
@@ -36,6 +40,10 @@ public function requestReceived(array $ctx): array;
      * Called when a request has been routed to a
      * particular method of the Twirp server.
      *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
+     *
      * @throws \Throwable
      */
     public function requestRouted(array $ctx): array;
@@ -44,6 +52,10 @@ public function requestRouted(array $ctx): array;
      * Called when a request has been handled and a
      * response is ready to be sent to the client.
      *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
+     *
      * @throws \Throwable
      */
     public function responsePrepared(array $ctx): array;
@@ -54,12 +66,18 @@ public function responsePrepared(array $ctx): array;
      * does not return a context.
      *
      * For the same reason, it MUST NOT throw any exceptions.
+     *
+     * @param array<string, mixed> $ctx
      */
     public function responseSent(array $ctx): void;
 
     /**
      * Called when an error occurs while handling a request. The
      * Error is passed as argument to the hook.
+     *
+     * @param array<string, mixed> $ctx
+     *
+     * @return array<string, mixed>
      */
     public function error(array $ctx, \Throwable $error): array;
 }