✨ Optional dialog setting for the document search

CHANGELOG.md

@@ -3,7 +3,11 @@
 All notable changes to `laravel-docuware` will be documented in this file.
 
 ## Not released
-
+
+## 0.3.1 - 2021-04-21
+
+- It is no longer required to set the dialog to search documents.
+
 ## 0.3.0 - 2021-04-20
 
 ⚠️ This release introduces breaking changes. Update with caution ⚠️

README.md

@@ -109,39 +109,46 @@ DocuWare::deleteDocument($fileCabinetId, $documentId);
 use CodebarAg\DocuWare\Facades\DocuWare;
 
 /**
- * Most basic example to search for documents.
+ * Most basic example to search for documents. You only need to provide a valid
+ * file cabinet id.
  */
+$id = '87356f8d-e50c-450b-909c-4eaccd318fbf';
+
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->get();
 
 /**
- * Search in multiple file cabinets.
+ * Search in multiple file cabinets. Provide an array of additional
+ * file cabinet ids.
  */
+$ids = [
+    '0ee72de3-4258-4353-8020-6a3ff6dd650f',
+    '3f9cb4ff-82f2-44dc-b439-dd648269064f',
+];
+
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
-    ->additionalFileCabinets($additionalFileCabinetIds)
+    ->fileCabinet($id)
+    ->additionalFileCabinets($ids)
     ->get();
 
 /**
  * Find results on the next page. 
+ * 
  * Default: 1
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->page(2)
     ->get();
 
 /**
- * Define the number of results which should be shown per page. 
+ * Define the number of results which should be shown per page.
+ * 
  * Default: 50
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->perPage(30)
     ->get();
 
@@ -150,55 +157,59 @@ $paginator = DocuWare::search()
  * cabinet before you can use this feature.
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->fulltext('My secret document')
     ->get();
 
 /**
  * Search documents which are created from the first of march.
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->dateFrom(Carbon::create(2021, 3, 1))
     ->get();
 
 /**
  * Search documents which are created until the first of april.
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->dateUntil(Carbon::create(2021, 4, 1))
     ->get();
 
 /**
- * Order the results by field name. Possibly values: 'desc' or 'asc'
+ * Order the results by field name. Supported values: 'asc', 'desc'
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->orderBy('DWSTOREDATETIME', 'desc')
     ->get();
 
 /**
  * Search documents filtered to the value. You can specify multiple filters.
  */
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
-    ->dialog($dialogId)
+    ->fileCabinet($id)
     ->filter('TYPE', 'Order')
     ->filter('OTHER_FIELD', 'other')
     ->get();
 
 /**
- * Or combine all together.
+ * You can specify the dialog which should be used.
  */
+$dialogId = 'bb42c30a-89fc-4b81-9091-d7e326caba62';
+
 $paginator = DocuWare::search()
-    ->fileCabinet($fileCabinetId)
+    ->fileCabinet($id)
     ->dialog($dialogId)
-    ->additionalFileCabinets($additionalFileCabinetIds)
+    ->get();
+
+/**
+ * You can also combine everything.
+ */
+$paginator = DocuWare::search()
+    ->fileCabinet($id)
+    ->additionalFileCabinets($ids)
     ->page(2)
     ->perPage(30)
     ->fulltext('My secret document')
@@ -207,12 +218,13 @@ $paginator = DocuWare::search()
     ->filter('TYPE', 'Order')
     ->filter('OTHER_FIELD', 'other')
     ->orderBy('DWSTOREDATETIME', 'desc')
+    ->dialog($dialogId)
     ->get();
 ```
 
 Please see [Tests](tests/Feature/DocuWareTest.php) for more details.
 
-## 🏋️ DTO's
+## 🏋️ DTO showcase
 
 ```php
 CodebarAg\DocuWare\DTO\FileCabinet {

src/DocuWareSearch.php

@@ -41,9 +41,9 @@ public function dialog(string $dialogId): self
         return $this;
     }
 
-    public function additionalFileCabinets(array $additionalCabinets): self
+    public function additionalFileCabinets(array $ids): self
     {
-        $this->additionalFileCabinetIds = $additionalCabinets;
+        $this->additionalFileCabinetIds = $ids;
 
         return $this;
     }
@@ -85,9 +85,9 @@ public function dateUntil(Carbon $dateUntil): self
 
     public function orderBy(string $field, string $direction = 'asc'): self
     {
-        $this->orderField = "\"{$field}\"";
+        $this->orderField = $field;
 
-        $this->orderDirection = $direction; // 'asc' || 'desc'
+        $this->orderDirection = $direction; // Supported values: 'asc', 'desc'
 
         return $this;
     }
@@ -108,12 +108,15 @@ public function get(): DocumentPaginator
         $this->guard();
 
         $url = sprintf(
-            '%s/DocuWare/Platform/FileCabinets/%s/Query/DialogExpression?dialogId=%s',
+            '%s/DocuWare/Platform/FileCabinets/%s/Query/DialogExpression',
             config('docuware.credentials.url'),
             $this->fileCabinetId,
-            $this->dialogId,
         );
 
+        if ($this->dialogId) {
+            $url .= "?dialogId={$this->dialogId}";
+        }
+
         $condition = [];
 
         if (Str::length($this->searchTerm) >= 1) {
@@ -181,11 +184,6 @@ protected function guard(): void
             UnableToSearch::cabinetNotSet(),
         );
 
-        throw_if(
-            is_null($this->dialogId),
-            UnableToSearch::dialogNotSet(),
-        );
-
         throw_if(
             $this->page <= 0,
             UnableToSearch::invalidPageNumber($this->page),

src/Exceptions/UnableToSearch.php

@@ -14,14 +14,6 @@ public static function cabinetNotSet(): self
         );
     }
 
-    public static function dialogNotSet(): self
-    {
-        return new static(
-            'You need to specify the dialog id. ' .
-                'Try to chain: "->dialog($id)"',
-        );
-    }
-
     public static function invalidPageNumber(int $page): self
     {
         return new static(

tests/Feature/DocuWareTest.php

@@ -211,14 +211,14 @@ public function it_can_upload_and_delete_a_document()
     public function it_can_search_documents()
     {
         $fileCabinetId = 'f95f2093-e790-495b-af04-7d198a296c5e';
+        $additionalFileCabinetIds = ['986ee421-9d6b-4a4b-837d-b3e61ea2e681'];
         $dialogId = '6a84f3da-7514-4116-86df-42b56acd19a7';
-        $additionalFileCabinets = ['986ee421-9d6b-4a4b-837d-b3e61ea2e681'];
 
         $paginator = (new DocuWare())
             ->search()
             ->fileCabinet($fileCabinetId)
+            ->additionalFileCabinets($additionalFileCabinetIds)
             ->dialog($dialogId)
-            ->additionalFileCabinets($additionalFileCabinets)
             ->page(1)
             ->perPage(5)
             ->fulltext('test')