Find object aggregate service, find, sort and limit service, and JSON serialize models in KeyCollections

Author: robgridley

README.md

@@ -170,6 +170,40 @@ $jobs = $pace->job
 	->find();
 ```
 
+### Limiting
+
+Use the `offset()` and `limit()` methods to limit your results. The default offset is 0 if it is not specified.
+
+```php
+$jobs = $pace->job
+	->filter('adminStatus/@openJob', true)
+	->sort('@dateSetup', true)
+	->limit(50)
+	->find();
+```
+
+You can also use the `paginate()` method to set the offset and limit for a page.
+
+```php
+$jobs = $pace->job
+	->filter('adminStatus/@openJob', true)
+	->sort('@dateSetup', true)
+	->paginate(1, 50)
+	->find();
+```
+
+### Eager loading
+
+The `load()` method preloads the models as part of the find request, using the find object aggregate service. It does not read the entire object; you must specify a list of fields in XPath. If the offset and limit are not specified, then 0 and 1,000 will be used by default.
+
+```php
+$employees = $pace->model('Employee')->filter('@status', 'A')->load([
+    '@firstName',
+    '@lastName',
+    'department' => 'department/@description',
+])->find();
+```
+
 ## Dates
 
 Dates are automatically converted to and from [Carbon](http://carbon.nesbot.com/) instances. Check out the `Soap\DateTimeMapper` and `Soap\Factory` classes if you want to see how this happens.

src/Client.php

@@ -2,6 +2,7 @@
 
 namespace Pace;
 
+use BadMethodCallException;
 use Closure;
 use InvalidArgumentException;
 use Pace\Contracts\Soap\Factory as SoapFactory;
@@ -131,15 +132,33 @@ public function deleteObject(string $object, mixed $key): void
      * @param string $object
      * @param string $filter
      * @param array|null $sort
+     * @param int|null $offset
+     * @param int|null $limit
+     * @param array $fields
      * @return array
      */
-    public function findObjects(string $object, string $filter, ?array $sort = null): array
+    public function findObjects(string $object, string $filter, ?array $sort = null, ?int $offset = null, ?int $limit = null, array $fields = []): array
     {
-        if (is_null($sort)) {
-            return $this->service('FindObjects')->find($object, $filter);
+        if (!empty($fields)) {
+            if (is_null($offset) || is_null($limit)) {
+                throw new BadMethodCallException('Offset and limit are required when fields is not empty.');
+            }
+
+            // I think this is a bug in the Pace SOAP API? This method always returns limit + 1.
+            $limit -= 1;
+
+            return $this->service('FindObjects')->loadValueObjects($object, $filter, $sort, $offset, $limit, $fields);
+        }
+
+        if (!is_null($limit)) {
+            return $this->service('FindObjects')->findSortAndLimit($object, $filter, $sort, $offset, $limit);
+        }
+
+        if (!is_null($sort)) {
+            return $this->service('FindObjects')->findAndSort($object, $filter, $sort);
         }
 
-        return $this->service('FindObjects')->findAndSort($object, $filter, $sort);
+        return $this->service('FindObjects')->find($object, $filter);
     }
 
     /**

src/KeyCollection.php

@@ -28,6 +28,40 @@ public function __construct(protected Model $model, protected array $keys)
     {
     }
 
+    /**
+     * Create a new key collection instance from an array of value objects.
+     *
+     * @param Model $model
+     * @param array $valueObjects
+     * @return static
+     */
+    public static function fromValueObjects(Model $model, array $valueObjects): static
+    {
+        $keys = array_map(fn(object $valueObject) => $valueObject->primaryKey, $valueObjects);
+        $readModels = array_combine(
+            $keys,
+            array_map(function (object $valueObject) use ($model) {
+                $fields = $valueObject->fields->ValueField;
+                $fields = is_array($fields) ? $fields : [$fields];
+                $attributes = array_combine(
+                    array_map(fn(object $field) => $field->name, $fields),
+                    array_map(fn(object $field) => $field->value, $fields)
+                );
+                $attributes['primaryKey'] = $valueObject->primaryKey;
+
+                $readModel = $model->newInstance($attributes);
+                $readModel->exists = true;
+
+                return $readModel;
+            }, $valueObjects)
+        );
+
+        $collection = new static($model, $keys);
+        $collection->readModels = $readModels;
+
+        return $collection;
+    }
+
     /**
      * Convert this instance to its string representation.
      *
@@ -146,7 +180,7 @@ public function isEmpty(): bool
      */
     function jsonSerialize(): array
     {
-        return $this->all();
+        return array_map(fn($value) => $value instanceof JsonSerializable ? $value->jsonSerialize() : $value, $this->all());
     }
 
     /**

src/Model.php

@@ -195,11 +195,23 @@ public function duplicate(mixed $newKey = null): ?static
      *
      * @param string $filter
      * @param array|null $sort
+     * @param int|null $offset
+     * @param int|null $limit
+     * @param array $fields
      * @return KeyCollection
      */
-    public function find(string $filter, ?array $sort = null): KeyCollection
+    public function find(string $filter, ?array $sort = null, ?int $offset = null, ?int $limit = null, array $fields = []): KeyCollection
     {
-        $keys = $this->client->findObjects($this->type, $filter, $sort);
+        if (!empty($fields)) {
+            if (is_null($offset)) {
+                $offset = 0;
+            }
+            if (is_null($limit)) {
+                $limit = 1000;
+            }
+        }
+
+        $keys = $this->client->findObjects($this->type, $filter, $sort, $offset, $limit, $fields);
 
         return $this->newKeyCollection($keys);
     }
@@ -657,6 +669,13 @@ public function newBuilder(): Builder
      */
     protected function newKeyCollection(array $keys): KeyCollection
     {
+        foreach ($keys as $key) {
+            if (is_object($key)) {
+                return KeyCollection::fromValueObjects($this, $keys);
+            }
+            break;
+        }
+
         return new KeyCollection($this, $keys);
     }
 

src/Services/FindObjects.php

@@ -38,4 +38,58 @@ public function findAndSort(string $object, string $filter, array $sort): array
 
         return isset($response->out->string) ? (array)$response->out->string : [];
     }
+
+    /**
+     * Find, sort and limit objects.
+     *
+     * @param string $object
+     * @param string $filter
+     * @param array|null $sort
+     * @param int $offset
+     * @param int $limit
+     * @return array
+     */
+    public function findSortAndLimit(string $object, string $filter, ?array $sort, int $offset, int $limit): array
+    {
+        $request = ['in0' => $object, 'in1' => $filter, 'in2' => $sort, 'in3' => $offset, 'in4' => $limit];
+
+        $response = $this->soap->findSortAndLimit($request);
+
+        return isset($response->out->string) ? (array)$response->out->string : [];
+    }
+
+    /**
+     * Call the find object aggregate service.
+     *
+     * @param string $object
+     * @param string $filter
+     * @param array|null $sort
+     * @param int $offset
+     * @param int $limit
+     * @param array $fields
+     * @param mixed $primaryKey
+     * @return array
+     */
+    public function loadValueObjects(string $object, string $filter, ?array $sort, int $offset, int $limit, array $fields, mixed $primaryKey = null): array
+    {
+        $request = [
+            'in0' => [
+                'objectName' => $object,
+                'xpathFilter' => $filter,
+                'xpathSorts' => $sort,
+                'offset' => $offset,
+                'limit' => $limit,
+                'fields' => $fields,
+                'primaryKey' => $primaryKey,
+            ],
+        ];
+
+        $response = $this->soap->loadValueObjects($request);
+
+        if (is_array($response->out->valueObjects->ValueObject)) {
+            return $response->out->valueObjects->ValueObject;
+        }
+
+        return [$response->out->valueObjects->ValueObject];
+    }
 }

src/XPath/Builder.php

@@ -39,6 +39,27 @@ class Builder
      */
     protected array $sorts = [];
 
+    /**
+     * The fields to load.
+     *
+     * @var array
+     */
+    protected array $fields = [];
+
+    /**
+     * The result offset.
+     *
+     * @var int
+     */
+    protected int $offset = 0;
+
+    /**
+     * The results limit.
+     *
+     * @var int|null
+     */
+    protected ?int $limit = null;
+
     /**
      * Create a new instance.
      *
@@ -108,7 +129,7 @@ public function filter(string|Closure $xpath, mixed $operator = null, mixed $val
      */
     public function find(): KeyCollection
     {
-        return $this->model->find($this->toXPath(), $this->toXPathSort());
+        return $this->model->find($this->toXPath(), $this->toXPathSort(), $this->offset, $this->limit, $this->toFieldDescriptor());
     }
 
     /**
@@ -158,6 +179,64 @@ public function get(): KeyCollection
         return $this->find();
     }
 
+    /**
+     * Load the specified fields.
+     *
+     * @param array $fields
+     * @return $this
+     */
+    public function load(array $fields): static
+    {
+        foreach ($fields as $key => $xpath) {
+            if (is_int($key)) {
+                $key = ltrim($xpath, '@');
+            }
+            $this->fields[$key] = $xpath;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Set the result offset.
+     *
+     * @param int $offset
+     * @return $this
+     */
+    public function offset(int $offset): static
+    {
+        $this->offset = $offset;
+
+        return $this;
+    }
+
+    /**
+     * Set the results limit.
+     *
+     * @param int $limit
+     * @return $this
+     */
+    public function limit(int $limit): static
+    {
+        $this->limit = $limit;
+
+        return $this;
+    }
+
+    /**
+     * Paginate the results.
+     *
+     * @param int $page
+     * @param int $perPage
+     * @return $this
+     */
+    public function paginate(int $page, int $perPage = 25): static
+    {
+        $offset = max($page - 1, 0) * $perPage;
+
+        return $this->offset($offset)->limit($perPage);
+    }
+
     /**
      * Add an "in" filter.
      *
@@ -292,6 +371,21 @@ public function toXPathSort(): ?array
         return count($this->sorts) ? ['XPathDataSort' => $this->sorts] : null;
     }
 
+    /**
+     * Get the field descriptor array.
+     *
+     * @return array
+     */
+    public function toFieldDescriptor(): array
+    {
+        return array_map(function (string $name, string $xpath) {
+            return [
+                'name' => $name,
+                'xpath' => $xpath,
+            ];
+        }, array_keys($this->fields), array_values($this->fields));
+    }
+
     /**
      * Compile a simple filter.
      *

tests/KeyCollectionTest.php

@@ -99,10 +99,10 @@ public function testJsonSerializable()
         $model = Mockery::mock(Model::class);
         $collection = new KeyCollection($model, [5]);
         $model->shouldReceive('read')->with(5)->once()->andReturnSelf();
+        $model->shouldReceive('jsonSerialize')->once()->andReturn([]);
         $array = $collection->jsonSerialize();
         $this->assertInstanceOf('JsonSerializable', $collection);
         $this->assertIsArray($array);
-        $this->assertContainsOnlyInstancesOf('JsonSerializable', $array);
     }
 
     public function testArrayAccess()