PHPackages                             headlessblog/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. headlessblog/sdk

ActiveLibrary[API Development](/categories/api)

headlessblog/sdk
================

PHP SDK for Headless.Blog API

00PHP

Since Jun 19Pushed todayCompare

[ Source](https://github.com/ClusterifyAI/php-headless-blog-sdk)[ Packagist](https://packagist.org/packages/headlessblog/sdk)[ RSS](/packages/headlessblog-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Headless Blog PHP SDK (v1.0.0)
==============================

[](#headless-blog-php-sdk-v100)

Welcome to the official Headless.Blog PHP Developer Guide. This SDK provides a high-performance, strictly typed, and completely database-agnostic interface for PHP applications, Laravel frameworks, decoupled monoliths, or any server-side integrations to consume blog content.

By utilizing this SDK, your backend or frontend application acts purely as a headless consumer. All complex business logic, multi-tenant security, taxonomy grouping, vector searches, and data aggregation are handled securely by the Headless.Blog backend.

---

Installation
------------

[](#installation)

Install the package via Composer. The SDK requires **PHP 8.2+** and uses Guzzle for robust HTTP requests.

```
composer require headlessblog/sdk
```

---

Initialization & Core Architecture
--------------------------------------

[](#initialization--core-architecture)

### 1. Strict Token Authentication

[](#1-strict-token-authentication)

The Headless API relies on strict API token authentication to isolate multi-tenant data. The SDK automatically manages this for you via the `Config` object.

```
use HeadlessBlog\Sdk\Config;
use HeadlessBlog\Sdk\Client;

// Initialize the Configuration with your active API key from the SaaS Dashboard
$config = new Config(
    apiKey: 'your_api_token_here',
    baseUrl: 'https://api.headless.blog/v1', // Optional, defaults to this URL
    timeout: 30                              // Optional, timeout in seconds
);

// Instantiate the SDK Client
$client = new Client($config);
```

### 2. High-Speed Hybrid Caching & CDN

[](#2-high-speed-hybrid-caching--cdn)

- **Image CDN Mapping**: The backend API automatically intercepts all responses and replaces relative database paths with fully qualified CDN URLs, providing automatic WebP compression.
- **Caching**: The backend utilizes Redis and Edge Delivery caching to ensure high performance.

---

Global Error Handling & Exceptions
--------------------------------------

[](#global-error-handling--exceptions)

All API errors throw specific Exceptions extending `HeadlessBlog\Sdk\Exception\HeadlessBlogException`. You should design your application to catch these gracefully.

### `BadRequestException` (HTTP 400)

[](#badrequestexception-http-400)

Thrown when query parameters or body payloads fail validation.

```
try {
    $client->posts->list(['limit' => 500]); // Exceeds max limit
} catch (\HeadlessBlog\Sdk\Exception\BadRequestException $e) {
    echo $e->getMessage();
    print_r($e->getDetails()); // Returns specific validation failures
}
```

### `UnauthorizedException` (HTTP 401 / 403)

[](#unauthorizedexception-http-401--403)

Thrown when the API token is completely missing, invalid, expired, or belongs to a disabled tenant.

### `RateLimitException` (HTTP 429)

[](#ratelimitexception-http-429)

Thrown when your client IP exceeds the configured sliding-window rate limit.

### `ServerException` (HTTP 500+)

[](#serverexception-http-500)

Thrown on catastrophic database or cache connection failures from the Headless.Blog servers.

---

Endpoint Reference Guide
------------------------

[](#endpoint-reference-guide)

All endpoints return parsed associative arrays. Below you will find the method signatures, parameters, and the exact response schemas.

### 1. Application Bootstrap & Navigation

[](#1-application-bootstrap--navigation)

Delivers all foundational categories, tags, and multi-dimensional taxonomies. Applications should call this once on launch or cache the result locally to build navigation menus.

**Method:**

```
$bootstrapData = $client->bootstrap->get();
```

**Response Schema:**

```
[
    'categories' => [
        [
            'id' => 1,
            'parentId' => null,
            'name' => 'Technology',
            'slug' => 'technology',
            'url_link' => 'https://...',
            'description' => 'Tech news',
            'imagePath' => 'https://cdn...',
            'position' => 0
        ]
    ],
    'tags' => [
        ['id' => 'uuid', 'name' => 'TypeScript', 'slug' => 'typescript', 'url_link' => 'https://...']
    ],
    'taxonomies' => [
        [
            'id' => 'uuid',
            'name' => 'Difficulty',
            'slug' => 'difficulty',
            'selectionType' => 'single',
            'isNavigation' => true,
            'visibleInPostTypeIds' => [1, 2],
            'terms' => [
                ['id' => 'uuid', 'name' => 'Easy', 'slug' => 'easy', 'colorCode' => '#00FF00']
            ]
        ]
    ],
    'postTypes' => [
        ['id' => 1, 'name' => 'Default', 'position' => 0, 'isDefault' => true, 'isDeletable' => false]
    ]
]
```

---

### 2. Website Settings

[](#2-website-settings)

Delivers general website settings. Call this to retrieve the base configuration like the website name, URLs, and AI feature toggles.

**Method:**

```
$settings = $client->settings->get();
```

**Response Schema:**

```
[
    'id' => 'uuid',
    'websiteName' => 'My Blog',
    'websiteBaseUrl' => 'https://myblog.com',
    'blogLandingPageUrl' => 'blog',
    'metaSeoKeywords' => 'blog, kitchen, travel',
    'highlightedCategoryId' => 5,
    'semanticSearchHeadlessApi' => true,
    'semanticSearchWebsite' => true
]
```

---

### 3. Consolidated Homepage Data

[](#3-consolidated-homepage-data)

Aggregates all homepage sections to build a full landing page in a single request, preventing UI waterfall loading.

**Method:**

```
$homeData = $client->home->get();
```

**Response Schema:**

```
[
    'section-hero'     => [ /* MobilePostSnippet array */ ],
    'section-recent'   => [ /* Array of 5 MobilePostSnippets */ ],
    'section-featured' => [ /* Array of 6 MobilePostSnippets */ ],
    'section-favorite' => [ /* Array of Curated Highlight MobilePostSnippets */ ]
]
```

---

### 4. Hybrid Search API

[](#4-hybrid-search-api)

Executes high-speed text search across published posts. Intelligently chooses between next-generation Semantic Vector Search and Classic Keyword Search based on dashboard settings.

**Method:**

```
// @param string $query Required search string
$results = $client->search->query('How to Bake Bread');
```

**Response Schema:**

```
[
    [
        'id' => 'uuid',
        'title' => 'How to Bake Bread',
        'slug' => 'how-to-bake-bread',
        'url_link' => 'https://...',
        'excerpt' => "A beginner's guide to baking.",
        'featuredImagePathThumbnail' => 'https://cdn.headless.blog/_next/image?url=...',
        'featuredImageDirectUrl' => 'https://cdn.headless.blog/...',
        'postTypeId' => 1,
        'contentType' => 'markdown',
        'categories' => [['id' => 1, 'name' => 'Recipes', 'slug' => 'recipes', 'url_link' => 'https://...']],
        'tags' => [['id' => 'uuid', 'name' => 'Baking', 'slug' => 'baking', 'url_link' => 'https://...']],
        'taxonomies' => [ /* Mapped Taxonomy Terms */ ]
    ]
]
```

---

### 5. Posts Index & Filtering

[](#5-posts-index--filtering)

Serves paginated lists of blog posts. Supports intersection filtering via an array of parameters.

**Method:**

```
// @param array $filters Optional key-value pairs for filtering
$postsData = $client->posts->list([
    'page' => 1,                  // optional, default: 1
    'limit' => 12,                // optional, default: 12, max: 50
    'category' => 'recipes',      // optional, category slug
    'tag' => 'baking',            // optional, tag slug
    'taxonomyGroup' => 'level',   // optional, requires taxonomyTerm
    'taxonomyTerm' => 'easy'      // optional, requires taxonomyGroup
]);
```

**Response Schema:**

```
[
    'pagination' => [
        'totalItems' => 42,
        'totalPages' => 4,
        'currentPage' => 1,
        'limit' => 12
    ],
    'posts' => [
        [
            'id' => 'uuid',
            'title' => 'Understanding Headless Architecture',
            'slug' => 'understanding-headless',
            'url_link' => 'https://...',
            'excerpt' => 'A brief summary.',
            'featuredImagePath' => 'https://cdn.headless.blog/...',
            'featuredImagePathThumbnail' => 'https://cdn.headless.blog/...',
            'featuredImageDirectUrl' => 'https://cdn.headless.blog/...',
            'featuredImageAlt' => 'Image Alt Text',
            'publishedAt' => '2026-06-08T12:00:00Z',
            'postTypeId' => 1,
            'contentType' => 'markdown',
            'categories' => [ /* MobileCategorySnippets */ ],
            'tags' => [ /* MobileTagSnippets */ ],
            'taxonomies' => [ /* Mapped Taxonomy Terms */ ],
            'author' => [
                'id' => 'uuid',
                'username' => 'admin',
                'displayName' => 'Admin User',
                'avatarUrl' => 'https://cdn.headless.blog/...'
            ]
        ]
    ]
]
```

---

### 6. Post Details

[](#6-post-details)

Fetches comprehensive details for a single blog post. Includes parsed HTML content, authors, SEO meta, and structured FAQ arrays.

**Methods:**

```
// @param string $id Lookup by post UUID
$post = $client->posts->get('uuid-of-post');

// @param string $slug Lookup by URL slug
$post = $client->posts->getBySlug('understanding-headless');
```

**Response Schema:**

```
[
    'id' => 'uuid',
    'title' => 'Understanding Headless Architecture',
    'slug' => 'understanding-headless',
    'url_link' => 'https://...',
    'content' => 'HTML content here with ',
    'excerpt' => 'A brief summary.',
    'featuredImagePath' => 'https://cdn.headless.blog/...',
    'featuredImagePathThumbnail' => 'https://cdn.headless.blog/...',
    'featuredImageDirectUrl' => 'https://cdn.headless.blog/...',
    'featuredImageAlt' => 'Image alt text',
    'metaSeoTitle' => 'SEO Title',
    'metaSeoDescription' => 'SEO Description',
    'contentFaq' => [
        ['question' => 'What is headless?', 'answer' => 'It is decoupled.']
    ],
    'metaSeoKeywords' => 'headless, architecture',
    'postTypeId' => 1,
    'contentType' => 'markdown',
    'categories' => [ /* Array of categories */ ],
    'tags' => [ /* Array of tags */ ],
    'taxonomies' => [ /* Filtered array of mapped Taxonomy Terms */ ],
    'author' => [ /* MobileAuthorSnippet */ ]
]
```

---

### 7. Comments Engine

[](#7-comments-engine)

Retrieves or submits comments for a specific post.

**Retrieve Comments:**

```
// @param string $id Post UUID
$comments = $client->posts->getComments('uuid-of-post');

// Returns an array of nested comment objects
```

**Submit a Comment:**Automatically assigned `pending` status for admin moderation.

```
// @param string $id Post UUID
// @param array  $data Comment Payload
$response = $client->posts->addComment('uuid-of-post', [
    'content'     => 'Great post! Thanks for sharing.',
    'authorName'  => 'Jane Doe',
    'authorEmail' => 'jane@example.com',
    'parentId'    => 'optional-uuid-to-reply-to-comment'
]);
```

---

### 8. Taxonomies & Metadata

[](#8-taxonomies--metadata)

The API exposes dedicated resources for querying precise metadata objects.

**Categories & Tags:**

```
$categories = $client->categories->list();
$category   = $client->categories->getBySlug('technology');

$tags = $client->tags->list();
$tag  = $client->tags->getBySlug('typescript');
```

**Taxonomies:**

```
$taxonomies = $client->taxonomies->list();
$group      = $client->taxonomies->getByGroupSlug('difficulty');
$term       = $client->taxonomies->getByTermSlug('difficulty', 'easy');

// Taxonomy Group Response Schema:
// [
//     'id' => 'uuid',
//     'name' => 'Difficulty',
//     'slug' => 'difficulty',
//     'selectionType' => 'single',
//     'isNavigation' => true,
//     'visibleInPostTypeIds' => [1, 2],
//     'terms' => [
//         ['id' => 'uuid', 'name' => 'Easy', 'slug' => 'easy', 'colorCode' => '#00FF00']
//     ]
// ]
```

**Post Types & Content Types:**

```
$postTypes = $client->postTypes->list();
// Returns: [['id' => 1, 'name' => 'Default', 'isDeletable' => false, 'isDefault' => true, 'position' => 0]]

$contentTypes = $client->contentTypes->list();
// Returns: [['id' => 'markdown', 'name' => 'Markdown'], ['id' => 'rich-text', 'name' => 'Rich Text']]
```

---

### 9. Static Pages

[](#9-static-pages)

Resolves SEO meta and dynamic layout configuration for static segments like `/about` or `/contact`.

**Method:**

```
// @param string $slug Page URL slug
$page = $client->pages->getBySlug('about');
```

**Response Schema:**

```
[
    'id' => 'uuid',
    'title' => 'About Us',
    'slug' => 'about',
    'content' => 'Page content...',
    'metaSeoTitle' => 'About Us | Headless.Blog',
    'metaSeoDescription' => 'Learn more about us.'
]
```

---

### 10. Newsletter

[](#10-newsletter)

Registers a subscriber to the tenant's mailing list.

**Method:**

```
// @param string $email Required email address
// @param string|null $name Optional name
$response = $client->newsletter->subscribe('user@example.com', 'Jane Doe');
```

---

### 11. Sitemap Generation

[](#11-sitemap-generation)

Dynamically generates standard sitemap data (URLs, last modification dates, priorities). Used to programmatically render dynamic `sitemap.xml` feeds.

**Method:**

```
$sitemapData = $client->sitemap->list();
```

**Response Schema:**

```
[
    [
        'url' => 'https://{your domain}/recipes/how-to-bake-bread',
        'lastModified' => '2026-06-08T12:00:00Z',
        'changeFrequency' => 'weekly',
        'priority' => 0.8
    ]
]
```

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/71940?v=4)[Clusterify](/maintainers/clusterify)[@clusterify](https://github.com/clusterify)

---

Top Contributors

[![boostmagento](https://avatars.githubusercontent.com/u/4080159?v=4)](https://github.com/boostmagento "boostmagento (3 commits)")

### Embed Badge

![Health badge](/badges/headlessblog-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/headlessblog-sdk/health.svg)](https://phpackages.com/packages/headlessblog-sdk)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.3M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[botman/driver-telegram

Telegram driver for BotMan

93452.6k6](/packages/botman-driver-telegram)[200mph/tnt-express-connect

TNT ExpressConnect (API) client

2228.2k](/packages/200mph-tnt-express-connect)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)