Improve UX, flesh out README

paragonie · Sep 19, 2022 · c546e3f · c546e3f
1 parent b67324f
commit c546e3f
Show file tree

Hide file tree

Showing 3 changed files with 75 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -9,6 +9,46 @@
 Extends [EasyDB](https://github.com/paragonie/easydb), caches Prepared Statements
 to reduce the number of database round trips. **Requires PHP 8.0 or newer.**
 
+## Installing
+
+```terminal
+composer require paragonie/easydb-cache
+```
+
+## Usage
+
+To use EasyDB with prepared statement caching, you can either change the class you're importing
+in your code, or update your code to use `EasyDBCache` instead. Alternatively, you can use the
+named constructor with your existing object.
+
+Afterwards, the EasyDB API is exactly the same as EasyDBCache.
+
+### Updating Import Statements
+
+```diff
+- use ParagonIE\EasyDB\EasyDB;
++ use ParagonIE\EasyDB\EasyDBCache;
+```
+
+### Updating Your Code
+
+```diff
+use ParagonIE\EasyDB\EasyDB;
++ use ParagonIE\EasyDB\EasyDBCache;
+
+- $db = new EasyDB(
++ $db = new EasyDBCache(
+```
+
+### Named Constructor
+
+```diff
++ use ParagonIE\EasyDB\EasyDBCache;
+
+- $db = new EasyDB(/* ... */);
++ $db = EasyDBCache::fromEasyDB(new EasyDB(/* ... */));
+```
+
 ## Support Contracts
 
 If your company uses this library in their products or services, you may be

diff --git a/src/EasyDBCache.php b/src/EasyDBCache.php
@@ -9,6 +9,7 @@
 use SodiumException;
 use TypeError;
 use function
+    is_null,
     is_string,
     sodium_crypto_shorthash,
     sodium_crypto_shorthash_keygen;
@@ -20,7 +21,7 @@ class EasyDBCache extends EasyDB
 {
     protected HiddenString $cacheKey;
 
-    /** @var array<string, \PDOStatement> $cache */
+    /** @var array<string, PDOStatement> $cache */
     protected array $cache = [];
 
     /**
@@ -34,20 +35,38 @@ class EasyDBCache extends EasyDB
      * @throws Exception
      */
     public function __construct(
-        \PDO $pdo,
+        PDO $pdo,
         string $dbEngine = '',
         array $options = [],
-        HiddenString $cacheKey = null
+        ?HiddenString $cacheKey = null
     ) {
         parent::__construct($pdo, $dbEngine, $options);
-        if (\is_null($cacheKey)) {
+        if (is_null($cacheKey)) {
             $cacheKey = new HiddenString(
                 sodium_crypto_shorthash_keygen()
             );
         }
         $this->cacheKey = $cacheKey;
     }
 
+    /**
+     * @param EasyDB $db
+     * @param ?HiddenString $cacheKey
+     * @return EasyDBCache
+     * @throws Exception
+     */
+    public static function fromEasyDB(
+        EasyDB $db,
+        ?HiddenString $cacheKey = null
+    ): EasyDBCache {
+        return new EasyDBCache(
+            $db->pdo,
+            $db->dbEngine,
+            $db->options,
+            $cacheKey
+        );
+    }
+
     /**
      * Flushes the cache of prepared statentes
      *

diff --git a/tests/EasyDBCacheTest.php b/tests/EasyDBCacheTest.php
@@ -3,6 +3,7 @@
 
 use ParagonIE\EasyDB\EasyDB;
 use ParagonIE\EasyDB\EasyDBCache;
+use ParagonIE\HiddenString\HiddenString;
 use PHPUnit\Framework\TestCase;
 use SodiumException;
 
@@ -31,6 +32,17 @@ public function setUp(): void
         $this->db2 = new EasyDB($pdo);
     }
 
+    public function testConstructors()
+    {
+        $pdo = new \PDO('sqlite::memory:');
+        $cacheKey = new HiddenString(sodium_crypto_shorthash_keygen());
+        $easy = new EasyDB($pdo);
+        $c1 = new EasyDBCache($pdo, 'sqlite', [], $cacheKey);
+        $c2 = EasyDBCache::fromEasyDB($easy, $cacheKey);
+        $this->assertTrue($c1->getPdo() instanceof \PDO);
+        $this->assertTrue($c2->getPdo() instanceof \PDO);
+    }
+
     /**
      * @throws SodiumException
      */