Skip to content

Commit 691a0d2

Browse files
fmontesfmontes
committed
feat(docs): Add comprehensive README for dotCMS PHP SDK
Introduce detailed documentation for the dotCMS PHP SDK: - Outline installation and configuration steps - Provide examples for basic and advanced usage - Include API reference and error handling guidelines - Highlight contributing and development setup instructions
1 parent 17d821f commit 691a0d2

1 file changed

Lines changed: 318 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
# dotCMS PHP SDK
2+
3+
A PHP library designed to simplify interaction with the dotCMS Page API. This SDK provides a clean, object-oriented interface for retrieving and working with dotCMS pages and their components.
4+
5+
## Requirements
6+
7+
- PHP 8.2 or higher
8+
- Composer
9+
10+
## Installation
11+
12+
Install the SDK using Composer:
13+
14+
```bash
15+
composer require dotcms/php-sdk
16+
```
17+
18+
## Configuration
19+
20+
The SDK requires configuration to connect to your dotCMS instance:
21+
22+
```php
23+
use Dotcms\PhpSdk\Config\Config;
24+
use Dotcms\PhpSdk\Config\LogLevel;
25+
26+
// Create a configuration for the client
27+
$config = new Config(
28+
host: 'https://your-dotcms-instance.com',
29+
apiKey: 'YOUR_API_KEY',
30+
clientOptions: [
31+
'timeout' => 30
32+
],
33+
logConfig: [
34+
'level' => LogLevel::INFO,
35+
'console' => true, // Output logs to console
36+
]
37+
);
38+
```
39+
40+
### Configuration Options
41+
42+
#### Required Parameters
43+
44+
- `host`: Your dotCMS instance URL
45+
- `apiKey`: Your dotCMS API key
46+
47+
#### Optional Parameters
48+
49+
- `clientOptions`: Guzzle HTTP client options
50+
- `headers`: Custom HTTP headers
51+
- `verify`: SSL verification (boolean)
52+
- `timeout`: Request timeout in seconds
53+
- `connect_timeout`: Connection timeout in seconds
54+
- `http_errors`: Whether to throw exceptions for HTTP errors
55+
- `allow_redirects`: Whether to follow redirects
56+
57+
- `logConfig`: Logging configuration
58+
- `level`: Log level (DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY)
59+
- `console`: Whether to output logs to console
60+
- `handlers`: Array of custom Monolog handlers
61+
62+
## Basic Usage
63+
64+
### Creating a Client
65+
66+
```php
67+
use Dotcms\PhpSdk\DotCMSClient;
68+
69+
// Create the dotCMS client
70+
$client = new DotCMSClient($config);
71+
```
72+
73+
### Fetching a Page
74+
75+
```php
76+
try {
77+
// Create a page request for a specific page
78+
$pageRequest = $client->createPageRequest('/', 'json');
79+
80+
// Get the page
81+
$page = $client->getPage($pageRequest);
82+
83+
// Access page information
84+
echo "Page title: " . $page->page->title . "\n";
85+
echo "Page URL: " . $page->page->pageUrl . "\n";
86+
echo "Template name: " . $page->template->title . "\n";
87+
88+
} catch (\Exception $e) {
89+
echo "Error: " . $e->getMessage() . "\n";
90+
}
91+
```
92+
93+
### Asynchronous Requests
94+
95+
```php
96+
// Create a page request
97+
$asyncPageRequest = $client->createPageRequest('/', 'json');
98+
99+
// Get the page asynchronously
100+
$promise = $client->getPageAsync($asyncPageRequest);
101+
102+
// Add callbacks for success and failure
103+
$promise->then(
104+
function ($asyncPage) {
105+
echo "Async page title: " . $asyncPage->page->title . "\n";
106+
},
107+
function (\Exception $e) {
108+
echo "Error: " . $e->getMessage() . "\n";
109+
}
110+
);
111+
112+
// Wait for the promise to complete
113+
$promise->wait();
114+
```
115+
116+
## Advanced Usage
117+
118+
### Customizing Page Requests
119+
120+
The `PageRequest` class provides several methods to customize your page requests:
121+
122+
```php
123+
$pageRequest = $client->createPageRequest('/about-us', 'json');
124+
125+
// Set the language ID for the request
126+
$pageRequest = $pageRequest->withLanguageId(1);
127+
128+
// Set the mode (LIVE, WORKING, EDIT_MODE)
129+
$pageRequest = $pageRequest->withMode('WORKING');
130+
131+
// Set the depth of the content to retrieve (0-3)
132+
$pageRequest = $pageRequest->withDepth(2);
133+
134+
// Set personalization options
135+
$pageRequest = $pageRequest->withPersonaId('persona_id');
136+
137+
// Set whether to fire rules
138+
$pageRequest = $pageRequest->withFireRules(true);
139+
140+
// Set the host ID (Site ID)
141+
$pageRequest = $pageRequest->withHostId('48190c8c-42c4-46af-8d1a-0cd5db894797');
142+
```
143+
144+
Note that each method returns a new instance with the updated value, so you need to reassign the result.
145+
146+
### Working with Page Components
147+
148+
Once you have a page, you can access its components:
149+
150+
```php
151+
// Access site information
152+
echo "Site hostname: " . $page->site->hostname . "\n";
153+
154+
// Access template information
155+
echo "Template title: " . $page->template->title . "\n";
156+
157+
// Access layout information
158+
echo "Layout header: " . $page->layout->header . "\n";
159+
160+
// Access containers and contentlets
161+
foreach ($page->containers as $containerId => $container) {
162+
echo "Container ID: " . $containerId . "\n";
163+
164+
if (!empty($container->contentlets)) {
165+
foreach ($container->contentlets as $uuid => $contentletArray) {
166+
foreach ($contentletArray as $contentlet) {
167+
echo "Contentlet type: " . $contentlet->contentType . "\n";
168+
echo "Contentlet title: " . ($contentlet->title ?? 'N/A') . "\n";
169+
170+
// Access additional fields using array access
171+
foreach ($contentlet as $fieldName => $fieldValue) {
172+
if (is_scalar($fieldValue)) {
173+
echo "$fieldName: $fieldValue\n";
174+
}
175+
}
176+
}
177+
}
178+
}
179+
}
180+
```
181+
182+
## API Reference
183+
184+
### DotCMSClient
185+
186+
The main client for interacting with the dotCMS API.
187+
188+
- `__construct(Config $config)`: Create a new client instance
189+
- `getPage(PageRequest $request)`: Fetch a page synchronously
190+
- `getPageAsync(PageRequest $request)`: Fetch a page asynchronously
191+
- `createPageRequest(string $pagePath, string $format = 'json')`: Create a new page request
192+
- `getConfig()`: Get the client configuration
193+
- `getHttpClient()`: Get the HTTP client
194+
- `getPageService()`: Get the page service
195+
196+
### PageRequest
197+
198+
Represents a request to the dotCMS Page API.
199+
200+
- `__construct(string $pagePath, string $format = 'json')`: Create a new page request
201+
- `withLanguageId(int $languageId)`: Set the language ID for the request
202+
- `withMode(string $mode)`: Set the mode (LIVE, WORKING, EDIT_MODE)
203+
- `withDepth(int $depth)`: Set the depth of the content to retrieve (0-3)
204+
- `withPersonaId(string $personaId)`: Set the persona ID for personalization
205+
- `withHostId(string $hostId)`: Set the host ID (Site ID)
206+
- `withFireRules(bool $fireRules)`: Set whether to fire rules
207+
- `buildPath()`: Build the API path for the request
208+
- `buildQueryParams()`: Build the query parameters for the request
209+
210+
### PageAsset
211+
212+
Represents a complete page asset from dotCMS.
213+
214+
- `page`: The Page object
215+
- `site`: The Site object
216+
- `template`: The Template object
217+
- `layout`: The Layout object
218+
- `containers`: Array of Container objects
219+
- `isGenerated()`: Check if the page is generated
220+
221+
## Error Handling
222+
223+
The SDK provides several exception classes for error handling:
224+
225+
- `DotCMSException`: Base exception class for all SDK exceptions
226+
- `ConfigException`: Thrown when there's an issue with the configuration
227+
- `HttpException`: Thrown when there's an HTTP error
228+
- `ResponseException`: Thrown when there's an issue with the response
229+
230+
Example error handling:
231+
232+
```php
233+
try {
234+
$page = $client->getPage($pageRequest);
235+
} catch (ConfigException $e) {
236+
echo "Configuration error: " . $e->getMessage() . "\n";
237+
} catch (HttpException $e) {
238+
echo "HTTP error: " . $e->getMessage() . "\n";
239+
echo "Status code: " . $e->getStatusCode() . "\n";
240+
} catch (ResponseException $e) {
241+
echo "Response error: " . $e->getMessage() . "\n";
242+
} catch (DotCMSException $e) {
243+
echo "dotCMS error: " . $e->getMessage() . "\n";
244+
} catch (\Exception $e) {
245+
echo "General error: " . $e->getMessage() . "\n";
246+
}
247+
```
248+
249+
## Examples
250+
251+
### Basic Example
252+
253+
```php
254+
<?php
255+
256+
require_once __DIR__ . '/vendor/autoload.php';
257+
258+
use Dotcms\PhpSdk\Config\Config;
259+
use Dotcms\PhpSdk\DotCMSClient;
260+
261+
// Create configuration
262+
$config = new Config(
263+
host: 'https://demo.dotcms.com',
264+
apiKey: 'YOUR_API_KEY'
265+
);
266+
267+
// Create client
268+
$client = new DotCMSClient($config);
269+
270+
// Create page request
271+
$pageRequest = $client->createPageRequest('/', 'json');
272+
273+
// Get page
274+
$page = $client->getPage($pageRequest);
275+
276+
// Display page information
277+
echo "Page title: " . $page->page->title . "\n";
278+
echo "Page URL: " . $page->page->pageUrl . "\n";
279+
```
280+
281+
### Integration with Symfony
282+
283+
The SDK can be easily integrated with Symfony. See the `examples/dotcms-symfony` directory for a complete example.
284+
285+
## Contributing
286+
287+
Contributions are welcome! Please feel free to submit a Pull Request.
288+
289+
### Development Setup
290+
291+
1. Clone the repository
292+
2. Install dependencies: `composer install`
293+
3. Run tests: `composer test`
294+
295+
### Coding Standards
296+
297+
The project uses PHP-CS-Fixer for code style. Run the following commands:
298+
299+
- Check code style: `composer cs-check`
300+
- Fix code style: `composer cs-fix`
301+
302+
### Static Analysis
303+
304+
The project uses PHPStan for static analysis:
305+
306+
```bash
307+
composer phpstan
308+
```
309+
310+
### Running All Checks
311+
312+
```bash
313+
composer check
314+
```
315+
316+
## License
317+
318+
This project is licensed under the MIT License - see the LICENSE file for details.

0 commit comments

Comments
 (0)