Merge branch 'cleanup'

Author: lkrms

scripts/generate.php

@@ -8,7 +8,7 @@
 use Salient\Cli\CliOptionBuilder;
 use Salient\Console\ConsoleWriter;
 use Salient\Container\Container;
-use Salient\Contract\Cache\CacheStoreInterface;
+use Salient\Contract\Cache\CacheInterface;
 use Salient\Contract\Console\ConsoleWriterInterface;
 use Salient\Contract\Container\ContainerInterface;
 use Salient\Contract\Core\MessageLevel as Level;
@@ -71,7 +71,7 @@
 
 $facades = [
     App::class => [ContainerInterface::class, [Container::class], '--desc', 'A facade for the global service container', '--api'],
-    Cache::class => [CacheStoreInterface::class, [CacheStore::class], '--desc', 'A facade for the global cache store', '--api'],
+    Cache::class => [CacheInterface::class, [CacheStore::class], '--desc', 'A facade for the global cache store', '--api'],
     Config::class => [ConfigurationManager::class, '--api'],
     Console::class => [ConsoleWriterInterface::class, [ConsoleWriter::class], '--desc', 'A facade for the global console writer', '--api'],
     Err::class => [ErrorHandler::class, '--skip', 'handleShutdown,handleError,handleException'],

src/Toolkit/Cache/CacheStore.php

@@ -2,21 +2,23 @@
 
 namespace Salient\Cache;
 
-use Salient\Contract\Cache\CacheStoreInterface;
+use Salient\Contract\Cache\CacheInterface;
 use Salient\Core\AbstractStore;
 use DateInterval;
 use DateTimeImmutable;
 use DateTimeInterface;
 use LogicException;
 use SQLite3Result;
+use SQLite3Stmt;
 
 /**
  * A PSR-16 key-value store backed by a SQLite database
  *
  * @api
  */
-final class CacheStore extends AbstractStore implements CacheStoreInterface
+final class CacheStore extends AbstractStore implements CacheInterface
 {
+    private ?SQLite3Stmt $Stmt = null;
     private ?int $Now = null;
 
     /**
@@ -103,34 +105,36 @@ public function set($key, $value, $ttl = null): bool
     /**
      * @phpstan-impure
      */
-    public function has($key, ?int $maxAge = null): bool
+    public function has($key): bool
     {
         $sql = <<<SQL
 SELECT
   COUNT(*)
 FROM
   _cache_item
 SQL;
-        $result = $this->queryItems($sql, $key, $maxAge);
+        $result = $this->queryItems($sql, $key);
         /** @var array{int} */
         $row = $result->fetchArray(\SQLITE3_NUM);
+        $this->closeStmt();
 
         return (bool) $row[0];
     }
 
     /**
      * @phpstan-impure
      */
-    public function get($key, $default = null, ?int $maxAge = null)
+    public function get($key, $default = null)
     {
         $sql = <<<SQL
 SELECT
   item_value
 FROM
   _cache_item
 SQL;
-        $result = $this->queryItems($sql, $key, $maxAge);
+        $result = $this->queryItems($sql, $key);
         $row = $result->fetchArray(\SQLITE3_NUM);
+        $this->closeStmt();
 
         return $row === false
             ? $default
@@ -140,14 +144,10 @@ public function get($key, $default = null, ?int $maxAge = null)
     /**
      * @phpstan-impure
      */
-    public function getInstanceOf($key, string $class, ?object $default = null, ?int $maxAge = null): ?object
+    public function getInstanceOf($key, string $class, ?object $default = null): ?object
     {
-        $store = $this->maybeAsOfNow();
-        if (!$store->has($key, $maxAge)) {
-            return $default;
-        }
-        $item = $store->get($key, $default, $maxAge);
-        if (!is_object($item) || !is_a($item, $class)) {
+        $item = $this->get($key);
+        if ($item === null || !is_object($item) || !is_a($item, $class)) {
             return $default;
         }
         return $item;
@@ -156,14 +156,10 @@ public function getInstanceOf($key, string $class, ?object $default = null, ?int
     /**
      * @phpstan-impure
      */
-    public function getArray($key, ?array $default = null, ?int $maxAge = null): ?array
+    public function getArray($key, ?array $default = null): ?array
     {
-        $store = $this->maybeAsOfNow();
-        if (!$store->has($key, $maxAge)) {
-            return $default;
-        }
-        $item = $store->get($key, $default, $maxAge);
-        if (!is_array($item)) {
+        $item = $this->get($key);
+        if ($item === null || !is_array($item)) {
             return $default;
         }
         return $item;
@@ -172,14 +168,10 @@ public function getArray($key, ?array $default = null, ?int $maxAge = null): ?ar
     /**
      * @phpstan-impure
      */
-    public function getInt($key, ?int $default = null, ?int $maxAge = null): ?int
+    public function getInt($key, ?int $default = null): ?int
     {
-        $store = $this->maybeAsOfNow();
-        if (!$store->has($key, $maxAge)) {
-            return $default;
-        }
-        $item = $store->get($key, $default, $maxAge);
-        if (!is_int($item)) {
+        $item = $this->get($key);
+        if ($item === null || !is_int($item)) {
             return $default;
         }
         return $item;
@@ -188,14 +180,10 @@ public function getInt($key, ?int $default = null, ?int $maxAge = null): ?int
     /**
      * @phpstan-impure
      */
-    public function getString($key, ?string $default = null, ?int $maxAge = null): ?string
+    public function getString($key, ?string $default = null): ?string
     {
-        $store = $this->maybeAsOfNow();
-        if (!$store->has($key, $maxAge)) {
-            return $default;
-        }
-        $item = $store->get($key, $default, $maxAge);
-        if (!is_string($item)) {
+        $item = $this->get($key);
+        if ($item === null || !is_string($item)) {
             return $default;
         }
         return $item;
@@ -256,10 +244,10 @@ public function clearExpired(): bool
     /**
      * @inheritDoc
      */
-    public function getMultiple($keys, $default = null, ?int $maxAge = null)
+    public function getMultiple($keys, $default = null)
     {
         foreach ($keys as $key) {
-            $values[$key] = $this->get($key, $default, $maxAge);
+            $values[$key] = $this->get($key, $default);
         }
         return $values ?? [];
     }
@@ -289,44 +277,46 @@ public function deleteMultiple($keys): bool
     /**
      * @phpstan-impure
      */
-    public function getItemCount(?int $maxAge = null): int
+    public function getItemCount(): int
     {
         $sql = <<<SQL
 SELECT
   COUNT(*)
 FROM
   _cache_item
 SQL;
-        $result = $this->queryItems($sql, null, $maxAge);
+        $result = $this->queryItems($sql);
         /** @var array{int} */
         $row = $result->fetchArray(\SQLITE3_NUM);
+        $this->closeStmt();
 
         return $row[0];
     }
 
     /**
      * @phpstan-impure
      */
-    public function getAllKeys(?int $maxAge = null): array
+    public function getItemKeys(): array
     {
         $sql = <<<SQL
 SELECT
   item_key
 FROM
   _cache_item
 SQL;
-        $result = $this->queryItems($sql, null, $maxAge);
+        $result = $this->queryItems($sql);
         while (($row = $result->fetchArray(\SQLITE3_NUM)) !== false) {
             $keys[] = $row[0];
         }
+        $this->closeStmt();
 
         return $keys ?? [];
     }
 
     /**
      * @inheritDoc
      */
-    public function asOfNow(?int $now = null): CacheStoreInterface
+    public function asOfNow(?int $now = null): CacheInterface
     {
         if ($this->Now !== null) {
             throw new LogicException(
@@ -378,49 +368,34 @@ private function now(): int
         return $this->Now ?? time();
     }
 
-    /**
-     * @return static
-     */
-    private function maybeAsOfNow(): self
+    private function queryItems(string $sql, ?string $key = null): SQLite3Result
     {
-        return $this->Now === null
-            ? $this->asOfNow()
-            : $this;
-    }
-
-    private function queryItems(string $sql, ?string $key, ?int $maxAge): SQLite3Result
-    {
-        $where = [];
-        $bind = [];
-
         if ($key !== null) {
             $where[] = 'item_key = :item_key';
             $bind[] = [':item_key', $key, \SQLITE3_TEXT];
         }
 
-        $bindNow = false;
-        if ($maxAge === null) {
-            $where[] = "(expires_at IS NULL OR expires_at > DATETIME(:now, 'unixepoch'))";
-            $bindNow = true;
-        } elseif ($maxAge) {
-            $where[] = "DATETIME(set_at, :max_age) > DATETIME(:now, 'unixepoch')";
-            $bind[] = [':max_age', "+$maxAge seconds", \SQLITE3_TEXT];
-            $bindNow = true;
-        }
-        if ($bindNow) {
-            $bind[] = [':now', $this->now(), \SQLITE3_INTEGER];
-        }
+        $where[] = "(expires_at IS NULL OR expires_at > DATETIME(:now, 'unixepoch'))";
+        $bind[] = [':now', $this->now(), \SQLITE3_INTEGER];
 
         $where = implode(' AND ', $where);
-        if ($where !== '') {
-            $sql .= " WHERE $where";
-        }
+        $sql .= " WHERE $where";
 
         $stmt = $this->prepare($sql);
         foreach ($bind as [$param, $value, $type]) {
             $stmt->bindValue($param, $value, $type);
         }
 
-        return $this->execute($stmt);
+        $result = $this->execute($stmt);
+        $this->Stmt = $stmt;
+        return $result;
+    }
+
+    private function closeStmt(): void
+    {
+        if ($this->Stmt !== null) {
+            $this->Stmt->close();
+            $this->Stmt = null;
+        }
     }
 }

src/Toolkit/Cache/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Luke Arms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/Toolkit/Cache/README.md

@@ -0,0 +1,33 @@
+# salient/cache
+
+> The cache component of the [Salient toolkit][toolkit]
+
+<p>
+  <a href="https://packagist.org/packages/salient/toolkit"><img src="https://poser.pugx.org/salient/toolkit/v" alt="Latest Stable Version" /></a>
+  <a href="https://packagist.org/packages/salient/toolkit"><img src="https://poser.pugx.org/salient/toolkit/license" alt="License" /></a>
+  <a href="https://github.com/salient-labs/toolkit/actions"><img src="https://github.com/salient-labs/toolkit/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a>
+  <a href="https://codecov.io/gh/salient-labs/toolkit"><img src="https://codecov.io/gh/salient-labs/toolkit/graph/badge.svg?token=Y0l9ZeEtrI" alt="Code Coverage" /></a>
+</p>
+
+---
+
+`salient/cache` provides a SQLite-backed key-value cache.
+
+- Implements [PSR-16 (Common Interface for Caching Libraries)][PSR-16]
+- Multiple cache operations can be grouped into an atomic transaction via a
+  time-bound instance of the cache[^1] that maintains an exclusive lock on the
+  underlying database until it goes out of scope or is explicitly closed
+
+## Documentation
+
+[API documentation][api-docs] for `salient/cache` tracks the `main` branch of
+the toolkit's [GitHub repository][toolkit], where further documentation can also
+be found.
+
+[^1]: See [CacheStore::asOfNow()][asOfNow] for more information.
+
+[api-docs]: https://salient-labs.github.io/toolkit/namespace-Salient.Cache.html
+[asOfNow]:
+  https://salient-labs.github.io/toolkit/Salient.Cache.CacheStore.html#_asOfNow
+[PSR-16]: https://www.php-fig.org/psr/psr-16/
+[toolkit]: https://github.com/salient-labs/toolkit

src/Toolkit/Container/Application.php

@@ -4,7 +4,7 @@
 
 use Salient\Cache\CacheStore;
 use Salient\Console\Target\StreamTarget;
-use Salient\Contract\Cache\CacheStoreInterface;
+use Salient\Contract\Cache\CacheInterface;
 use Salient\Contract\Console\ConsoleMessageType as MessageType;
 use Salient\Contract\Container\ApplicationInterface;
 use Salient\Contract\Core\MessageLevel as Level;
@@ -500,7 +500,7 @@ final public function stopCache()
         return $this;
     }
 
-    private function checkCache(CacheStoreInterface $cache): bool
+    private function checkCache(CacheInterface $cache): bool
     {
         return $cache instanceof CacheStore
             && File::same($this->getCacheDb(false), $cache->getFilename());

src/Toolkit/Container/Container.php

@@ -13,7 +13,7 @@
 use Salient\Container\Exception\ArgumentsNotUsedException;
 use Salient\Container\Exception\InvalidServiceException;
 use Salient\Container\Exception\ServiceNotFoundException;
-use Salient\Contract\Cache\CacheStoreInterface;
+use Salient\Contract\Cache\CacheInterface;
 use Salient\Contract\Console\ConsoleWriterInterface;
 use Salient\Contract\Container\ContainerAwareInterface;
 use Salient\Contract\Container\ContainerInterface;
@@ -58,7 +58,7 @@ class Container implements ContainerInterface, FacadeAwareInterface
     ];
 
     private const DEFAULT_SERVICES = [
-        CacheStoreInterface::class => [CacheStore::class, ServiceLifetime::SINGLETON],
+        CacheInterface::class => [CacheStore::class, ServiceLifetime::SINGLETON],
         ConsoleWriterInterface::class => [ConsoleWriter::class, ServiceLifetime::SINGLETON],
         LoggerInterface::class => [ConsoleLogger::class, ServiceLifetime::INHERIT],
         SyncStoreInterface::class => [SyncStore::class, ServiceLifetime::SINGLETON],