README

Virtual Pages from APIs

Installation

unzip 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

class CatsPage extends \Bnomei\APIRecordsPage {}

site/blueprints/cat.yml

title: Cat
fields:
    country:
        type: text
    origin:
        type: text
    coat:
        type: text
    pattern:
        type: text

site/blueprints/cats.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

class RickandmortyPage extends \Bnomei\APIRecordsPage {}

site/config/config.php

<?php

return [
    'bnomei.api-pages.records' => [
        '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

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

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.

License

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.

bnomei / kirby-api-pages

Maintainers

Details