https://github.com/bnomei/kirby-api-pages
Virtual Pages from API Endpoints
https://github.com/bnomei/kirby-api-pages
api auth content graphql headless kirby kirby-4 kirby-5 kirby-cms kirby-plugin pages panel performance rest token virtual
Last synced: 8 months ago
JSON representation
Virtual Pages from API Endpoints
- Host: GitHub
- URL: https://github.com/bnomei/kirby-api-pages
- Owner: bnomei
- License: mit
- Created: 2025-02-13T14:51:53.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-02-13T15:11:10.000Z (8 months ago)
- Last Synced: 2025-02-13T15:49:24.273Z (8 months ago)
- Topics: api, auth, content, graphql, headless, kirby, kirby-4, kirby-5, kirby-cms, kirby-plugin, pages, panel, performance, rest, token, virtual
- Language: PHP
- Homepage:
- Size: 0 Bytes
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Kirby API-Pages
[](https://getkirby.com)
[](https://codeclimate.com/github/bnomei/kirby-api-pages)
[](https://codeclimate.com/github/bnomei/kirby-api-pages/issues)
[](https://discordapp.com/users/bnomei)
[](https://www.buymeacoffee.com/bnomei)
Virtual Pages from APIs
## Installation
- unzip [master.zip](https://github.com/bnomei/kirby-api-pages/archive/master.zip) as folder `site/plugins/kirby-api-pages` or
- `git submodule add https://github.com/bnomei/kirby-api-pages.git site/plugins/kirby-api-pages` or
- `composer require bnomei/kirby-api-pages`
## Usage
You can find these examples in the tests of this repository.
### Records definition via Blueprint
**site/models/cats.php**
```php
class CatsPage extends \Bnomei\APIRecordsPage {}
```
**site/blueprints/cat.yml**
```yml
title: Cat
fields:
country:
type: text
origin:
type: text
coat:
type: text
pattern:
type: text
```
**site/blueprints/cats.yml**
```yml
title: Cats
records:
url: https://catfact.ninja/breeds
query: data.sortBy("coat", "desc")
template: cat
# model: cat
# expire: 60
map:
title: breed
# omit or use * to select all
# content: *
# select a few by path
content:
country: country
origin: origin
coat: coat
pattern: pattern
sections:
catfacts:
label: Virtual Pages from CatFacts API
type: pages
template: cat
```
### Records definition via Config
**site/blueprints/rickandmorty.yml**
**site/blueprints/alien.yml**
**site/blueprints/human.yml**
**site/models/rickandmorty.php**
```php
class RickandmortyPage extends \Bnomei\APIRecordsPage {}
```
**site/config/config.php**
```php
[
'rickandmorty' => [ // site/models/rickandmorty.php & site/blueprints/pages/rickandmorty.yml
'url' => 'https://rickandmortyapi.com/graphql', // string or closure
'params' => [
'headers' => function (\Bnomei\APIRecords $records) {
// you could add Basic/Bearer Auth within this closure if you needed
// or retrieve environment variable with `env()` and use them here
return [
'Content-Type: application/json',
];
},
'method' => 'POST', // defaults to GET else provide a string or closure
'data' => json_encode(['query' => '{ characters() { results { name status species }}}']), // string or closure
],
'query' => 'data.characters.results', // {"data: [...]}
'map' => [
// kirby <=> json
'title' => 'name',
'uuid' => fn ($i) => md5($i['name']),
'template' => fn ($i) => strtolower($i['species']), // site/blueprints/pages/alien.yml || human.yml
'content' => [
'species' => 'species',
'hstatus' => 'status', // status is reserved by kirby
],
],
],
],
// other options ...
];
```
### Records definition via Page Model
**site/blueprints/secret.yml**
**site/blueprints/secrets.yml**
**site/models/secrets.php**
```php
class SecretsPage extends \Bnomei\APIRecordsPage {
public function recordsConfig(): array
{
return [
'url' => 'https://example.api/secrets', // does not exist
'params' => [
'headers' => [
'Content-Type: application/json',
'Authorization: Bearer MY_BEARER_TOKEN',
],
'method' => 'POST',
'data' => json_encode([
'query' => $this->myquery()->value(),
]),
],
'query' => 'data.whispers',
'template' => 'secret',
'map' => [
// kirby <=> json
'title' => 'item.name',
'content' => [
'description' => 'item.desc',
'uuid' => 'id',
],
],
];
}
}
```
## Settings
| bnomei.api-pages. | Default | Description |
|-------------------|---------------|-------------------------------------------------------------------------------|
| expire | `60` | Cache expire duration in minutes |
| exception | `fn($remote)` | Exception handler for non 2xx status codes |
| records | `[]` | Custom config arrays for your virtual Pages (alternative to Blueprint config) |
## Disclaimer
This plugin is provided "as is" with no guarantee. You can use it at your own risk and always test it before using it in a production environment. If you find any issues, please [create a new issue](https://github.com/bnomei/kirby-api-pages/issues/new).
## License
[MIT](https://opensource.org/licenses/MIT)
It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.