Skip to content

Commit 161cfd8

Browse files
fmontesfmontes
committed
feat(navigation): Implement navigation API client and examples
Add NavigationService, NavigationRequest, and NavigationItem classes to interact with the dotCMS Navigation API. Include a new example file demonstrating usage for fetching navigation items, including top-level navigation, navigation with children, and asynchronous requests.
1 parent 0bb15db commit 161cfd8

5 files changed

Lines changed: 603 additions & 0 deletions

File tree

‎examples/navigation_example.php‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<?php
2+
3+
require_once __DIR__ . '/../vendor/autoload.php';
4+
5+
use Dotcms\PhpSdk\Config\Config;
6+
use Dotcms\PhpSdk\DotCMSClient;
7+
8+
// Create a configuration
9+
$config = new Config(
10+
'https://demo.dotcms.com', // host
11+
'your-api-key-here' // apiKey - Replace with your actual API key if needed
12+
);
13+
14+
// Create a client
15+
$client = new DotCMSClient($config);
16+
17+
// Example 1: Get top-level navigation
18+
echo "Example 1: Top-level navigation\n";
19+
echo "--------------------------------\n";
20+
$navRequest = $client->createNavigationRequest('/', 1);
21+
$nav = $client->getNavigation($navRequest);
22+
echo "Title: " . $nav->getTitle() . "\n";
23+
echo "URL: " . $nav->getHref() . "\n";
24+
echo "Type: " . $nav->getType() . "\n\n";
25+
26+
// Example 2: Get navigation with children (depth=2)
27+
echo "Example 2: Navigation with children (depth=2)\n";
28+
echo "------------------------------------------\n";
29+
$navWithChildrenRequest = $client->createNavigationRequest('/about-us', 2);
30+
$navWithChildren = $client->getNavigation($navWithChildrenRequest);
31+
echo "Title: " . $navWithChildren->getTitle() . "\n";
32+
echo "URL: " . $navWithChildren->getHref() . "\n";
33+
echo "Type: " . $navWithChildren->getType() . "\n";
34+
35+
if ($navWithChildren->hasChildren()) {
36+
echo "Children:\n";
37+
foreach ($navWithChildren->getChildren() as $child) {
38+
echo "- " . $child->getTitle() . " (" . $child->getHref() . ")\n";
39+
}
40+
}
41+
echo "\n";
42+
43+
// Example 3: Get navigation in a different language
44+
echo "Example 3: Navigation in Spanish (languageId=2)\n";
45+
echo "-------------------------------------------\n";
46+
$navSpanishRequest = $client->createNavigationRequest('/', 1, 2);
47+
$navSpanish = $client->getNavigation($navSpanishRequest);
48+
echo "Title: " . $navSpanish->getTitle() . "\n";
49+
echo "URL: " . $navSpanish->getHref() . "\n";
50+
echo "Language ID: " . $navSpanish->getLanguageId() . "\n\n";
51+
52+
// Example 4: Async navigation request
53+
echo "Example 4: Async navigation request\n";
54+
echo "--------------------------------\n";
55+
$asyncRequest = $client->createNavigationRequest('/about-us', 2);
56+
$client->getNavigationAsync($asyncRequest)->then(
57+
function ($nav) {
58+
echo "Title: " . $nav->getTitle() . "\n";
59+
if ($nav->hasChildren()) {
60+
echo "Children:\n";
61+
foreach ($nav->getChildren() as $child) {
62+
echo "- " . $child->getTitle() . "\n";
63+
}
64+
}
65+
}
66+
)->wait();

‎src/DotCMSClient.php‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,11 @@
66

77
use Dotcms\PhpSdk\Config\Config;
88
use Dotcms\PhpSdk\Http\HttpClient;
9+
use Dotcms\PhpSdk\Model\NavigationItem;
910
use Dotcms\PhpSdk\Model\PageAsset;
11+
use Dotcms\PhpSdk\Request\NavigationRequest;
1012
use Dotcms\PhpSdk\Request\PageRequest;
13+
use Dotcms\PhpSdk\Service\NavigationService;
1114
use Dotcms\PhpSdk\Service\PageService;
1215
use GuzzleHttp\Promise\PromiseInterface;
1316

@@ -20,6 +23,8 @@ class DotCMSClient
2023

2124
private readonly PageService $pageService;
2225

26+
private readonly NavigationService $navigationService;
27+
2328
/**
2429
* Create a new DotCMSClient instance
2530
*
@@ -29,6 +34,7 @@ public function __construct(Config $config)
2934
{
3035
$this->httpClient = new HttpClient($config);
3136
$this->pageService = new PageService($this->httpClient);
37+
$this->navigationService = new NavigationService($this->httpClient);
3238
}
3339

3440
/**
@@ -64,4 +70,39 @@ public function createPageRequest(string $pagePath, string $format = 'json'): Pa
6470
{
6571
return new PageRequest($pagePath, $format);
6672
}
73+
74+
/**
75+
* Fetch navigation items from dotCMS
76+
*
77+
* @param NavigationRequest $request The navigation request
78+
* @return NavigationItem The navigation item with optional children
79+
*/
80+
public function getNavigation(NavigationRequest $request): NavigationItem
81+
{
82+
return $this->navigationService->getNavigation($request);
83+
}
84+
85+
/**
86+
* Fetch navigation items from dotCMS asynchronously
87+
*
88+
* @param NavigationRequest $request The navigation request
89+
* @return PromiseInterface A promise that resolves to a NavigationItem
90+
*/
91+
public function getNavigationAsync(NavigationRequest $request): PromiseInterface
92+
{
93+
return $this->navigationService->getNavigationAsync($request);
94+
}
95+
96+
/**
97+
* Create a new navigation request
98+
*
99+
* @param string $path The root path to begin traversing the folder tree
100+
* @param int $depth The depth of the folder tree to return
101+
* @param int $languageId The language ID of content to return
102+
* @return NavigationRequest The navigation request
103+
*/
104+
public function createNavigationRequest(string $path = '/', int $depth = 1, int $languageId = 1): NavigationRequest
105+
{
106+
return new NavigationRequest($path, $depth, $languageId);
107+
}
67108
}

‎src/Model/NavigationItem.php‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Dotcms\PhpSdk\Model;
6+
7+
/**
8+
* Class NavigationItem
9+
*
10+
* Represents a navigation item from the dotCMS Navigation API.
11+
*
12+
* @package Dotcms\PhpSdk\Model
13+
*/
14+
class NavigationItem extends AbstractModel
15+
{
16+
/**
17+
* @var NavigationItem[]|null Array of child navigation items
18+
*/
19+
private ?array $childrenItems = null;
20+
21+
/**
22+
* @param string|null $code The code of the navigation item
23+
* @param string|null $folder The folder identifier
24+
* @param string $host The host identifier
25+
* @param int $languageId The language ID
26+
* @param string $href The URL of the navigation item
27+
* @param string $title The title of the navigation item
28+
* @param string $type The type of the navigation item (folder, htmlpage, etc.)
29+
* @param int $hash The hash of the navigation item
30+
* @param string $target The target attribute for links (_self, _blank, etc.)
31+
* @param int $order The order of the navigation item
32+
* @param array|null $children Array of child navigation items data
33+
*/
34+
public function __construct(
35+
private readonly ?string $code,
36+
private readonly ?string $folder,
37+
private readonly string $host,
38+
private readonly int $languageId,
39+
private readonly string $href,
40+
private readonly string $title,
41+
private readonly string $type,
42+
private readonly int $hash,
43+
private readonly string $target,
44+
private readonly int $order,
45+
private readonly ?array $children = null
46+
) {
47+
// Map children to NavigationItem objects if they exist
48+
if ($this->children !== null) {
49+
$this->childrenItems = array_map(
50+
fn($child) => new self(
51+
$child['code'] ?? null,
52+
$child['folder'] ?? null,
53+
$child['host'],
54+
$child['languageId'],
55+
$child['href'],
56+
$child['title'],
57+
$child['type'],
58+
$child['hash'],
59+
$child['target'],
60+
$child['order'],
61+
$child['children'] ?? null
62+
),
63+
$this->children
64+
);
65+
}
66+
}
67+
68+
/**
69+
* Get the code
70+
*
71+
* @return string|null
72+
*/
73+
public function getCode(): ?string
74+
{
75+
return $this->code;
76+
}
77+
78+
/**
79+
* Get the folder identifier
80+
*
81+
* @return string|null
82+
*/
83+
public function getFolder(): ?string
84+
{
85+
return $this->folder;
86+
}
87+
88+
/**
89+
* Get the host identifier
90+
*
91+
* @return string
92+
*/
93+
public function getHost(): string
94+
{
95+
return $this->host;
96+
}
97+
98+
/**
99+
* Get the language ID
100+
*
101+
* @return int
102+
*/
103+
public function getLanguageId(): int
104+
{
105+
return $this->languageId;
106+
}
107+
108+
/**
109+
* Get the URL
110+
*
111+
* @return string
112+
*/
113+
public function getHref(): string
114+
{
115+
return $this->href;
116+
}
117+
118+
/**
119+
* Get the title
120+
*
121+
* @return string
122+
*/
123+
public function getTitle(): string
124+
{
125+
return $this->title;
126+
}
127+
128+
/**
129+
* Get the type
130+
*
131+
* @return string
132+
*/
133+
public function getType(): string
134+
{
135+
return $this->type;
136+
}
137+
138+
/**
139+
* Get the hash
140+
*
141+
* @return int
142+
*/
143+
public function getHash(): int
144+
{
145+
return $this->hash;
146+
}
147+
148+
/**
149+
* Get the target
150+
*
151+
* @return string
152+
*/
153+
public function getTarget(): string
154+
{
155+
return $this->target;
156+
}
157+
158+
/**
159+
* Get the order
160+
*
161+
* @return int
162+
*/
163+
public function getOrder(): int
164+
{
165+
return $this->order;
166+
}
167+
168+
/**
169+
* Get the raw children data
170+
*
171+
* @return array|null
172+
*/
173+
public function getRawChildren(): ?array
174+
{
175+
return $this->children;
176+
}
177+
178+
/**
179+
* Get the children as NavigationItem objects
180+
*
181+
* @return NavigationItem[]|null
182+
*/
183+
public function getChildren(): ?array
184+
{
185+
return $this->childrenItems;
186+
}
187+
188+
/**
189+
* Check if this navigation item is a folder
190+
*
191+
* @return bool
192+
*/
193+
public function isFolder(): bool
194+
{
195+
return $this->type === 'folder';
196+
}
197+
198+
/**
199+
* Check if this navigation item is a page
200+
*
201+
* @return bool
202+
*/
203+
public function isPage(): bool
204+
{
205+
return $this->type === 'htmlpage';
206+
}
207+
208+
/**
209+
* Check if this navigation item has children
210+
*
211+
* @return bool
212+
*/
213+
public function hasChildren(): bool
214+
{
215+
return $this->childrenItems !== null && count($this->childrenItems) > 0;
216+
}
217+
218+
/**
219+
* Specify data which should be serialized to JSON
220+
*
221+
* @return array<string, mixed>
222+
*/
223+
public function jsonSerialize(): array
224+
{
225+
return [
226+
'code' => $this->code,
227+
'folder' => $this->folder,
228+
'host' => $this->host,
229+
'languageId' => $this->languageId,
230+
'href' => $this->href,
231+
'title' => $this->title,
232+
'type' => $this->type,
233+
'hash' => $this->hash,
234+
'target' => $this->target,
235+
'order' => $this->order,
236+
'children' => $this->childrenItems
237+
];
238+
}
239+
}

0 commit comments

Comments
 (0)