From bc3fe54e1c7721afed5378b2f6032a1798ebfdc1 Mon Sep 17 00:00:00 2001
From: Joby Elliott <code@byjoby.com>
Date: Fri, 28 Aug 2020 09:36:21 -0600
Subject: [PATCH] updated readme, new Search helper methods

---
 README.md      | 33 +++++++++++++++++++++++++++------
 src/Search.php | 26 ++++++++++++++++++--------
 2 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index c300c56..9deaa20 100644
--- a/README.md
+++ b/README.md
@@ -66,11 +66,37 @@ $obj->undelete();
 $obj->delete(true);
 ```
 
+### Searching
+
+Factories provide an interface for creating `Search` objects, which allow you to enter in various SQL clauses in a structured and abstract fashion.
+
+```php
+// get a new search object from the factory
+$search = $factory->search();
+
+// Search::where() takes SQL for the WHERE clause of a query
+// ${path} syntax is used to reference data within objects, and
+// works everywhere in searches
+$search->where('${dso.date.modified} > :time');
+
+// Search::order() takes SQL to go inside an ORDER BY clause
+// in the final query.
+$search->order('${dso.date.modified} desc');
+
+// Search limit/offset methods can be used for pagination
+// there is also a paginate() method for more conveniently
+// paginating results
+$search->paginate(20,1);
+
+// Search::execute() returns an array of the resulting objects
+$results = $search->execute();
+```
+
 ## Requirements
 
 This system relies **heavily** on the JSON features of the underlying database.
 This means it cannot possibly run without a database that supports JSON features.
-Exact requirements are in flux during development, but basically if a database doesn't have JSON functions it's probably impossible for Destructr to ever work with it.
+Basically if a database doesn't have JSON functions it's probably impossible for Destructr to ever work with it.
 
 At the moment there is pretty decent support for:
 
@@ -85,11 +111,6 @@ In practice this means Destructr will **never** be able to run on less than the
 * PostgreSQL >=9.3
 * SQL Server >=2016
 
-There is also a SQLite driver available that inserts a PHP JSON function.
-It doesn't support generated columns, so its indexing and optimization capabilities are limited.
-Nevertheless, SQLite can be reasonably performant for many smaller/simpler applications.
-For more information see [the legacy drivers readme](src/LegacyDrivers/README.md).
-
 Theoretically Destructr is also an excellent fit for NoSQL databases.
 If I ever find myself needing it there's a good chance it's possible to write drivers for running it on something like MongoDB as well.
 It might even be kind of easy.
diff --git a/src/Search.php b/src/Search.php
index 52fac78..d48dce1 100644
--- a/src/Search.php
+++ b/src/Search.php
@@ -3,7 +3,6 @@
 namespace Destructr;
 
 use Destructr\DSOFactoryInterface;
-use Destructr\Drivers\DSODriverInterface;
 
 class Search implements \Serializable
 {
@@ -13,12 +12,12 @@ class Search implements \Serializable
     protected $limit;
     protected $offset;
 
-    public function __construct(DSOFactoryInterface $factory=null)
+    public function __construct(DSOFactoryInterface $factory = null)
     {
         $this->factory = $factory;
     }
 
-    public function quote(string $str) : string
+    public function quote(string $str): string
     {
         return $this->factory->quote($str);
     }
@@ -33,7 +32,7 @@ class Search implements \Serializable
         return $this->factory->executeSearch($this, $params, $deleted);
     }
 
-    public function where(string $set = null) : ?string
+    public function where(string $set = null): ?string
     {
         if ($set !== null) {
             $this->where = $set;
@@ -41,7 +40,18 @@ class Search implements \Serializable
         return $this->where;
     }
 
-    public function order(string $set = null) : ?string
+    public function paginate(int $perPage, int $page = 1)
+    {
+        $this->limit($perPage);
+        $this->offset(($page - 1) * $perPage);
+    }
+
+    public function pageCount(int $perPage)
+    {
+        return ceil($this->count() / $perPage);
+    }
+
+    public function order(string $set = null): ?string
     {
         if ($set !== null) {
             $this->order = $set;
@@ -49,7 +59,7 @@ class Search implements \Serializable
         return $this->order;
     }
 
-    public function limit(int $set = null) : ?int
+    public function limit(int $set = null): ?int
     {
         if ($set !== null) {
             $this->limit = $set;
@@ -57,7 +67,7 @@ class Search implements \Serializable
         return $this->limit;
     }
 
-    public function offset(int $set = null) : ?int
+    public function offset(int $set = null): ?int
     {
         if ($set !== null) {
             $this->offset = $set;
@@ -68,7 +78,7 @@ class Search implements \Serializable
     public function serialize()
     {
         return json_encode(
-            [$this->where(),$this->order(),$this->limit(),$this->offset()]
+            [$this->where(), $this->order(), $this->limit(), $this->offset()]
         );
     }