PHPackages johannschopplich/kirby-headless - 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. johannschopplich/kirby-headless ActiveKirby-plugin[API Development](/categories/api) johannschopplich/kirby-headless =============================== API-first toolkit for Kirby CMS 7.0.0(2w ago)4316.3k↓14.4%6MITPHPPHP >=8.3 Since Dec 28Pushed 2w ago3 watchersCompare [ Source](https://github.com/johannschopplich/kirby-headless)[ Packagist](https://packagist.org/packages/johannschopplich/kirby-headless)[ Docs](https://kirby.tools/docs/headless)[ Fund](https://paypal.me/jschopplich)[ RSS](/packages/johannschopplich-kirby-headless/feed)WikiDiscussions main Synced 2d ago READMEChangelog (10)Dependencies (5)Versions (77)Used By (0) [![Kirby Headless logo](./.github/favicon.svg)](./.github/favicon.svg)Kirby Headless ============== [](#kirby-headless) Bearer-authenticated KQL, UUID resolution in blocks and layouts, JSON templates, and an Express-style API builder for Kirby – everything you need to drive any frontend from Kirby. [KQL](https://kirby.tools/docs/headless/usage/kql) • [Field Methods](https://kirby.tools/docs/headless/usage/field-methods) • [JSON Templates](https://kirby.tools/docs/headless/usage/json-templates) • [API Builder](https://kirby.tools/docs/headless/advanced/api-builder) • [Authentication](https://kirby.tools/docs/headless/configuration/authentication) Note Want a ready-to-use headless-only project? Start from the [Kirby Headless Starter](https://github.com/johannschopplich/kirby-headless-starter). When to Use ----------- [](#when-to-use) I want to…UseQuery content from a frontend over HTTPKQL endpoint at `/api/kql`Lock the API behind a token instead of basic auth`kql.auth => 'bearer'` + `headless.token`Resolve UUIDs in blocks and layouts to real objects`$field->toResolvedBlocks()`Resolve permalinks in writer and text fields`$field->resolvePermalinks()`Return JSON straight from a templateJSON templates / `__template__` endpointCompose custom, authenticated API routes`Api::createHandler()` + middlewaresBuild navigation and language switchers in the frontendpage methods (`frontendUrl()`, `i18nMeta()`, …)Features -------- [](#features) ### 🔑 Bearer Token Authentication [](#-bearer-token-authentication) Protect the `/api/kql` endpoint and your own API routes with a bearer token, or fall back to Kirby's native API authentication. ``` // config.php return [ 'kql' => ['auth' => 'bearer'], 'headless' => ['token' => 'your-secret-token'] ]; ``` **[Read more →](https://kirby.tools/docs/headless/configuration/authentication)** ### 🧱 Block & Layout Resolution [](#-block--layout-resolution) Resolve UUIDs in blocks and layouts to complete file and page objects server-side, so your frontend consumes ready-to-use URLs and data. Configure which fields to resolve, or plug in custom resolvers. ``` $page->blocks()->toResolvedBlocks()->toArray(); $page->layout()->toResolvedLayouts()->toArray(); ``` **[Read more →](https://kirby.tools/docs/headless/usage/field-methods)** ### ⚡️ Enhanced KQL [](#️-enhanced-kql) A drop-in `/api/kql` endpoint that extends the official KQL plugin with bearer authentication, response caching, and multi-language support via a request header. ``` await fetch("https://example.com/api/kql", { method: "POST", headers: { Authorization: `Bearer ${token}` }, body: JSON.stringify({ query: "page('notes').children" }), }); ``` **[Read more →](https://kirby.tools/docs/headless/usage/kql)** ### 🗂 JSON Templates [](#-json-templates) Return JSON from your templates instead of HTML for full control over the response shape, with built-in `__template__` and `__sitemap__` endpoints. ``` // site/templates/about.php echo \Kirby\Data\Json::encode([ 'title' => $page->title()->value(), 'layout' => $page->layout()->toResolvedLayouts()->toArray() ]); ``` **[Read more →](https://kirby.tools/docs/headless/usage/json-templates)** ### 🍢 API Builder [](#-api-builder) Compose routes from middleware chains – Express-style. Reuse bearer auth, file and page resolution, or your own validators across routes. ``` use JohannSchopplich\Headless\Api\Api; use JohannSchopplich\Headless\Api\Middlewares; Api::createHandler( Middlewares::hasBearerToken(), fn (array $context, array $args) => Api::createResponse(200, [ 'message' => 'Hello World' ]) ); ``` **[Read more →](https://kirby.tools/docs/headless/advanced/api-builder)** ### 🧭 Page Methods [](#-page-methods) Helpers for headless frontends: frontend URLs, breadcrumb data, and multi-language metadata for navigation and language switchers. ``` $page->frontendUrl(); // URL on your frontend app $page->breadcrumbMeta(); // breadcrumb data for navigation $page->i18nMeta(); // language switcher metadata ``` **[Read more →](https://kirby.tools/docs/headless/usage/page-methods)** Requirements ------------ [](#requirements) - Kirby 5 - PHP 8.3+ Note Using Kirby 4? Install the [`v4` release](https://github.com/johannschopplich/kirby-headless/releases/tag/v4.0.2). Installation ------------ [](#installation) ### Composer (Recommended) [](#composer-recommended) ``` composer require johannschopplich/kirby-headless ``` ### Manual Installation [](#manual-installation) Download and copy this repository to `/site/plugins/kirby-headless`. License ------- [](#license) [MIT](./LICENSE) License © 2022-PRESENT [Johann Schopplich](https://github.com/johannschopplich) ### Health Score 61 — FairBetter than 98% of packages Maintenance96 Actively maintained with recent releases Popularity39 Limited adoption so far Community14 Small or concentrated contributor base Maturity76 Established project with proven stability Bus Factor1 Top contributor holds 99.1% 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. ### Release Activity Cadence Every ~17 days Recently: every ~95 days Total 75 Last Release 19d ago Major Versions 2.3.7 → 3.0.02024-02-12 3.3.0 → 4.0.02024-08-08 4.0.2 → 5.0.02025-05-27 5.0.3 → 6.0.02025-12-08 6.0.1 → 7.0.02026-06-14 ### Community Maintainers ![](https://www.gravatar.com/avatar/b9be5bf8dd3a36f63c00f92a115f1109567745fb3b068617341ffc8a90755d6c?d=identicon)[johannschopplich](/maintainers/johannschopplich) --- Top Contributors [![johannschopplich](https://avatars.githubusercontent.com/u/27850750?v=4)](https://github.com/johannschopplich "johannschopplich (229 commits)")[![AlexHupe](https://avatars.githubusercontent.com/u/6893843?v=4)](https://github.com/AlexHupe "AlexHupe (1 commits)")[![bnomei](https://avatars.githubusercontent.com/u/3265642?v=4)](https://github.com/bnomei "bnomei (1 commits)") --- Tags headlesskirby-cmskirby-pluginkirby-themekirby4kirby5headlesskirby ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/johannschopplich-kirby-headless/health.svg) ``` [![Health](https://phpackages.com/badges/johannschopplich-kirby-headless/health.svg)](https://phpackages.com/packages/johannschopplich-kirby-headless) ``` ### Alternatives [getkirby/cms The Kirby core 1.5k584.8k472](/packages/getkirby-cms)[getkirby/kql Kirby Query Language 15027.0k](/packages/getkirby-kql)[jcalderonzumba/gastonjs PhantomJS API based server for webpage automation 13111.2M73](/packages/jcalderonzumba-gastonjs)[medienbaecker/kirby-modules Easily add modules to your pages 895.5k1](/packages/medienbaecker-kirby-modules)[kontent-ai/delivery-sdk-php Kontent.ai Delivery SDK for PHP 4632.1k1](/packages/kontent-ai-delivery-sdk-php)[johannschopplich/kirby-content-translator DeepL & AI-powered content translation for Kirby CMS 2010.8k](/packages/johannschopplich-kirby-content-translator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)