types cleanup

 - per-component phpstan
 - upgrade spanner to phpstan level 3
 - improved typing
 - address review comments

Author: bshaffer

.github/workflows/emulator-system-tests-spanner.yaml

@@ -49,7 +49,7 @@ jobs:
       - name: Install dependencies
         run: |
           # ensure composer uses local Core instead of pulling from packagist
-          # composer config repositories.local  --json '{"type":"path", "url": "../Core", "options": {"versions": {"google/cloud-core": "1.100"}}}' -d Spanner
+          composer config repositories.local  --json '{"type":"path", "url": "../Core", "options": {"versions": {"google/cloud-core": "1.100"}},"canonical":false}' -d Spanner
           composer update --prefer-dist --no-interaction --no-suggest -d Spanner/
 
       - name: Run system tests

Core/src/LongRunning/LongRunningOperation.php

@@ -19,6 +19,7 @@
 
 /**
  * Represent and interact with a Long Running Operation.
+ * @template T
  */
 class LongRunningOperation
 {
@@ -180,7 +181,7 @@ public function state(array $options = [])
      * ```
      *
      * @param array $options [optional] Configuration options.
-     * @return mixed|null
+     * @return T|mixed|null
      */
     public function result(array $options = [])
     {

Core/src/RequestHandler.php

@@ -46,12 +46,12 @@ class RequestHandler
 
     /**
      * @param Serializer $serializer
-     * @param array<string|object> $clientClasses
+     * @param array<string|object> $clients
      * @param array $clientConfig
      */
     public function __construct(
         Serializer $serializer,
-        array $clientClasses,
+        array $clients,
         array $clientConfig = []
     ) {
         //@codeCoverageIgnoreStart
@@ -75,7 +75,7 @@ public function __construct(
         //@codeCoverageIgnoreEnd
 
         // Initialize the client classes and store them in memory
-        foreach ($clientClasses as $client) {
+        foreach ($clients as $client) {
             if (is_object($client)) {
                 $this->clients[get_class($client)] = $client;
             } else {

Core/src/Timestamp.php

@@ -17,6 +17,8 @@
 
 namespace Google\Cloud\Core;
 
+use DateTimeInterface;
+
 /**
  * Represents a Timestamp value.
  *
@@ -85,9 +87,9 @@ public function __construct(\DateTimeInterface $value, $nanoSeconds = null)
      * $dateTime = $timestamp->get();
      * ```
      *
-     * @return \DateTimeInterface
+     * @return DateTimeInterface
      */
-    public function get()
+    public function get(): DateTimeInterface
     {
         return $this->value;
     }
@@ -102,7 +104,7 @@ public function get()
      *
      * @return int
      */
-    public function nanoSeconds()
+    public function nanoSeconds(): int
     {
         return $this->nanoSeconds === null
             ? (int) $this->value->format('u') * 1000
@@ -119,7 +121,7 @@ public function nanoSeconds()
      *
      * @return string
      */
-    public function formatAsString()
+    public function formatAsString(): string
     {
         return $this->formatTimeAsString(
             $this->value,
@@ -143,7 +145,7 @@ public function __toString()
      *
      * @return array
      */
-    public function formatForApi()
+    public function formatForApi(): array
     {
         return $this->formatTimeAsArray($this->value, $this->nanoSeconds());
     }
@@ -155,7 +157,7 @@ public function formatForApi()
      * @access private
      */
     #[\ReturnTypeWillChange]
-    public function jsonSerialize()
+    public function jsonSerialize(): string
     {
         return $this->formatAsString();
     }

Core/tests/Unit/ServiceBuilderTest.php

@@ -24,7 +24,6 @@
 use Google\Cloud\Firestore\FirestoreClient;
 use Google\Cloud\Language\LanguageClient;
 use Google\Cloud\Logging\LoggingClient;
-use Google\Cloud\Speech\SpeechClient;
 use Google\Cloud\Storage\StorageClient;
 use Google\Cloud\Core\Tests\Unit\Fixtures;
 use GuzzleHttp\Psr7\Response;
@@ -161,10 +160,6 @@ public function serviceProvider()
             ], [
                 'language',
                 LanguageClient::class
-            ], [
-                'speech',
-                SpeechClient::class,
-                ['languageCode' => 'en-US']
             ], [
                 'storage',
                 StorageClient::class

Spanner/phpstan.neon.dist

@@ -0,0 +1,13 @@
+parameters:
+    level: 3
+    treatPhpDocTypesAsCertain: false
+    excludePaths:
+    # Ignore classes not compatible with Monolog2
+    - src/V1/*
+    - src/*/*/V1/*
+    ignoreErrors:
+    -
+        identifier: new.static                 # Ignore this error because changing it would be a breaking change.
+includes:
+    - ../dev/vendor/phpstan/phpstan/conf/bleedingEdge.neon
+

Spanner/src/ArrayType.php

@@ -61,18 +61,11 @@
  */
 class ArrayType
 {
-    /**
-     * @var int|null
-     */
-    private $type;
-
-    /**
-     * @var StructType|null
-     */
-    private $structType;
+    private int|string|null $type;
+    private StructType|null $structType;
 
     /**
-     * @param int|string|null|StructType $type A value type code or nested struct
+     * @param int|string|StructType|null $type A value type code or nested struct
      *        definition. Accepted integer and string values are defined as constants on
      *        {@see \Google\Cloud\Spanner\Database}, and are as follows:
      *        `Database::TYPE_BOOL`, `Database::TYPE_INT64`,
@@ -87,7 +80,7 @@ class ArrayType
      *        a struct is defined but the given type is not
      *        `Database::TYPE_STRUCT`.
      */
-    public function __construct($type)
+    public function __construct(int|string|StructType|null $type)
     {
         if ($type === Database::TYPE_STRUCT) {
             throw new \InvalidArgumentException(

Spanner/src/Backup.php

@@ -58,7 +58,8 @@ class Backup
      *
      * @internal Backup is constructed by the {@see Instance} class.
      *
-     * @param DatabaseAdminClient The database admin client to make backup RPC calls.
+     * @param DatabaseAdminClient $databaseAdminClient The database admin client to make backup RPC
+     *        calls.
      * @param Serializer $serializer The serializer instance to encode/decode messages.
      * @param Instance $instance The instance in which the backup exists.
      * @param string $projectId The project ID.
@@ -100,7 +101,7 @@ public function __construct(
      * @throws \InvalidArgumentException
      */
     public function create(
-        $database,
+        string $database,
         DateTimeInterface $expireTime,
         array $options = []
     ): LongRunningOperation {
@@ -362,7 +363,7 @@ public function updateExpireTime(DateTimeInterface $newTimestamp, array $options
      * @param string $operationName The Long Running Operation name.
      * @return LongRunningOperation
      */
-    public function resumeOperation($operationName, array $options = []): LongRunningOperation
+    public function resumeOperation(string $operationName, array $options = []): LongRunningOperation
     {
         return new LongRunningOperation(
             new LongRunningClientConnection($this->databaseAdminClient, $this->serializer),
@@ -423,7 +424,7 @@ function (OperationProto $operation) {
      *
      * @return string
      */
-    private function fullyQualifiedBackupName($name): string
+    private function fullyQualifiedBackupName(string $name): string
     {
         $instance = DatabaseAdminClient::parseName($this->instance->name())['instance'];
 

Spanner/src/Batch/BatchClient.php

@@ -108,30 +108,15 @@ class BatchClient
     use TransactionConfigurationTrait;
 
     const PARTITION_TYPE_KEY = '__partitionTypeName';
-
-    /**
-     * @var Operation
-     */
-    private $operation;
-
-    /**
-     * @var string
-     */
-    private $databaseName;
-
-    /**
-     * @var string|null
-     */
-    private $databaseRole;
-
-    /**
-     * @var array
-     */
-    private $allowedPartitionTypes = [
+    private const ALLOWED_PARTITION_TYPES = [
         QueryPartition::class,
         ReadPartition::class
     ];
 
+    private Operation $operation;
+    private string $databaseName;
+    private string|null $databaseRole;
+
     /**
      * @param Operation $operation A Cloud Spanner Operations wrapper.
      * @param string $databaseName The database name to which the batch client
@@ -198,6 +183,7 @@ public function snapshot(array $options = [])
             $sessionOptions
         );
 
+        /** @var BatchSnapshot */
         return $this->operation->snapshot($session, [
             'className' => BatchSnapshot::class,
             'transactionOptions' => $transactionOptions
@@ -233,7 +219,7 @@ public function snapshotFromString($identifier)
 
         $session = $this->operation->session($data['sessionName']);
 
-        $readTime = $this->parseTimeString($data['readTimestamp']);
+        /** @var BatchSnapshot */
         return $this->operation->createSnapshot($session, [
             'id' => $data['transactionId'],
             'readTimestamp' => $data['readTimestamp']
@@ -262,7 +248,7 @@ public function partitionFromString($partition)
         }
 
         $class = $data[self::PARTITION_TYPE_KEY];
-        if (!in_array($class, $this->allowedPartitionTypes)) {
+        if (!in_array($class, self::ALLOWED_PARTITION_TYPES)) {
             throw new \InvalidArgumentException('Invalid partition type.');
         }
 

Spanner/src/Batch/BatchSnapshot.php

@@ -92,7 +92,7 @@ public function __construct(Operation $operation, Session $session, array $optio
      * @param array $options [optional] Configuration Options
      * @return void
      */
-    public function close(array $options = [])
+    public function close(array $options = []): void
     {
         $this->session->delete($options);
     }
@@ -131,7 +131,7 @@ public function close(array $options = [])
      * }
      * @return ReadPartition[]
      */
-    public function partitionRead($table, KeySet $keySet, array $columns, array $options = [])
+    public function partitionRead($table, KeySet $keySet, array $columns, array $options = []): array
     {
         return $this->operation->partitionRead(
             $this->session,
@@ -194,7 +194,7 @@ public function partitionRead($table, KeySet $keySet, array $columns, array $opt
      * }
      * @return QueryPartition[]
      */
-    public function partitionQuery($sql, array $options = [])
+    public function partitionQuery($sql, array $options = []): array
     {
         return $this->operation->partitionQuery(
             $this->session,
@@ -218,11 +218,10 @@ public function partitionQuery($sql, array $options = [])
      * ```
      *
      * @param PartitionInterface $partition The partition to read.
-     * @param array $options Configuration Options.
      * @return Result
      * @throws \BadMethodCallException If an invalid partition type is given.
      */
-    public function executePartition(PartitionInterface $partition, array $options = [])
+    public function executePartition(PartitionInterface $partition): Result
     {
         if ($partition instanceof QueryPartition) {
             return $this->executeQuery($partition);
@@ -243,7 +242,7 @@ public function executePartition(PartitionInterface $partition, array $options =
      *
      * @return string
      */
-    public function serialize()
+    public function serialize(): string
     {
         return base64_encode(json_encode([
             'sessionName' => $this->session->name(),
@@ -269,7 +268,7 @@ public function __toString()
      * @param QueryPartition $partition The partition.
      * @return Result
      */
-    private function executeQuery(QueryPartition $partition)
+    private function executeQuery(QueryPartition $partition): Result
     {
         return $this->execute($partition->sql(), [
             'partitionToken' => $partition->token()
@@ -282,7 +281,7 @@ private function executeQuery(QueryPartition $partition)
      * @param ReadPartition $partition The partition.
      * @return Result
      */
-    private function executeRead(ReadPartition $partition)
+    private function executeRead(ReadPartition $partition): Result
     {
         return $this->read($partition->table(), $partition->keySet(), $partition->columns(), [
             'partitionToken' => $partition->token()