Fixes in PHP client for documentation (#71)

* Usage should be in comments for method: load, delete and store in DocumentSession and openSession in DocumentStore

* Usage should be available on class description
* Faceted searches fixes
* DocumentQueryCustomization class implementation

* Methods should have Usage samples

* Methods should have usage explanations

* Search terms should be able to be passed as an array

* interface for ignoreChangesFor object should be enabled and available to be used in code

* Update method comments

* Need interface be open for method conditionalLoad

* OperationExecutor send method should be updated with Usage examples

* waitForCompletion should throw TimoutException if duration is defined

* In Class Operation method waitForCompletion should return BulkOperationResult object upon succesfull completion

* Duration should have option to be converted to DateTime interval

* GetDetailedCollectionStatisticsOperation classes should be included

* Add support to ToggleDatabasesStateOperation to receive multiple database names

* Implement CompactDatabaseOperation and supporting files

* PutIndexOperation should accept simple array of IndexDefinitions

* We should be able to pass array of strings as parameter

* Update classes for TogleDatabaseStateOperation

* We should be able to pass array with IndexFieldOptions

* DocumentQuery::aggregateBy should be able to receive FacetBaseArray as parameter

* Updates required for facet classes

* Implement getRevision in DocumentSessionAttachments

* Rename includeRevisions builder

* Document extensions > Revisions > Client API > Operations > Configure revisions
* Document extensions > Revisions > Client API > Operations > Configure conflict revisions
* Document extensions > Revisions > Client API > Operations > Get revisions

* add method ofYears

* Implement conditionalLoad in LazySessionOperations

* Implement whatChangedFor in InMemoryDocumentSessionOperations

* Time for rollups should be longer

* Add support to PutServerWideClientConfigurationOperation

Author: alxsabo

src/Documents/DocumentStore.php

@@ -145,7 +145,17 @@ public function close(): void
     /**
      * Opens the session for a particular database
      *
-     * @param null|string|SessionOptions $dbNameOrOptions Database to use
+     * Usage
+     *
+     * Open session for a 'default' database configured in 'DocumentStore'
+     *  - openSession(): DocumentSessionInterface;
+     *
+     * Open session for a specified database
+     *  - openSession(string $database): DocumentSessionInterface;
+     *
+     *  - openSession(SessionOptions $sessionOptions): DocumentSessionInterface;
+     *
+     * @param null|string|SessionOptions $dbNameOrOptions Database name or options to use
      *
      * @return DocumentSessionInterface Document session
      */

src/Documents/Indexes/AbstractGenericIndexCreationTask.php

@@ -60,6 +60,10 @@ protected function index(?string $field, ?FieldIndexing $indexing): void
 
     /**
      * Register a field to be spatially indexed
+     *
+     * Usage:
+     *   - spatial("shape", function ($x) {...})
+     *
      * @param string|null $field Field
      * @param Closure $indexing factory for spatial options
      */

src/Documents/Indexes/AbstractJavaScriptIndexCreationTask.php

@@ -35,8 +35,11 @@ public function getFields(): IndexFieldOptionsArray
         return $this->definition->getFields();
     }
 
-    public function setFields(?IndexFieldOptionsArray $fields): void
+    public function setFields(null|IndexFieldOptionsArray|array $fields): void
     {
+        if (is_array($fields)) {
+            $fields = IndexFieldOptionsArray::fromArray($fields);
+        }
         $this->definition->setFields($fields);
     }
 

src/Documents/Indexes/IndexDefinition.php

@@ -12,7 +12,7 @@
 
 class IndexDefinition extends IndexDefinitionBase implements ResultInterface
 {
-    public function __constructor()
+    public function __construct()
     {
         parent::__construct();
 

src/Documents/Operations/BulkOperationDetailsArray.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace RavenDB\Documents\Operations;
+
+use _PHPStan_b8e553790\Nette\Neon\Exception;
+use RavenDB\Type\TypedArray;
+
+class BulkOperationDetailsArray extends TypedArray
+{
+    public function __construct()
+    {
+        parent::__construct(BulkOperationDetailsInterface::class);
+    }
+
+    /**
+     * @throws Exception
+     */
+    public static function createNewItemObjectFromValue(mixed $value): object
+    {
+        if (!array_key_exists('$type', $value)) {
+            throw new Exception('Details array should have \'\$type\' key inside.');
+        }
+
+        $type = $value['$type'];
+
+//        print_r($type);
+
+        switch ($type) {
+            case 'Raven.Client.Documents.Operations.BulkOperationResult+DeleteDetails, Raven.Client':
+                return BulkOperationResultDeleteDetails::fromArray($value);
+            case 'Raven.Client.Documents.Operations.BulkOperationResult+PatchDetails, Raven.Client':
+                return BulkOperationResultPatchDetails::fromArray($value);
+            default:
+
+                break;
+        }
+
+        throw new Exception('Unknown type: ' . $type);
+
+    }
+}

src/Documents/Operations/BulkOperationDetailsInterface.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace RavenDB\Documents\Operations;
+
+interface BulkOperationDetailsInterface
+{
+
+}

src/Documents/Operations/BulkOperationResult.php

@@ -0,0 +1,103 @@
+<?php
+
+namespace RavenDB\Documents\Operations;
+
+use Symfony\Component\Serializer\Annotation\SerializedName;
+
+class BulkOperationResult
+{
+    #[SerializedName('Total')]
+    private ?int $total = null;
+    #[SerializedName('DocumentsProcessed')]
+    private ?int $documentsProcessed = null;
+    #[SerializedName('AttachmentsProcessed')]
+    private ?int $attachmentsProcessed = null;
+    #[SerializedName('CountersProcessed')]
+    private ?int $countersProcessed = null;
+    #[SerializedName('TimeSeriesProcessed')]
+    private ?int $timeSeriesProcessed = null;
+    #[SerializedName('Query')]
+    private ?string $query = null;
+    // array<BulkOperationDetailsInterface> $details
+    #[SerializedName('Details')]
+    private ?BulkOperationDetailsArray $details = null;
+
+//    private bool $shouldPersist = false;
+//    private bool $canMerge = true;
+//    private string $message = "Processed {Total:#,#0} items.";
+
+    public function __construct()
+    {
+        $this->details = new BulkOperationDetailsArray();
+    }
+
+    public function getTotal(): ?int
+    {
+        return $this->total;
+    }
+
+    public function setTotal(?int $total): void
+    {
+        $this->total = $total;
+    }
+
+    public function getDocumentsProcessed(): ?int
+    {
+        return $this->documentsProcessed;
+    }
+
+    public function setDocumentsProcessed(?int $documentsProcessed): void
+    {
+        $this->documentsProcessed = $documentsProcessed;
+    }
+
+    public function getAttachmentsProcessed(): ?int
+    {
+        return $this->attachmentsProcessed;
+    }
+
+    public function setAttachmentsProcessed(?int $attachmentsProcessed): void
+    {
+        $this->attachmentsProcessed = $attachmentsProcessed;
+    }
+
+    public function getCountersProcessed(): ?int
+    {
+        return $this->countersProcessed;
+    }
+
+    public function setCountersProcessed(?int $countersProcessed): void
+    {
+        $this->countersProcessed = $countersProcessed;
+    }
+
+    public function getTimeSeriesProcessed(): ?int
+    {
+        return $this->timeSeriesProcessed;
+    }
+
+    public function setTimeSeriesProcessed(?int $timeSeriesProcessed): void
+    {
+        $this->timeSeriesProcessed = $timeSeriesProcessed;
+    }
+
+    public function getQuery(): ?string
+    {
+        return $this->query;
+    }
+
+    public function setQuery(?string $query): void
+    {
+        $this->query = $query;
+    }
+
+    public function getDetails(): ?BulkOperationDetailsArray
+    {
+        return $this->details;
+    }
+
+    public function setDetails(?BulkOperationDetailsArray $details): void
+    {
+        $this->details = $details;
+    }
+}

src/Documents/Operations/BulkOperationResultDeleteDetails.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace RavenDB\Documents\Operations;
+
+class BulkOperationResultDeleteDetails implements BulkOperationDetailsInterface
+{
+    private ?string $id = null;
+    public ?int $etag = null;
+
+    public function getId(): ?string
+    {
+        return $this->id;
+    }
+
+    public function setId(?string $id): void
+    {
+        $this->id = $id;
+    }
+
+    public function getEtag(): ?int
+    {
+        return $this->etag;
+    }
+
+    public function setEtag(?int $etag): void
+    {
+        $this->etag = $etag;
+    }
+
+    public static function fromArray(array $data): BulkOperationResultDeleteDetails
+    {
+        $object = new BulkOperationResultDeleteDetails();
+
+        if (array_key_exists('Id', $data)) {
+            $object->setId($data['Id']);
+        }
+
+        if (array_key_exists('ETag', $data)) {
+            $object->setEtag($data['ETag']);
+        }
+
+        return $object;
+    }
+}

src/Documents/Operations/BulkOperationResultOperationDetails.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace RavenDB\Documents\Operations;
+
+class BulkOperationResultOperationDetails
+{
+    public ?string $query = null;
+
+    public function getQuery(): ?string
+    {
+        return $this->query;
+    }
+
+    public function setQuery(?string $query): void
+    {
+        $this->query = $query;
+    }
+
+    public static function fromArray(array $data): BulkOperationResultOperationDetails
+    {
+        $object = new BulkOperationResultOperationDetails();
+
+        if (array_key_exists('Query', $data)) {
+            $object->setQuery($data['Query']);
+        }
+
+        return $object;
+    }
+}

src/Documents/Operations/BulkOperationResultPatchDetails.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace RavenDB\Documents\Operations;
+
+class BulkOperationResultPatchDetails implements BulkOperationDetailsInterface
+{
+    public ?string $id = null;
+    public ?string $changeVector = null;
+    public ?PatchStatus $status = null;
+
+    public function getId(): ?string
+    {
+        return $this->id;
+    }
+
+    public function setId(?string $id): void
+    {
+        $this->id = $id;
+    }
+
+    public function getChangeVector(): ?string
+    {
+        return $this->changeVector;
+    }
+
+    public function setChangeVector(?string $changeVector): void
+    {
+        $this->changeVector = $changeVector;
+    }
+
+    public function getStatus(): ?PatchStatus
+    {
+        return $this->status;
+    }
+
+    public function setStatus(?PatchStatus $status): void
+    {
+        $this->status = $status;
+    }
+
+    public static function fromArray(array $data): BulkOperationResultPatchDetails
+    {
+        $object = new BulkOperationResultPatchDetails();
+
+        if (array_key_exists('Id', $data)) {
+            $object->setId($data['Id']);
+        }
+
+        if (array_key_exists('ChangeVector', $data)) {
+            $object->setChangeVector($data['ChangeVector']);
+        }
+
+        if (array_key_exists('Status', $data)) {
+            $object->setStatus($data['Status']);
+        }
+
+        return $object;
+    }
+}