feat(docs): Enhance README with navigation examples and customization details

Add sections for fetching navigation, asynchronous navigation requests, and customizing navigation requests in the README. Update example files to reflect changes in navigation item access and improve clarity on usage.

Author: fmontes

README.md

@@ -90,6 +90,32 @@ try {
 }
 ```
 
+### Fetching Navigation
+
+```php
+try {
+    // Create a navigation request
+    $navRequest = $client->createNavigationRequest('/about-us', 2);
+    
+    // Get the navigation
+    $nav = $client->getNavigation($navRequest);
+    
+    // Access navigation information
+    echo "Navigation title: " . $nav['title'] . "\n";
+    echo "Navigation URL: " . $nav['href'] . "\n";
+    
+    // Access children if available
+    if ($nav->hasChildren()) {
+        foreach ($nav->getChildren() as $child) {
+            echo "- " . $child['title'] . " (" . $child['href'] . ")\n";
+        }
+    }
+    
+} catch (\Exception $e) {
+    echo "Error: " . $e->getMessage() . "\n";
+}
+```
+
 ### Asynchronous Requests
 
 ```php
@@ -113,6 +139,34 @@ $promise->then(
 $promise->wait();
 ```
 
+### Asynchronous Navigation Requests
+
+```php
+// Create a navigation request
+$asyncNavRequest = $client->createNavigationRequest('/', 2);
+
+// Get the navigation asynchronously
+$promise = $client->getNavigationAsync($asyncNavRequest);
+
+// Add callbacks for success and failure
+$promise->then(
+    function ($nav) {
+        echo "Navigation title: " . $nav['title'] . "\n";
+        if ($nav->hasChildren()) {
+            foreach ($nav->getChildren() as $child) {
+                echo "- " . $child['title'] . "\n";
+            }
+        }
+    },
+    function (\Exception $e) {
+        echo "Error: " . $e->getMessage() . "\n";
+    }
+);
+
+// Wait for the promise to complete
+$promise->wait();
+```
+
 ## Advanced Usage
 
 ### Customizing Page Requests
@@ -143,6 +197,22 @@ $pageRequest = $pageRequest->withHostId('48190c8c-42c4-46af-8d1a-0cd5db894797');
 
 Note that each method returns a new instance with the updated value, so you need to reassign the result.
 
+### Customizing Navigation Requests
+
+The `NavigationRequest` class allows you to customize your navigation requests:
+
+```php
+// Create a navigation request with custom parameters
+$navRequest = $client->createNavigationRequest(
+    path: '/about-us',  // The root path to begin traversing
+    depth: 2,           // The depth of the folder tree to return (1-3)
+    languageId: 2       // The language ID for content (e.g., 2 for Spanish)
+);
+
+// Get the navigation with the custom parameters
+$nav = $client->getNavigation($navRequest);
+```
+
 ### Working with Page Components
 
 Once you have a page, you can access its components:
@@ -179,6 +249,43 @@ foreach ($page->containers as $containerId => $container) {
 }
 ```
 
+### Working with Navigation Items
+
+The `NavigationItem` class extends `AbstractModel` and provides array access to its properties:
+
+```php
+// Check if the navigation item is a folder
+if ($nav->isFolder()) {
+    echo "This is a folder\n";
+}
+
+// Check if the navigation item is a page
+if ($nav->isPage()) {
+    echo "This is a page\n";
+}
+
+// Access navigation properties using array access
+echo "Title: " . $nav['title'] . "\n";
+echo "URL: " . $nav['href'] . "\n";
+echo "Type: " . $nav['type'] . "\n";
+echo "Target: " . $nav['target'] . "\n"; // e.g., "_self", "_blank"
+echo "Order: " . $nav['order'] . "\n";
+
+// Recursively process navigation tree
+function processNavigation($navItem, $level = 0) {
+    $indent = str_repeat("  ", $level);
+    echo $indent . "- " . $navItem['title'] . " (" . $navItem['href'] . ")\n";
+    
+    if ($navItem->hasChildren()) {
+        foreach ($navItem->getChildren() as $child) {
+            processNavigation($child, $level + 1);
+        }
+    }
+}
+
+processNavigation($nav);
+```
+
 ## API Reference
 
 ### DotCMSClient
@@ -191,6 +298,9 @@ The main client for interacting with the dotCMS API.
 | `getPage` | Fetch a page synchronously | `PageRequest $request` |
 | `getPageAsync` | Fetch a page asynchronously | `PageRequest $request` |
 | `createPageRequest` | Create a new page request | `string $pagePath, string $format = 'json'` |
+| `getNavigation` | Fetch navigation items synchronously | `NavigationRequest $request` |
+| `getNavigationAsync` | Fetch navigation items asynchronously | `NavigationRequest $request` |
+| `createNavigationRequest` | Create a new navigation request | `string $path = '/', int $depth = 1, int $languageId = 1` |
 
 ### PageRequest
 
@@ -208,6 +318,19 @@ Represents a request to the dotCMS Page API.
 | `buildPath` | **(Internal)** Build the API path for the request | None |
 | `buildQueryParams` | **(Internal)** Build the query parameters for the request | None |
 
+### NavigationRequest
+
+Represents a request to the dotCMS Navigation API.
+
+| Method | Description | Parameters |
+|--------|-------------|------------|
+| `__construct` | Create a new navigation request | `string $path = '/', int $depth = 1, int $languageId = 1` |
+| `getPath` | Get the path | None |
+| `getDepth` | Get the depth | None |
+| `getLanguageId` | Get the language ID | None |
+| `buildPath` | **(Internal)** Build the API path for the request | None |
+| `buildQueryParams` | **(Internal)** Build the query parameters for the request | None |
+
 ### PageAsset
 
 Represents a complete page asset from dotCMS.
@@ -220,6 +343,30 @@ Represents a complete page asset from dotCMS.
 | `layout` | Layout | The Layout object |
 | `containers` | Array | Array of Container objects |
 
+### NavigationItem
+
+Represents a navigation item from the dotCMS Navigation API. Extends AbstractModel to provide array access to properties.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `code` | ?string | The code of the navigation item |
+| `folder` | ?string | The folder identifier |
+| `host` | string | The host identifier |
+| `languageId` | int | The language ID |
+| `href` | string | The URL of the navigation item |
+| `title` | string | The title of the navigation item |
+| `type` | string | The type of the navigation item (folder, htmlpage, etc.) |
+| `hash` | int | The hash of the navigation item |
+| `target` | string | The target attribute for links (_self, _blank, etc.) |
+| `order` | int | The order of the navigation item |
+
+| Method | Description | Return Type |
+|--------|-------------|-------------|
+| `isFolder` | Check if this navigation item is a folder | `bool` |
+| `isPage` | Check if this navigation item is a page | `bool` |
+| `hasChildren` | Check if this navigation item has children | `bool` |
+| `getChildren` | Get the children as NavigationItem objects | `?array` |
+
 ## Error Handling
 
 The SDK provides several exception classes for error handling:
@@ -252,7 +399,7 @@ try {
 
 ## Examples
 
-### Basic Example
+### Basic Page Example
 
 ```php
 <?php
@@ -282,6 +429,43 @@ echo "Page title: " . $page->page->title . "\n";
 echo "Page URL: " . $page->page->pageUrl . "\n";
 ```
 
+### Basic Navigation Example
+
+```php
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+use Dotcms\PhpSdk\Config\Config;
+use Dotcms\PhpSdk\DotCMSClient;
+
+// Create configuration
+$config = new Config(
+    host: 'https://demo.dotcms.com',
+    apiKey: 'YOUR_API_KEY'
+);
+
+// Create client
+$client = new DotCMSClient($config);
+
+// Create navigation request for the About Us section with depth=2
+$navRequest = $client->createNavigationRequest('/about-us', 2);
+
+// Get navigation
+$nav = $client->getNavigation($navRequest);
+
+// Display navigation information
+echo "Navigation title: " . $nav['title'] . "\n";
+
+// Display children if available
+if ($nav->hasChildren()) {
+    echo "Children:\n";
+    foreach ($nav->getChildren() as $child) {
+        echo "- " . $child['title'] . " (" . $child['href'] . ")\n";
+    }
+}
+```
+
 ### Integration with Symfony
 
 The SDK can be easily integrated with Symfony. See the `examples/dotcms-symfony` directory for a complete example.

examples/navigation_example.php

@@ -19,23 +19,23 @@
 echo "--------------------------------\n";
 $navRequest = $client->createNavigationRequest('/', 1);
 $nav = $client->getNavigation($navRequest);
-echo "Title: " . $nav->getTitle() . "\n";
-echo "URL: " . $nav->getHref() . "\n";
-echo "Type: " . $nav->getType() . "\n\n";
+echo "Title: " . $nav['title'] . "\n";
+echo "URL: " . $nav['href'] . "\n";
+echo "Type: " . $nav['type'] . "\n\n";
 
 // Example 2: Get navigation with children (depth=2)
 echo "Example 2: Navigation with children (depth=2)\n";
 echo "------------------------------------------\n";
 $navWithChildrenRequest = $client->createNavigationRequest('/about-us', 2);
 $navWithChildren = $client->getNavigation($navWithChildrenRequest);
-echo "Title: " . $navWithChildren->getTitle() . "\n";
-echo "URL: " . $navWithChildren->getHref() . "\n";
-echo "Type: " . $navWithChildren->getType() . "\n";
+echo "Title: " . $navWithChildren['title'] . "\n";
+echo "URL: " . $navWithChildren['href'] . "\n";
+echo "Type: " . $navWithChildren['type'] . "\n";
 
 if ($navWithChildren->hasChildren()) {
     echo "Children:\n";
     foreach ($navWithChildren->getChildren() as $child) {
-        echo "- " . $child->getTitle() . " (" . $child->getHref() . ")\n";
+        echo "- " . $child['title'] . " (" . $child['href'] . ")\n";
     }
 }
 echo "\n";
@@ -45,21 +45,21 @@
 echo "-------------------------------------------\n";
 $navSpanishRequest = $client->createNavigationRequest('/', 1, 2);
 $navSpanish = $client->getNavigation($navSpanishRequest);
-echo "Title: " . $navSpanish->getTitle() . "\n";
-echo "URL: " . $navSpanish->getHref() . "\n";
-echo "Language ID: " . $navSpanish->getLanguageId() . "\n\n";
+echo "Title: " . $navSpanish['title'] . "\n";
+echo "URL: " . $navSpanish['href'] . "\n";
+echo "Language ID: " . $navSpanish['languageId'] . "\n\n";
 
 // Example 4: Async navigation request
 echo "Example 4: Async navigation request\n";
 echo "--------------------------------\n";
 $asyncRequest = $client->createNavigationRequest('/about-us', 2);
 $client->getNavigationAsync($asyncRequest)->then(
     function ($nav) {
-        echo "Title: " . $nav->getTitle() . "\n";
+        echo "Title: " . $nav['title'] . "\n";
         if ($nav->hasChildren()) {
             echo "Children:\n";
             foreach ($nav->getChildren() as $child) {
-                echo "- " . $child->getTitle() . "\n";
+                echo "- " . $child['title'] . "\n";
             }
         }
     }