[Download](https://github.com/getkirby/kql/releases) and copy this repository to `/site/plugins/kql` of your Kirby installation.
### Composer
```bash
composer require getkirby/kql
```
## Documentation
### API Endpoint
KQL adds a new `query` API endpoint to your Kirby API (i.e. `yoursite.com/api/query`). This endpoint [requires authentication](https://getkirby.com/docs/guide/api/authentication).
You can switch off authentication in your config at your own risk:
```php
return [
'kql' => [
'auth' => false
]
];
```
### Sending POST Requests
You can use any HTTP request library in your language of choice to make regular POST requests to your `/api/query` endpoint. In this example, we are using [the `fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and JavaScript to retrieve data from our Kirby installation.
KQL becomes really powerful by its flexible way to control the result set with the select option.
#### Select Single Properties and Fields
To include a property or field in your results, list them as an array. Check out our [reference for available properties](https://getkirby.com/docs/reference) for pages, users, files, etc.
Whenever you query a collection (pages, files, users, roles, languages) you can limit the resultset and also paginate through entries. You've probably already seen the pagination object in the results above. It is included in all results for collections, even if you didn't specify any pagination settings.
#### `limit`
You can specify a custom limit with the limit option. The default limit for collections is 100 entries.
KQL is very strict with allowed methods by default. Custom page methods, file methods or model methods are not allowed to make sure you don't miss an important security issue by accident. You can allow additional methods though.
#### Allow List
The most straight forward way is to define allowed methods in your config.
```php
return [
'kql' => [
'methods' => [
'allowed' => [
'MyCustomPage::cover'
]
]
]
];
```
#### DocBlock Comment
You can also add a comment to your methods' doc blocks to allow them:
You can block individual class methods that would normally be accessible by listing them in your config:
```php
return [
'kql' => [
'methods' => [
'blocked' => [
'Kirby\Cms\Page::url'
]
]
]
];
```
### Blocking Classes
Sometimes you might want to reduce access to various parts of the system. This can be done by blocking individual methods (see above) or by blocking entire classes.
```php
return [
'kql' => [
'classes' => [
'blocked' => [
'Kirby\Cms\User'
]
]
]
];
```
Now, access to any user is blocked.
### Custom Classes and Interceptors
If you want to add support for a custom class or a class in Kirby's source that is not supported yet, you can list your own interceptors in your config
```php
return [
'kql' => [
'interceptors' => [
'Kirby\Cms\System' => 'SystemInterceptor'
]
]
];
```
You can put the class for such a custom interceptor in a plugin for example.
```php
class SystemInterceptor extends Kirby\Kql\Interceptors\Interceptor
{
public const CLASS_ALIAS = 'system';
protected $toArray = [
'isInstallable',
];
public function allowedMethods(): array
{
return [
'isInstallable',
];
}
}
```
Interceptor classes are pretty straight forward. With the `CLASS_ALIAS` you can give objects with that class a short name for KQL queries. The `$toArray` property lists all methods that should be rendered if you don't run a subquery. I.e. in this case `kirby.system` would render an array with the `isInstallable` value.
The `allowedMethods` method must return an array of all methods that can be access for this object. In addition to that you can also create your own custom methods in an interceptor that will then become available in KQL.
```php
class SystemInterceptor extends Kirby\Kql\Interceptors\Interceptor
{
...
public function isReady()
{
return 'yes it is!';
}
}
```
This custom method can now be used with `kirby.system.isReady` in KQL and will return `yes it is!`
### Unintercepted Classes
If you want to fully allow access to an entire class without putting an interceptor in between, you can add the class to the allow list in your config:
```php
return [
'kql' => [
'classes' => [
'allowed' => [
'Kirby\Cms\System'
]
]
]
];
```
This will introduce full access to all public class methods. This can be very risky though and you should avoid this if possible.
### No Mutations
KQL only offers access to data in your site. It does not support any mutations. All destructive methods are blocked and cannot be accessed in queries.
