Merge pull request #102 from dcblogdev/folders-find-by-name

Folders find by name

Author: dcblogdev

docs/v3/msgraph/emails.md

@@ -14,11 +14,13 @@ MsGraph::emails();
 
 Return a list of emails
 
+If no options are set emails are loaded from the inbox folder.
+
 ```php
-MsGraph::emails()->get();
+MsGraph::emails()->get($folderIdOrName = 'Inbox', $params = []);
 ```
 
-By default, only 10 emails are returned this can be changed by either using GET requests or pass an array of option to get()
+By default, only 25 emails are returned this can be changed by either using GET requests or pass an array of option to get()
 
 Option 1: GET Request
 
@@ -34,21 +36,21 @@ The default array that is used internally is below, you can override these optio
 
 ```php
 [
-    "\$orderby" => "displayName",
-    "\$top" => $top,
-    "\$skip" => $skip,
-    "\$count" => "true",
+    '$orderby' => "displayName",
+    '$top' => $top,
+    '$skip' => $skip,
+    '$count' => "true",
 ]
 ```
 
 This would look like this:
 
 ```php
-MsGraph::emails()->get([
-    "\$orderby" => "displayName",
-    "\$top" => 15,
-    "\$skip" => 0,
-    "\$count" => "true",
+MsGraph::emails()->get('Inbox', [
+    '$orderby' => "displayName",
+    '$top' => 15,
+    '$skip' => 0,
+    '$count' => "true",
 ]);
 ```
 
@@ -259,6 +261,12 @@ MsGraph::emails()->folders()->get(array $params = [], bool $sort = false, array
 MsGraph::emails()->folders()->find($id)
 ```
 
+## Get folder by name
+
+```php
+MsGraph::emails()->folders()->findByName($name)
+```
+
 ## Create folder
 
 ```php

src/Resources/Emails/Emails.php

@@ -3,6 +3,7 @@
 namespace Dcblogdev\MsGraph\Resources\Emails;
 
 use Dcblogdev\MsGraph\Facades\MsGraph;
+use Dcblogdev\MsGraph\Validators\GraphQueryValidator;
 use Exception;
 
 class Emails extends MsGraph
@@ -114,42 +115,39 @@ public function skip(string $skip): static
     /**
      * @throws Exception
      */
-    public function get(string $folderId = '', array $params = []): array
+    public function get(string $folderIdOrName = 'Inbox', array $params = []): array
     {
+        GraphQueryValidator::validate($params);
+
         $top = request('top', $this->top);
         $skip = request('skip', $this->skip);
 
-        if ($top === null) {
-            $top = 100;
+        if ($top === '') {
+            $top = 25;
         }
 
-        if ($skip === null) {
+        if ($skip === '') {
             $skip = 0;
         }
 
         if ($params === []) {
-            $params = http_build_query([
+            $params = [
                 '$top' => $top,
                 '$skip' => $skip,
                 '$count' => 'true',
-            ]);
-        } else {
-            $params = http_build_query($params);
+            ];
         }
 
-        $folder = $folderId == '' ? 'Inbox' : $folderId;
-
-        // get inbox from folders list
-        $folder = MsGraph::get("me/mailFolders?\$filter=startswith(displayName,'$folder')");
-
-        if (isset($folder['value'][0])) {
-            // folder id
-            $folderId = $folder['value'][0]['id'];
+        if ($this->isId($folderIdOrName)) {
+            $folder = MsGraph::emails()->folders()->find($folderIdOrName);
+        } else {
+            $folder = MsGraph::emails()->folders()->findByName($folderIdOrName);
+        }
 
-            // get messages from folderId
-            return MsGraph::get("me/mailFolders/$folderId/messages?".$params);
+        if ($folder !== []) {
+            return MsGraph::get("me/mailFolders/".$folder['id']."/messages?".http_build_query($params));
         } else {
-            throw new Exception('email folder not found');
+            throw new Exception('Email folder not found');
         }
     }
 
@@ -339,4 +337,10 @@ protected function prepareEmail(): array
 
         return $envelope;
     }
+
+    private function isId(string $value): bool
+    {
+        // IDs are long, contain uppercase/lowercase letters, numbers, hyphens, dots, underscores, and end with '='
+        return preg_match('/^[A-Za-z0-9\-_]+={0,2}$/', $value) && strlen($value) > 50;
+    }
 }

src/Resources/Emails/Folders.php

@@ -36,6 +36,12 @@ public function find(string $id): array
         return MsGraph::get('me/mailFolders/'.$id);
     }
 
+    public function findByName(string $name): array
+    {
+        $response = MsGraph::get("me/mailFolders?\$filter=startswith(displayName,'$name')");
+        return $response['value'][0] ?? [];
+    }
+
     public function store(array $data): array
     {
         EmailFolderStoreValidator::validate($data);