From 54bc57783b0a69b105610a0be05ea49f829ffde9 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Thu, 17 Apr 2025 10:38:49 +1200 Subject: [PATCH 1/2] Generic type hints --- src/Pools/Connection.php | 32 +++++++++++------- src/Pools/Group.php | 48 ++++++++++++++------------- src/Pools/Pool.php | 60 ++++++++++++++++++++-------------- tests/Pools/ConnectionTest.php | 3 ++ tests/Pools/PoolTest.php | 3 ++ 5 files changed, 87 insertions(+), 59 deletions(-) diff --git a/src/Pools/Connection.php b/src/Pools/Connection.php index eaeec6f..e770b91 100644 --- a/src/Pools/Connection.php +++ b/src/Pools/Connection.php @@ -4,14 +4,20 @@ use Exception; +/** + * @template TResource + */ class Connection { protected string $id = ''; + /** + * @var Pool|null + */ protected ?Pool $pool = null; /** - * @param mixed $resource + * @param TResource $resource */ public function __construct(protected mixed $resource) { @@ -27,7 +33,7 @@ public function getID(): string /** * @param string $id - * @return self + * @return $this */ public function setID(string $id): self { @@ -36,7 +42,7 @@ public function setID(string $id): self } /** - * @return mixed + * @return TResource */ public function getResource(): mixed { @@ -44,17 +50,17 @@ public function getResource(): mixed } /** - * @param mixed $resource - * @return self + * @param TResource $resource + * @return $this */ - public function setResource(mixed $resource): self + public function setResource(mixed $resource): static { $this->resource = $resource; return $this; } /** - * @return Pool + * @return Pool|null */ public function getPool(): ?Pool { @@ -62,17 +68,18 @@ public function getPool(): ?Pool } /** - * @param Pool $pool - * @return self + * @param Pool $pool + * @return $this */ - public function setPool(Pool &$pool): self + public function setPool(Pool $pool): static { $this->pool = $pool; return $this; } /** - * @return Pool + * @return Pool + * @throws Exception */ public function reclaim(): Pool { @@ -84,7 +91,8 @@ public function reclaim(): Pool } /** - * @return Pool + * @return Pool + * @throws Exception */ public function destroy(): Pool { diff --git a/src/Pools/Group.php b/src/Pools/Group.php index f7c72f7..c157a83 100644 --- a/src/Pools/Group.php +++ b/src/Pools/Group.php @@ -8,15 +8,15 @@ class Group { /** - * @var Pool[] + * @var array> */ protected array $pools = []; /** - * @param Pool $pool - * @return self + * @param Pool $pool + * @return static */ - public function add(Pool $pool): self + public function add(Pool $pool): static { $this->pools[$pool->getName()] = $pool; return $this; @@ -24,27 +24,28 @@ public function add(Pool $pool): self /** * @param string $name - * @return Pool + * @return Pool + * @throws Exception */ public function get(string $name): Pool { - return $this->pools[$name] ?? throw new Exception("Pool '{$name}' not found"); + return $this->pools[$name] ?? throw new Exception("Pool '$name' not found"); } /** * @param string $name - * @return self + * @return static */ - public function remove(string $name): self + public function remove(string $name): static { unset($this->pools[$name]); return $this; } /** - * @return self + * @return static */ - public function reclaim(): self + public function reclaim(): static { foreach ($this->pools as $pool) { $pool->reclaim(); @@ -56,9 +57,11 @@ public function reclaim(): self /** * Execute a callback with a managed connection * - * @param string[] $names Name of resources - * @param callable(mixed...): mixed $callback Function that receives the connection resources - * @return mixed Return value from the callback + * @template TReturn + * @param array $names Name of resources + * @param callable(mixed...): TReturn $callback Function that receives the connection resources + * @return TReturn Return value from the callback + * @throws Exception */ public function use(array $names, callable $callback): mixed { @@ -71,10 +74,11 @@ public function use(array $names, callable $callback): mixed /** * Internal recursive callback for `use`. * - * @param string[] $names Name of resources - * @param callable(mixed...): mixed $callback Function that receives the connection resources - * @param mixed[] $resources - * @return mixed + * @template TReturn + * @param array $names Name of resources + * @param callable(mixed...): TReturn $callback Function that receives the connection resources + * @param array $resources + * @return TReturn * @throws Exception */ private function useInternal(array $names, callable $callback, array $resources = []): mixed @@ -90,9 +94,9 @@ private function useInternal(array $names, callable $callback, array $resources /** * @param int $reconnectAttempts - * @return self + * @return static */ - public function setReconnectAttempts(int $reconnectAttempts): self + public function setReconnectAttempts(int $reconnectAttempts): static { foreach ($this->pools as $pool) { $pool->setReconnectAttempts($reconnectAttempts); @@ -103,9 +107,9 @@ public function setReconnectAttempts(int $reconnectAttempts): self /** * @param int $reconnectSleep - * @return self + * @return static */ - public function setReconnectSleep(int $reconnectSleep): self + public function setReconnectSleep(int $reconnectSleep): static { foreach ($this->pools as $pool) { $pool->setReconnectSleep($reconnectSleep); @@ -114,7 +118,7 @@ public function setReconnectSleep(int $reconnectSleep): self return $this; } - public function setTelemetry(Telemetry $telemetry): self + public function setTelemetry(Telemetry $telemetry): static { foreach ($this->pools as $pool) { $pool->setTelemetry($telemetry); diff --git a/src/Pools/Pool.php b/src/Pools/Pool.php index a04f990..57e4f04 100644 --- a/src/Pools/Pool.php +++ b/src/Pools/Pool.php @@ -8,6 +8,9 @@ use Utopia\Telemetry\Gauge; use Utopia\Telemetry\Histogram; +/** + * @template TResource + */ class Pool { /** @@ -46,12 +49,12 @@ class Pool protected int $retrySleep = 1; // seconds /** - * @var array + * @var array|true> */ protected array $pool = []; /** - * @var array + * @var array> */ protected array $active = []; @@ -67,7 +70,7 @@ class Pool /** * @param string $name * @param int $size - * @param callable $init + * @param callable(): TResource $init */ public function __construct(string $name, int $size, callable $init) { @@ -104,9 +107,9 @@ public function getReconnectAttempts(): int /** * @param int $reconnectAttempts - * @return self + * @return $this */ - public function setReconnectAttempts(int $reconnectAttempts): self + public function setReconnectAttempts(int $reconnectAttempts): static { $this->reconnectAttempts = $reconnectAttempts; return $this; @@ -122,9 +125,9 @@ public function getReconnectSleep(): int /** * @param int $reconnectSleep - * @return self + * @return $this */ - public function setReconnectSleep(int $reconnectSleep): self + public function setReconnectSleep(int $reconnectSleep): static { $this->reconnectSleep = $reconnectSleep; return $this; @@ -140,9 +143,9 @@ public function getRetryAttempts(): int /** * @param int $retryAttempts - * @return self + * @return $this */ - public function setRetryAttempts(int $retryAttempts): self + public function setRetryAttempts(int $retryAttempts): static { $this->retryAttempts = $retryAttempts; return $this; @@ -158,15 +161,19 @@ public function getRetrySleep(): int /** * @param int $retrySleep - * @return self + * @return $this */ - public function setRetrySleep(int $retrySleep): self + public function setRetrySleep(int $retrySleep): static { $this->retrySleep = $retrySleep; return $this; } - public function setTelemetry(Telemetry $telemetry): void + /** + * @param Telemetry $telemetry + * @return $this + */ + public function setTelemetry(Telemetry $telemetry): static { $this->telemetryOpenConnections = $telemetry->createGauge('pool.connection.open.count'); $this->telemetryActiveConnections = $telemetry->createGauge('pool.connection.active.count'); @@ -183,13 +190,16 @@ public function setTelemetry(Telemetry $telemetry): void advisory: ['ExplicitBucketBoundaries' => [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10]], ); $this->telemetryAttributes = ['pool' => $this->name, 'size' => $this->size]; + + return $this; } /** * Execute a callback with a managed connection * - * @param callable(mixed): mixed $callback Function that receives the connection resource - * @return mixed Return value from the callback + * @template T + * @param callable(mixed): T $callback Function that receives the connection resource + * @return T Return value from the callback */ public function use(callable $callback): mixed { @@ -213,7 +223,8 @@ public function use(callable $callback): mixed * 3. If still no connection is available, throw an exception * 4. If a connection is available, return it * - * @return Connection + * @return Connection + * @throws Exception * @internal Please migrate to `use`. */ public function pop(): Connection @@ -275,10 +286,10 @@ public function pop(): Connection } /** - * @param Connection $connection - * @return self + * @param Connection $connection + * @return $this */ - public function push(Connection $connection): self + public function push(Connection $connection): static { try { $this->pool[] = $connection; @@ -299,10 +310,10 @@ public function count(): int } /** - * @param Connection|null $connection - * @return self + * @param Connection|null $connection + * @return $this */ - public function reclaim(Connection $connection = null): self + public function reclaim(Connection $connection = null): static { if ($connection !== null) { $this->push($connection); @@ -316,12 +327,11 @@ public function reclaim(Connection $connection = null): self return $this; } - /** - * @param Connection|null $connection - * @return self + * @param Connection|null $connection + * @return $this */ - public function destroy(Connection $connection = null): self + public function destroy(Connection $connection = null): static { try { if ($connection !== null) { diff --git a/tests/Pools/ConnectionTest.php b/tests/Pools/ConnectionTest.php index 40cd909..93bf1a0 100644 --- a/tests/Pools/ConnectionTest.php +++ b/tests/Pools/ConnectionTest.php @@ -9,6 +9,9 @@ class ConnectionTest extends TestCase { + /** + * @var Connection + */ protected Connection $object; public function setUp(): void diff --git a/tests/Pools/PoolTest.php b/tests/Pools/PoolTest.php index d840ea4..33e5f0f 100644 --- a/tests/Pools/PoolTest.php +++ b/tests/Pools/PoolTest.php @@ -10,6 +10,9 @@ class PoolTest extends TestCase { + /** + * @var Pool + */ protected Pool $object; public function setUp(): void From f720711329f7e657eb668da93adde8b938f1ab3d Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Thu, 17 Apr 2025 10:40:09 +1200 Subject: [PATCH 2/2] Static bind setID --- src/Pools/Connection.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Pools/Connection.php b/src/Pools/Connection.php index e770b91..3d2ba4d 100644 --- a/src/Pools/Connection.php +++ b/src/Pools/Connection.php @@ -35,7 +35,7 @@ public function getID(): string * @param string $id * @return $this */ - public function setID(string $id): self + public function setID(string $id): static { $this->id = $id; return $this;