Initial SQLite development (#1)

Reviewed-on: #1

src/Find.php

@@ -0,0 +1,78 @@
+<?php declare(strict_types=1);
+
+namespace BitBadger\PDODocument;
+
+use BitBadger\PDODocument\Mapper\DocumentMapper;
+
+/**
+ * Functions to find documents
+ */
+class Find
+{
+    /**
+     * Retrieve all documents in the given table
+     *
+     * @template TDoc The type of document to be retrieved
+     * @param string $tableName The table from which documents should be retrieved
+     * @param class-string<TDoc> $className The name of the class to be retrieved
+     * @return DocumentList<TDoc> A list of all documents from the table
+     * @throws DocumentException If any is encountered
+     */
+    public static function all(string $tableName, string $className): DocumentList
+    {
+        return Custom::list(Query::selectFromTable($tableName), [], new DocumentMapper($className));
+    }
+
+    /**
+     * Retrieve a document by its ID (returns false if not found)
+     *
+     * @template TDoc The type of document to be retrieved
+     * @param string $tableName The table from which the document should be retrieved
+     * @param mixed $docId The ID of the document to retrieve
+     * @param class-string<TDoc> $className The name of the class to be retrieved
+     * @return false|TDoc The document if it exists, false if not
+     * @throws DocumentException If any is encountered
+     */
+    public static function byId(string $tableName, mixed $docId, string $className): mixed
+    {
+        return Custom::single(Query\Find::byId($tableName), Parameters::id($docId), new DocumentMapper($className));
+    }
+
+    /**
+     * Retrieve documents via a comparison on JSON fields
+     *
+     * @template TDoc The type of document to be retrieved
+     * @param string $tableName The table from which documents should be retrieved
+     * @param array|Field[] $fields The field comparison to match
+     * @param class-string<TDoc> $className The name of the class to be retrieved
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @return DocumentList<TDoc> A list of documents matching the given field comparison
+     * @throws DocumentException If any is encountered
+     */
+    public static function byFields(string $tableName, array $fields, string $className,
+                                    string $conjunction = 'AND'): DocumentList
+    {
+        $namedFields = Parameters::nameFields($fields);
+        return Custom::list(Query\Find::byFields($tableName, $namedFields, $conjunction),
+            Parameters::addFields($namedFields, []), new DocumentMapper($className));
+    }
+
+    /**
+     * Retrieve documents via a comparison on JSON fields, returning only the first result
+     *
+     * @template TDoc The type of document to be retrieved
+     * @param string $tableName The table from which the document should be retrieved
+     * @param array|Field[] $fields The field comparison to match
+     * @param class-string<TDoc> $className The name of the class to be retrieved
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @return false|TDoc The first document if any matches are found, false otherwise
+     * @throws DocumentException If any is encountered
+     */
+    public static function firstByFields(string $tableName, array $fields, string $className,
+                                         string $conjunction = 'AND'): mixed
+    {
+        $namedFields = Parameters::nameFields($fields);
+        return Custom::single(Query\Find::byFields($tableName, $namedFields, $conjunction),
+            Parameters::addFields($namedFields, []), new DocumentMapper($className));
+    }
+}