studio-variable/designtopack
3
0
Fork 0
Code Issues 7 Pull requests Projects Releases Packages Wiki Activity Actions

vite config : ignore /local and /public/** to improve perf

Browse source
This commit is contained in:
isUnknown 2025-10-02 09:53:59 +02:00
parent 3c9eed7804
commit c11a85e7f8
32 changed files with 1235 additions and 858 deletions
Download patch file Download diff file Expand all files Collapse all files

24
public/site/plugins/kql/.editorconfig Normal file
View file

@ -0,0 +1,24 @@
# This file is for unifying the coding style for different editors and IDEs
# editorconfig.org
# PHP PSR-12 Coding Standards
# https://www.php-fig.org/psr/psr-12/
root = true
[*]
charset = utf-8
end_of_line = lf
indent_style = tab
indent_size = 2
trim_trailing_whitespace = true
[*.php]
indent_size = 4
insert_final_newline = true
[*.yml]
indent_style = space
[*.md]
trim_trailing_whitespace = false

1
public/site/plugins/kql/.github/FUNDING.yml vendored Normal file
View file

@ -0,0 +1 @@
custom: ['https://getkirby.com/buy']

29
public/site/plugins/kql/.gitignore vendored Normal file
View file

@ -0,0 +1,29 @@
# OS files
.DS_Store
# npm modules
/node_modules
# files of Composer dependencies that are not needed for the plugin
/vendor/**/.*
/vendor/**/*.json
/vendor/**/*.txt
/vendor/**/*.md
/vendor/**/*.yml
/vendor/**/*.yaml
/vendor/**/*.xml
/vendor/**/*.dist
/vendor/**/readme.php
/vendor/**/LICENSE
/vendor/**/COPYING
/vendor/**/VERSION
/vendor/**/docs/*
/vendor/**/example/*
/vendor/**/examples/*
/vendor/**/test/*
/vendor/**/tests/*
/vendor/**/php4/*
/vendor/getkirby/composer-installer
/.php_cs.cache
/.phpunit.result.cache
/.php-cs-fixer.cache

60
public/site/plugins/kql/.php-cs-fixer.dist.php Normal file
View file

@ -0,0 +1,60 @@
<?php
$finder = PhpCsFixer\Finder::create()
->exclude('dependencies')
->exclude('panel/node_modules')
->in(__DIR__);
$config = new PhpCsFixer\Config();
return $config
->setRules([
'@PSR12' => true,
'align_multiline_comment' => ['comment_type' => 'phpdocs_like'],
'array_indentation' => true,
'array_syntax' => ['syntax' => 'short'],
'cast_spaces' => ['space' => 'none'],
// 'class_keyword_remove' => true, // replaces static::class with 'static' (won't work)
'combine_consecutive_issets' => true,
'combine_consecutive_unsets' => true,
'combine_nested_dirname' => true,
'concat_space' => ['spacing' => 'one'],
'declare_equal_normalize' => ['space' => 'single'],
'dir_constant' => true,
'function_typehint_space' => true,
'include' => true,
'logical_operators' => true,
'lowercase_cast' => true,
'lowercase_static_reference' => true,
'magic_constant_casing' => true,
'magic_method_casing' => true,
'method_chaining_indentation' => true,
'modernize_types_casting' => true,
'multiline_comment_opening_closing' => true,
'native_function_casing' => true,
'native_function_type_declaration_casing' => true,
'new_with_braces' => true,
'no_blank_lines_after_class_opening' => true,
'no_blank_lines_after_phpdoc' => true,
'no_empty_comment' => true,
'no_empty_phpdoc' => true,
'no_empty_statement' => true,
'no_leading_namespace_whitespace' => true,
'no_mixed_echo_print' => ['use' => 'echo'],
'no_unneeded_control_parentheses' => true,
'no_unused_imports' => true,
'no_useless_return' => true,
'ordered_imports' => ['sort_algorithm' => 'alpha'],
// 'phpdoc_add_missing_param_annotation' => ['only_untyped' => false], // adds params in the wrong order
'phpdoc_align' => ['align' => 'left'],
'phpdoc_indent' => true,
'phpdoc_scalar' => true,
'phpdoc_trim' => true,
'short_scalar_cast' => true,
'single_line_comment_style' => true,
'single_quote' => true,
'ternary_to_null_coalescing' => true,
'whitespace_after_comma_in_array' => true
])
->setRiskyAllowed(true)
->setIndent("\t")
->setFinder($finder);

530
public/site/plugins/kql/README.md
View file

@ -16,21 +16,21 @@ Given a POST request to: `/api/query`
```json ```json
{ {
"query": "page('photography').children", "query": "page('photography').children",
"select": { "select": {
"url": true, "url": true,
"title": true, "title": true,
"text": "page.text.markdown", "text": "page.text.markdown",
"images": { "images": {
"query": "page.moodboard", "query": "page.images",
"select": { "select": {
"url": true "url": true
} }
}
},
"pagination": {
"limit": 10
} }
},
"pagination": {
"limit": 10
}
} }
``` ```
@ -39,48 +39,48 @@ Given a POST request to: `/api/query`
```json ```json
{ {
"code": 200, "code": 200,
"result": { "result": {
"data": [ "data": [
{ {
"url": "https://example.com/photography/trees", "url": "https://example.com/photography/trees",
"title": "Trees", "title": "Trees",
"text": "Lorem <strong>ipsum</strong> …", "text": "Lorem <strong>ipsum</strong> …",
"images": [ "images": [
{ {
"url": "https://example.com/media/pages/photography/trees/1353177920-1579007734/cheesy-autumn.jpg" "url": "https://example.com/media/pages/photography/trees/1353177920-1579007734/cheesy-autumn.jpg"
}, },
{ {
"url": "https://example.com/media/pages/photography/trees/1940579124-1579007734/last-tree-standing.jpg" "url": "https://example.com/media/pages/photography/trees/1940579124-1579007734/last-tree-standing.jpg"
}, },
{ {
"url": "https://example.com/media/pages/photography/trees/3506294441-1579007734/monster-trees-in-the-fog.jpg" "url": "https://example.com/media/pages/photography/trees/3506294441-1579007734/monster-trees-in-the-fog.jpg"
} }
] ]
}, },
{ {
"url": "https://example.com/photography/sky", "url": "https://example.com/photography/sky",
"title": "Sky", "title": "Sky",
"text": "<h1>Dolor sit amet</h1> …", "text": "<h1>Dolor sit amet</h1> …",
"images": [ "images": [
{ {
"url": "https://example.com/media/pages/photography/sky/183363500-1579007734/blood-moon.jpg" "url": "https://example.com/media/pages/photography/sky/183363500-1579007734/blood-moon.jpg"
}, },
{ {
"url": "https://example.com/media/pages/photography/sky/3904851178-1579007734/coconut-milkyway.jpg" "url": "https://example.com/media/pages/photography/sky/3904851178-1579007734/coconut-milkyway.jpg"
} }
] ]
} }
], ],
"pagination": { "pagination": {
"page": 1, "page": 1,
"pages": 1, "pages": 1,
"offset": 0, "offset": 0,
"limit": 10, "limit": 10,
"total": 2 "total": 2
} }
}, },
"status": "ok" "status": "ok"
} }
``` ```
@ -116,35 +116,34 @@ return [
### Sending POST Requests ### 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. 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 [ohmyfetch](https://github.com/unjs/ohmyfetch) (a better fetch API for Node and the browser) and JavaScript to retreive data from our Kirby installation.
```js ```js
import { $fetch } from "ohmyfetch";
const api = "https://yoursite.com/api/query"; const api = "https://yoursite.com/api/query";
const username = "apiuser"; const username = "apiuser";
const password = "strong-secret-api-password"; const password = "strong-secret-api-password";
const headers = { const headers = {
Authorization: Authorization: Buffer.from(`${username}:${password}`).toString("base64"),
"Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
"Content-Type": "application/json",
Accept: "application/json",
}; };
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('notes').children", query: "page('notes').children",
select: { select: {
title: true, title: true,
text: "page.text.kirbytext", text: "page.text.kirbytext",
slug: true, slug: true,
date: "page.date.toDate('d.m.Y')", date: "page.date.toDate('d.m.Y')",
}, },
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
### `query` ### `query`
@ -158,15 +157,15 @@ When you don't pass the select option, Kirby will try to come up with the most u
##### Fetching the Site Title ##### Fetching the Site Title
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.title", query: "site.title",
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -185,15 +184,15 @@ console.log(await response.json());
##### Fetching a List of Page IDs ##### Fetching a List of Page IDs
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.children", query: "site.children",
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -220,15 +219,15 @@ console.log(await response.json());
Queries can even execute field methods. Queries can even execute field methods.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.title.upper", query: "site.title.upper",
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -253,16 +252,16 @@ KQL becomes really powerful by its flexible way to control the result set with t
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. 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.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.children", query: "site.children",
select: ["title", "url"], select: ["title", "url"],
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -311,19 +310,19 @@ console.log(await response.json());
You can also use the object notation and pass true for each key/property you want to include. You can also use the object notation and pass true for each key/property you want to include.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.children", query: "site.children",
select: { select: {
title: true, title: true,
url: true, url: true,
}, },
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -368,18 +367,18 @@ console.log(await response.json());
Instead of passing true, you can also pass a string query to specify what you want to return for each key in your select object. Instead of passing true, you can also pass a string query to specify what you want to return for each key in your select object.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.children", query: "site.children",
select: { select: {
title: "page.title", title: "page.title",
}, },
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -409,18 +408,18 @@ console.log(await response.json());
#### Executing Field Methods #### Executing Field Methods
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site.children", query: "site.children",
select: { select: {
title: "page.title.upper", title: "page.title.upper",
}, },
}), },
headers, headers,
}); });
console.log(await response.json()); console.log(response);
``` ```
<details> <details>
@ -452,23 +451,21 @@ console.log(await response.json());
String queries are a perfect way to create aliases or return variations of the same field or property multiple times. String queries are a perfect way to create aliases or return variations of the same field or property multiple times.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('notes').children", query: "page('notes').children",
select: { select: {
title: "page.title", title: "page.title",
upperCaseTitle: "page.title.upper", upperCaseTitle: "page.title.upper",
lowerCaseTitle: "page.title.lower", lowerCaseTitle: "page.title.lower",
guid: "page.id", guid: "page.id",
date: "page.date.toDate('d.m.Y')", date: "page.date.toDate('d.m.Y')",
timestamp: "page.date.toTimestamp", timestamp: "page.date.toTimestamp",
}, },
}), },
headers, headers,
}); });
console.log(await response.json());
``` ```
<details> <details>
@ -504,19 +501,17 @@ console.log(await response.json());
With such string queries you can of course also include nested data With such string queries you can of course also include nested data
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('photography').children", query: "page('photography').children",
select: { select: {
title: "page.title", title: "page.title",
images: "page.moodboard", images: "page.images",
}, },
}), },
headers, headers,
}); });
console.log(await response.json());
``` ```
<details> <details>
@ -554,24 +549,22 @@ console.log(await response.json());
You can also pass an object with a `query` and a `select` option You can also pass an object with a `query` and a `select` option
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('photography').children", query: "page('photography').children",
select: {
title: "page.title",
images: {
query: "page.images",
select: { select: {
title: "page.title", filename: true,
images: {
query: "page.moodboard",
select: {
filename: true,
},
},
}, },
}), },
headers, },
},
headers,
}); });
console.log(await response.json());
``` ```
<details> <details>
@ -623,21 +616,19 @@ Whenever you query a collection (pages, files, users, roles, languages) you can
You can specify a custom limit with the limit option. The default limit for collections is 100 entries. You can specify a custom limit with the limit option. The default limit for collections is 100 entries.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('notes').children", query: "page('notes').children",
pagination: { pagination: {
limit: 5, limit: 5,
}, },
select: { select: {
title: "page.title", title: "page.title",
}, },
}), },
headers, headers,
}); });
console.log(await response.json());
``` ```
<details> <details>
@ -683,22 +674,20 @@ console.log(await response.json());
You can jump to any page in the resultset with the `page` option. You can jump to any page in the resultset with the `page` option.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('notes').children", query: "page('notes').children",
pagination: { pagination: {
page: 2, page: 2,
limit: 5, limit: 5,
}, },
select: { select: {
title: "page.title", title: "page.title",
}, },
}), },
headers, headers,
}); });
console.log(await response.json());
``` ```
<details> <details>
@ -735,28 +724,26 @@ console.log(await response.json());
Pagination settings also work for subqueries. Pagination settings also work for subqueries.
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "page('photography').children", query: "page('photography').children",
select: { select: {
title: "page.title", title: "page.title",
images: { images: {
query: "page.moodboard", query: "page.images",
pagination: { pagination: {
page: 2, page: 2,
limit: 5, limit: 5,
},
select: {
filename: true,
},
},
}, },
}), select: {
headers, filename: true,
},
},
},
},
headers,
}); });
console.log(await response.json());
``` ```
### Multiple Queries in a Single Call ### Multiple Queries in a Single Call
@ -764,45 +751,43 @@ console.log(await response.json());
With the power of selects and subqueries you can basically query the entire site in a single request With the power of selects and subqueries you can basically query the entire site in a single request
```js ```js
const response = await fetch(api, { const response = await $fetch(api, {
method: "post", method: "post",
body: JSON.stringify({ body: {
query: "site", query: "site",
select: {
title: "site.title",
url: "site.url",
notes: {
query: "page('notes').children.listed",
select: { select: {
title: "site.title", title: true,
url: "site.url", url: true,
notes: { date: "page.date.toDate('d.m.Y')",
query: "page('notes').children.listed", text: "page.text.kirbytext",
select: {
title: true,
url: true,
date: "page.date.toDate('d.m.Y')",
text: "page.text.kirbytext",
},
},
photography: {
query: "page('photography').children.listed",
select: {
title: true,
images: {
query: "page.moodboard",
select: {
url: true,
alt: true,
caption: "file.caption.kirbytext",
},
},
},
},
about: {
text: "page.text.kirbytext",
},
}, },
}), },
headers, photography: {
query: "page('photography').children.listed",
select: {
title: true,
images: {
query: "page.images",
select: {
url: true,
alt: true,
caption: "file.caption.kirbytext",
},
},
},
},
about: {
text: "page.text.kirbytext",
},
},
},
headers,
}); });
console.log(await response.json());
``` ```
### Allowing Methods ### Allowing Methods
@ -951,7 +936,7 @@ If you want to fully allow access to an entire class without putting an intercep
return [ return [
'kql' => [ 'kql' => [
'classes' => [ 'classes' => [
'allowed' => [ 'allow' => [
'Kirby\Cms\System' 'Kirby\Cms\System'
] ]
] ]
@ -967,23 +952,8 @@ KQL only offers access to data in your site. It does not support any mutations.
## Plugins ## Plugins
- [KQL + 11ty](https://github.com/getkirby/eleventykit) - [nuxt-kql](https://nuxt-kql.jhnn.dev): A Nuxt 3 module for KQL.
- [KQL + Nuxt](https://nuxt-kql.jhnn.dev)
## What's Kirby?
- **[getkirby.com](https://getkirby.com)** – Get to know the CMS.
- **[Try it](https://getkirby.com/try)** – Take a test ride with our online demo. Or download one of our kits to get started.
- **[Documentation](https://getkirby.com/docs/guide)** – Read the official guide, reference and cookbook recipes.
- **[Issues](https://github.com/getkirby/kirby/issues)** – Report bugs and other problems.
- **[Feedback](https://feedback.getkirby.com)** – You have an idea for Kirby? Share it.
- **[Forum](https://forum.getkirby.com)** – Whenever you get stuck, don't hesitate to reach out for questions and support.
- **[Discord](https://chat.getkirby.com)** – Hang out and meet the community.
- **[Mastodon](https://mastodon.social/@getkirby)** – Spread the word.
- **[Instagram](https://www.instagram.com/getkirby/)** – Share your creations: #madewithkirby.
---
## License ## License
[MIT](./LICENSE) License © 2020-2023 [Bastian Allgeier](https://getkirby.com) [MIT](./LICENSE) License © 2020-2022 [Bastian Allgeier](https://getkirby.com)

56
public/site/plugins/kql/composer.json
View file

@ -2,8 +2,7 @@
"name": "getkirby/kql", "name": "getkirby/kql",
"description": "Kirby Query Language", "description": "Kirby Query Language",
"license": "MIT", "license": "MIT",
"type": "kirby-plugin", "version": "1.2.0",
"version": "2.1.0",
"keywords": [ "keywords": [
"kirby", "kirby",
"cms", "cms",
@ -12,62 +11,29 @@
"query", "query",
"headless" "headless"
], ],
"homepage": "https://getkirby.com",
"type": "kirby-plugin",
"authors": [ "authors": [
{ {
"name": "Bastian Allgeier", "name": "Bastian Allgeier",
"email": "bastian@getkirby.com" "email": "bastian@getkirby.com"
},
{
"name": "Nico Hoffmann",
"email": "nico@getkirby.com"
} }
], ],
"homepage": "https://getkirby.com",
"support": {
"email": "support@getkirby.com",
"issues": "https://github.com/getkirby/kql/issues",
"forum": "https://forum.getkirby.com",
"source": "https://github.com/getkirby/kql"
},
"require": { "require": {
"php": ">=8.0.0 <8.3.0",
"getkirby/cms": ">=3.8.2",
"getkirby/composer-installer": "^1.2.1" "getkirby/composer-installer": "^1.2.1"
}, },
"config": {
"optimize-autoloader": true,
"allow-plugins": {
"getkirby/composer-installer": false
}
},
"autoload": { "autoload": {
"psr-4": { "psr-4": {
"Kirby\\": [ "Kirby\\": "src/"
"tests/"
]
} }
}, },
"config": {
"allow-plugins": {
"getkirby/composer-installer": true
},
"optimize-autoloader": true
},
"extra": {
"installer-name": "kql",
"kirby-cms-path": false
},
"scripts": { "scripts": {
"analyze": [ "fix": "php-cs-fixer fix"
"@analyze:composer",
"@analyze:psalm",
"@analyze:phpcpd",
"@analyze:phpmd"
],
"analyze:composer": "composer validate --strict --no-check-version --no-check-all",
"analyze:phpcpd": "phpcpd --fuzzy --exclude tests --exclude vendor .",
"analyze:phpmd": "phpmd . ansi phpmd.xml.dist --exclude 'dependencies/*,tests/*,vendor/*'",
"analyze:psalm": "psalm",
"ci": [
"@fix",
"@analyze",
"@test"
],
"fix": "php-cs-fixer fix",
"test": "phpunit --stderr --coverage-html=tests/coverage"
} }
} }

66
public/site/plugins/kql/composer.lock generated Normal file
View file

@ -0,0 +1,66 @@
{
"_readme": [
"This file locks the dependencies of your project to a known state",
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "b3661c52f0da1ad6c43e66f6001abb79",
"packages": [
{
"name": "getkirby/composer-installer",
"version": "1.2.1",
"source": {
"type": "git",
"url": "https://github.com/getkirby/composer-installer.git",
"reference": "c98ece30bfba45be7ce457e1102d1b169d922f3d"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/getkirby/composer-installer/zipball/c98ece30bfba45be7ce457e1102d1b169d922f3d",
"reference": "c98ece30bfba45be7ce457e1102d1b169d922f3d",
"shasum": ""
},
"require": {
"composer-plugin-api": "^1.0 || ^2.0"
},
"require-dev": {
"composer/composer": "^1.8 || ^2.0"
},
"type": "composer-plugin",
"extra": {
"class": "Kirby\\ComposerInstaller\\Plugin"
},
"autoload": {
"psr-4": {
"Kirby\\": "src/"
}
},
"notification-url": "https://packagist.org/downloads/",
"license": [
"MIT"
],
"description": "Kirby's custom Composer installer for the Kirby CMS and for Kirby plugins",
"homepage": "https://getkirby.com",
"support": {
"issues": "https://github.com/getkirby/composer-installer/issues",
"source": "https://github.com/getkirby/composer-installer/tree/1.2.1"
},
"funding": [
{
"url": "https://getkirby.com/buy",
"type": "custom"
}
],
"time": "2020-12-28T12:54:39+00:00"
}
],
"packages-dev": [],
"aliases": [],
"minimum-stability": "stable",
"stability-flags": [],
"prefer-stable": false,
"prefer-lowest": false,
"platform": [],
"platform-dev": [],
"plugin-api-version": "2.3.0"
}

8
public/site/plugins/kql/extensions/aliases.php
View file

@ -1,8 +0,0 @@
<?php
class_alias(\Kirby\Kql\Kql::class, 'Kql');
class_alias(\Kirby\Kql\Interceptor::class, 'Kirby\Kql\Interceptors\Interceptor');
// Provide backwards compatibility for Kirby 3 core classes
class_alias(\Kirby\Kql\Interceptors\Content\Content::class, 'Kirby\Kql\Interceptors\Cms\Content');
class_alias(\Kirby\Kql\Interceptors\Content\Field::class, 'Kirby\Kql\Interceptors\Cms\Field');

25
public/site/plugins/kql/extensions/api.php
View file

@ -1,25 +0,0 @@
<?php
use Kirby\Kql\Kql;
return [
'routes' => function ($kirby) {
return [
[
'pattern' => 'query',
'method' => 'POST|GET',
'auth' => $kirby->option('kql.auth') === false ? false : true,
'action' => function () use ($kirby) {
$input = $kirby->request()->get();
$result = Kql::run($input);
return [
'code' => 200,
'result' => $result,
'status' => 'ok',
];
}
]
];
}
];

21
public/site/plugins/kql/extensions/autoload.php
View file

@ -1,21 +0,0 @@
<?php
namespace Kirby\Kql;
use Kirby\Toolkit\Str;
function autoload(string $namespace, string $dir)
{
spl_autoload_register(function ($class) use ($namespace, $dir) {
if (str_contains($class, '.') === true || str_starts_with($class, $namespace) === false) {
return;
}
$path = Str::after($class, $namespace);
$path = $dir . '/' . str_replace('\\', '/', $path) . '.php';
if (is_file($path) === true) {
include $path;
}
});
}

11
public/site/plugins/kql/extensions/helpers.php
View file

@ -1,11 +0,0 @@
<?php
use Kirby\Cms\Helpers;
use Kirby\Kql\Kql;
if (Helpers::hasOverride('kql') === false) {
function kql($input, $model = null)
{
return Kql::run($input, $model);
}
}

35
public/site/plugins/kql/index.php
View file

@ -1,16 +1,33 @@
<?php <?php
namespace Kirby\Kql; @include_once __DIR__ . '/vendor/autoload.php';
use Kirby\Cms\App; class_alias('Kirby\Kql\Kql', 'Kql');
require_once __DIR__ . '/extensions/autoload.php'; function kql($input, $model = null)
{
return Kql::run($input, $model);
}
autoload('Kirby\\', __DIR__ . '/src/'); Kirby::plugin('getkirby/kql', [
'api' => [
'routes' => function ($kirby) {
return [
[
'pattern' => 'query',
'method' => 'POST|GET',
'auth' => $kirby->option('kql.auth') === false ? false : true,
'action' => function () {
$result = Kql::run(get());
require_once __DIR__ . '/extensions/aliases.php'; return [
require_once __DIR__ . '/extensions/helpers.php'; 'code' => 200,
'result' => $result,
App::plugin('getkirby/kql', [ 'status' => 'ok',
'api' => require_once 'extensions/api.php' ];
}
]
];
}
]
]); ]);

13
public/site/plugins/kql/phpunit.xml.dist Normal file
View file

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="tests/bootstrap.php" convertErrorsToExceptions="true" convertNoticesToExceptions="true" convertWarningsToExceptions="true" stopOnFailure="true" stderr="true" colors="true" verbose="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
<coverage>
<include>
<directory>./src</directory>
</include>
</coverage>
<testsuites>
<testsuite name="Classes">
<directory>./tests/</directory>
</testsuite>
</testsuites>
</phpunit>

106
public/site/plugins/kql/src/Kql/Help.php
View file

@ -2,46 +2,27 @@
namespace Kirby\Kql; namespace Kirby\Kql;
use Kirby\Toolkit\A;
use ReflectionClass;
use ReflectionMethod; use ReflectionMethod;
/**
* Providing help information about
* queried objects, methods, arrays...
*
* @package Kirby KQL
* @author Bastian Allgeier <bastian@getkirby.com>
* @link https://getkirby.com
* @copyright Bastian Allgeier
* @license https://getkirby.com/license
*/
class Help class Help
{ {
/** public static function for($object)
* Provides information about passed value
* depending on its type
*/
public static function for($value): array
{ {
if (is_array($value) === true) { if (is_array($object) === true) {
return static::forArray($value); return static::forArray($object);
} }
if (is_object($value) === true) { if (is_object($object) === true) {
return static::forObject($value); return static::forObject($object);
} }
return [ return [
'type' => gettype($value), 'type' => gettype($object),
'value' => $value 'value' => $object
]; ];
} }
/** public static function forArray(array $array)
* @internal
*/
public static function forArray(array $array): array
{ {
return [ return [
'type' => 'array', 'type' => 'array',
@ -49,42 +30,42 @@ class Help
]; ];
} }
/** public static function forMethod($object, $method)
* Gathers information for method about
* name, parameters, return type etc.
* @internal
*/
public static function forMethod(object $object, string $method): array
{ {
$reflection = new ReflectionMethod($object, $method); $reflection = new ReflectionMethod($object, $method);
$returns = $reflection->getReturnType()?->getName(); $returns = null;
$params = []; $params = [];
if ($returnType = $reflection->getReturnType()) {
$returns = $returnType->getName();
}
foreach ($reflection->getParameters() as $param) { foreach ($reflection->getParameters() as $param) {
$name = $param->getName(); $p = [
$required = $param->isOptional() === false; 'name' => $param->getName(),
$type = $param->hasType() ? $param->getType()->getName() : null; 'required' => $param->isOptional() === false,
$default = null; 'type' => $param->hasType() ? $param->getType()->getName() : null,
];
if ($param->isDefaultValueAvailable()) { if ($param->isDefaultValueAvailable()) {
$default = $param->getDefaultValue(); $p['default'] = $param->getDefaultValue();
} }
$call = ''; $call = null;
if ($type !== null) { if ($p['type'] !== null) {
$call = $type . ' '; $call = $p['type'] . ' ';
} }
$call .= '$' . $name; $call .= '$' . $p['name'];
if ($required === false && $default !== null) { if ($p['required'] === false && isset($p['default']) === true) {
$call .= ' = ' . var_export($default, true); $call .= ' = ' . var_export($p['default'], true);
} }
$p['call'] = $call; $p['call'] = $call;
$params[$name] = compact('name', 'type', 'required', 'default', 'call'); $params[$p['name']] = $p;
} }
$call = '.' . $method; $call = '.' . $method;
@ -101,11 +82,7 @@ class Help
]; ];
} }
/** public static function forMethods($object, $methods)
* Gathers informations for each unique method
* @internal
*/
public static function forMethods(object $object, array $methods): array
{ {
$methods = array_unique($methods); $methods = array_unique($methods);
$reflection = []; $reflection = [];
@ -123,30 +100,11 @@ class Help
return $reflection; return $reflection;
} }
/** public static function forObject($object)
* Retrieves info for objects either from Interceptor (to
* only list allowed methods) or via reflection
* @internal
*/
public static function forObject(object $object): array
{ {
// get interceptor object to only return info on allowed methods $original = $object;
$interceptor = Interceptor::replace($object); $object = Interceptor::replace($original);
if ($interceptor instanceof Interceptor) { return $object->__debugInfo();
return $interceptor->__debugInfo();
}
// for original classes, use reflection
$class = new ReflectionClass($object);
$methods = A::map(
$class->getMethods(),
fn ($method) => static::forMethod($object, $method->getName())
);
return [
'type' => $class->getName(),
'methods' => $methods
];
} }
} }

268
public/site/plugins/kql/src/Kql/Interceptor.php
View file

@ -2,294 +2,58 @@
namespace Kirby\Kql; namespace Kirby\Kql;
use Closure; use Exception;
use Kirby\Cms\App;
use Kirby\Exception\InvalidArgumentException;
use Kirby\Exception\PermissionException; use Kirby\Exception\PermissionException;
use Kirby\Toolkit\Str;
use ReflectionFunction;
use ReflectionMethod;
use Throwable;
/** class Interceptor
* Base class for proxying core classes to
* intercept method calls that are not allowed
* on the related core class
*
* @package Kirby KQL
* @author Bastian Allgeier <bastian@getkirby.com>
* @link https://getkirby.com
* @copyright Bastian Allgeier
* @license https://getkirby.com/license
*/
abstract class Interceptor
{ {
public const CLASS_ALIAS = null;
protected $toArray = [];
public function __construct(protected $object)
{
}
/**
* Magic caller that prevents access
* to restricted methods
*/
public function __call(string $method, array $args = [])
{
if ($this->isAllowedMethod($method) === true) {
return $this->object->$method(...$args);
}
$this->forbiddenMethod($method);
}
/**
* Return information about corresponding object
* incl. information about allowed methods
*/
public function __debugInfo(): array
{
$help = Help::forMethods($this->object, $this->allowedMethods());
return [
'type' => $this::CLASS_ALIAS,
'methods' => $help,
'value' => $this->toArray()
];
}
/**
* Returns list of allowed classes. Specific list
* to be implemented in specific interceptor child classes.
* @codeCoverageIgnore
*/
public function allowedMethods(): array
{
return [];
}
/**
* Returns class name for Interceptor that responds
* to passed name string of a Kirby core class
* @internal
*/
public static function class(string $class): string
{
return str_replace('Kirby\\', 'Kirby\\Kql\\Interceptors\\', $class);
}
/**
* Throws exception for accessing a restricted method
* @throws \Kirby\Exception\PermissionException
*/
protected function forbiddenMethod(string $method)
{
$name = get_class($this->object) . '::' . $method . '()';
throw new PermissionException('The method "' . $name . '" is not allowed in the API context');
}
/**
* Checks if method is allowed to call
*/
public function isAllowedMethod($method)
{
$kirby = App::instance();
$name = strtolower(get_class($this->object) . '::' . $method);
// get list of blocked methods from config
$blocked = $kirby->option('kql.methods.blocked', []);
$blocked = array_map('strtolower', $blocked);
// check in the block list from the config
if (in_array($name, $blocked) === true) {
return false;
}
// check in class allow list
if (in_array($method, $this->allowedMethods()) === true) {
return true;
}
// get list of explicitly allowed methods from config
$allowed = $kirby->option('kql.methods.allowed', []);
$allowed = array_map('strtolower', $allowed);
// check in the allow list from the config
if (in_array($name, $allowed) === true) {
return true;
}
// support for model methods with docblock comment
if ($this->isAllowedCallable($method) === true) {
return true;
}
// support for custom methods with docblock comment
if ($this->isAllowedCustomMethod($method) === true) {
return true;
}
return false;
}
/**
* Checks if closure or object method is allowed
*/
protected function isAllowedCallable($method): bool
{
try {
$ref = match (true) {
$method instanceof Closure
=> new ReflectionFunction($method),
is_string($method) === true
=> new ReflectionMethod($this->object, $method),
default
=> throw new InvalidArgumentException('Invalid method')
};
if ($comment = $ref->getDocComment()) {
if (Str::contains($comment, '@kql-allowed') === true) {
return true;
}
}
} catch (Throwable) {
return false;
}
return false;
}
protected function isAllowedCustomMethod(string $method): bool
{
// has no custom methods
if (property_exists($this->object, 'methods') === false) {
return false;
}
// does not have that method
if (!$call = $this->method($method)) {
return false;
}
// check for a docblock comment
if ($this->isAllowedCallable($call) === true) {
return true;
}
return false;
}
/**
* Returns a registered method by name, either from
* the current class or from a parent class ordered by
* inheritance order (top to bottom)
*/
protected function method(string $method)
{
if (isset($this->object::$methods[$method]) === true) {
return $this->object::$methods[$method];
}
foreach (class_parents($this->object) as $parent) {
if (isset($parent::$methods[$method]) === true) {
return $parent::$methods[$method];
}
}
return null;
}
/**
* Tries to replace a Kirby core object with the
* corresponding interceptor.
* @throws \Kirby\Exception\InvalidArgumentException for non-objects
* @throws \Kirby\Exception\PermissionException when accessing blocked class
*/
public static function replace($object) public static function replace($object)
{ {
if (is_object($object) === false) { if (is_object($object) === false) {
throw new InvalidArgumentException('Unsupported value: ' . gettype($object)); throw new Exception('Unsupported value: ' . gettype($object));
} }
$kirby = App::instance(); $className = get_class($object);
$class = get_class($object); $fullName = strtolower($className);
$name = strtolower($class); $blocked = array_map('strtolower', option('kql.classes.blocked', []));
// 1. Is $object class explicitly blocked?
// get list of blocked classes from config
$blocked = $kirby->option('kql.classes.blocked', []);
$blocked = array_map('strtolower', $blocked);
// check in the block list from the config // check in the block list from the config
if (in_array($name, $blocked) === true) { if (in_array($fullName, $blocked) === true) {
throw new PermissionException('Access to the class "' . $class . '" is blocked'); throw new PermissionException('Access to the class "' . $className . '" is blocked');
} }
// 2. Is $object already an interceptor?
// directly return interceptor objects // directly return interceptor objects
if ($object instanceof Interceptor) { if (is_a($object, 'Kirby\\Kql\\Interceptors\\Interceptor') === true) {
return $object; return $object;
} }
// 3. Does an interceptor class for $object exist?
// check for an interceptor class // check for an interceptor class
$interceptors = $kirby->option('kql.interceptors', []); $interceptors = array_change_key_case(option('kql.interceptors', []), CASE_LOWER);
$interceptors = array_change_key_case($interceptors, CASE_LOWER);
// load an interceptor from config if it exists and otherwise fall back to a built-in interceptor // load an interceptor from config if it exists and otherwise fall back to a built-in interceptor
$interceptor = $interceptors[$name] ?? static::class($class); $interceptor = $interceptors[$fullName] ?? str_replace('Kirby\\', 'Kirby\\Kql\\Interceptors\\', $className);
// check for a valid interceptor class // check for a valid interceptor class
if ($class !== $interceptor && class_exists($interceptor) === true) { if ($className !== $interceptor && class_exists($interceptor) === true) {
return new $interceptor($object); return new $interceptor($object);
} }
// 4. Also check for parent classes of $object
// go through parents of the current object to use their interceptors as fallback // go through parents of the current object to use their interceptors as fallback
foreach (class_parents($object) as $parent) { foreach (class_parents($object) as $parent) {
$interceptor = static::class($parent); $interceptor = str_replace('Kirby\\', 'Kirby\\Kql\\Interceptors\\', $parent);
if (class_exists($interceptor) === true) { if (class_exists($interceptor) === true) {
return new $interceptor($object); return new $interceptor($object);
} }
} }
// 5. $object has no interceptor but is explicitly allowed?
// check for a class in the allow list // check for a class in the allow list
$allowed = $kirby->option('kql.classes.allowed', []); $allowed = array_map('strtolower', option('kql.classes.allowed', []));
$allowed = array_map('strtolower', $allowed);
// return the plain object if it is allowed // return the plain object if it is allowed
if (in_array($name, $allowed) === true) { if (in_array($fullName, $allowed) === true) {
return $object; return $object;
} }
// 6. None of the above? Block class. throw new PermissionException('Access to the class "' . $className . '" is not supported');
throw new PermissionException('Access to the class "' . $class . '" is not supported');
}
public function toArray(): array|null
{
$toArray = [];
// filter methods which cannot be called
foreach ($this->toArray as $method) {
if ($this->isAllowedMethod($method) === true) {
$toArray[] = $method;
}
}
return Kql::select($this, $toArray);
}
/**
* Mirrors by default ::toArray but can be
* implemented differently by specifc interceptor.
* KQL will prefer ::toResponse over ::toArray
*/
public function toResponse()
{
return $this->toArray();
} }
} }

2
public/site/plugins/kql/src/Kql/Interceptors/Cms/App.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Cms; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class App extends Interceptor class App extends Interceptor
{ {

2
public/site/plugins/kql/src/Kql/Interceptors/Cms/Blueprint.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Cms; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Blueprint extends Interceptor class Blueprint extends Interceptor
{ {

2
public/site/plugins/kql/src/Kql/Interceptors/Cms/Collection.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Cms; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Collection extends Interceptor class Collection extends Interceptor
{ {

4
public/site/plugins/kql/src/Kql/Interceptors/Content/Content.php → public/site/plugins/kql/src/Kql/Interceptors/Cms/Content.php
View file

@ -1,8 +1,8 @@
<?php <?php
namespace Kirby\Kql\Interceptors\Content; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Content extends Interceptor class Content extends Interceptor
{ {

4
public/site/plugins/kql/src/Kql/Interceptors/Content/Field.php → public/site/plugins/kql/src/Kql/Interceptors/Cms/Field.php
View file

@ -1,8 +1,8 @@
<?php <?php
namespace Kirby\Kql\Interceptors\Content; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Field extends Interceptor class Field extends Interceptor
{ {

2
public/site/plugins/kql/src/Kql/Interceptors/Cms/Model.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Cms; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Model extends Interceptor class Model extends Interceptor
{ {

2
public/site/plugins/kql/src/Kql/Interceptors/Cms/Role.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Cms; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Role extends Interceptor class Role extends Interceptor
{ {

2
public/site/plugins/kql/src/Kql/Interceptors/Cms/Translation.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Cms; namespace Kirby\Kql\Interceptors\Cms;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Translation extends Interceptor class Translation extends Interceptor
{ {

174
public/site/plugins/kql/src/Kql/Interceptors/Interceptor.php Normal file
View file

@ -0,0 +1,174 @@
<?php
namespace Kirby\Kql\Interceptors;
use Exception;
use Kirby\Exception\PermissionException;
use Kirby\Kql\Help;
use Kirby\Kql\Kql;
use Kirby\Toolkit\Str;
use ReflectionFunction;
use ReflectionMethod;
use Throwable;
abstract class Interceptor
{
public const CLASS_ALIAS = null;
protected $object;
protected $toArray = [];
public function __construct($object)
{
$this->object = $object;
}
public function __call($method, array $args = [])
{
if ($this->isAllowedMethod($method) === true) {
return $this->object->$method(...$args);
}
$this->forbiddenMethod($method);
}
public function allowedMethods(): array
{
return [];
}
protected function forbiddenMethod(string $method)
{
$className = get_class($this->object);
throw new PermissionException('The method "' . $className . '::' . $method . '()" is not allowed in the API context');
}
/**
* Returns a registered method by name, either from
* the current class or from a parent class ordered by
* inheritance order (top to bottom)
*
* @param string $method
* @return \Closure|null
*/
protected function getMethod(string $method)
{
if (isset($this->object::$methods[$method]) === true) {
return $this->object::$methods[$method];
}
foreach (class_parents($this->object) as $parent) {
if (isset($parent::$methods[$method]) === true) {
return $parent::$methods[$method];
}
}
return null;
}
protected function isAllowedCallable($method): bool
{
try {
if (is_a($method, 'Closure') === true) {
$ref = new ReflectionFunction($method);
} elseif (is_string($method) === true) {
$ref = new ReflectionMethod($this->object, $method);
} else {
throw new Exception('Invalid method');
}
if ($comment = $ref->getDocComment()) {
if (Str::contains($comment, '@kql-allowed') === true) {
return true;
}
}
} catch (Throwable $e) {
return false;
}
return false;
}
protected function isAllowedMethod($method)
{
$fullName = strtolower(get_class($this->object) . '::' . $method);
$blocked = array_map('strtolower', option('kql.methods.blocked', []));
// check in the block list from the config
if (in_array($fullName, $blocked) === true) {
return false;
}
// check in class allow list
if (in_array($method, $this->allowedMethods()) === true) {
return true;
}
$allowed = array_map('strtolower', option('kql.methods.allowed', []));
// check in the allow list from the config
if (in_array($fullName, $allowed) === true) {
return true;
}
// support for model methods with docblock comment
if ($this->isAllowedCallable($method) === true) {
return true;
}
// support for custom methods with docblock comment
if ($this->isAllowedCustomMethod($method) === true) {
return true;
}
return false;
}
protected function isAllowedCustomMethod(string $method): bool
{
// has no custom methods
if (property_exists($this->object, 'methods') === false) {
return false;
}
// does not have that method
if (!$call = $this->getMethod($method)) {
return false;
}
// check for a docblock comment
if ($this->isAllowedCallable($call) === true) {
return true;
}
return false;
}
public function __debugInfo(): array
{
return [
'type' => $this::CLASS_ALIAS,
'methods' => Help::forMethods($this->object, $this->allowedMethods()),
'value' => $this->toArray()
];
}
public function toArray(): ?array
{
$toArray = [];
// filter methods which cannot be called
foreach ($this->toArray as $method) {
if ($this->isAllowedMethod($method) === true) {
$toArray[] = $method;
}
}
return Kql::select($this, $toArray);
}
public function toResponse()
{
return $this->toArray();
}
}

2
public/site/plugins/kql/src/Kql/Interceptors/Panel/Model.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Panel; namespace Kirby\Kql\Interceptors\Panel;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Model extends Interceptor class Model extends Interceptor
{ {

2
public/site/plugins/kql/src/Kql/Interceptors/Toolkit/Obj.php
View file

@ -2,7 +2,7 @@
namespace Kirby\Kql\Interceptors\Toolkit; namespace Kirby\Kql\Interceptors\Toolkit;
use Kirby\Kql\Interceptor; use Kirby\Kql\Interceptors\Interceptor;
class Obj extends Interceptor class Obj extends Interceptor
{ {

174
public/site/plugins/kql/src/Kql/Kql.php
View file

@ -3,81 +3,16 @@
namespace Kirby\Kql; namespace Kirby\Kql;
use Exception; use Exception;
use Kirby\Cms\App;
use Kirby\Cms\Collection; use Kirby\Cms\Collection;
use Kirby\Toolkit\Str; use Kirby\Toolkit\Str;
/**
* ...
*
* @package Kirby KQL
* @author Bastian Allgeier <bastian@getkirby.com>
* @link https://getkirby.com
* @copyright Bastian Allgeier
* @license https://getkirby.com/license
*/
class Kql class Kql
{ {
public static function fetch($model, $key, $selection) public static function help($object)
{
// simple key/value
if ($selection === true) {
return static::render($model->$key());
}
// selection without additional query
if (
is_array($selection) === true &&
empty($selection['query']) === true
) {
return static::select(
$model->$key(),
$selection['select'] ?? null,
$selection['options'] ?? []
);
}
// nested queries
return static::run($selection, $model);
}
/**
* Returns helpful information about the object
* type as well as, if available, values and methods
*/
public static function help($object): array
{ {
return Help::for($object); return Help::for($object);
} }
public static function query(string $query, $model = null)
{
$model ??= App::instance()->site();
$data = [$model::CLASS_ALIAS => $model];
return Query::factory($query)->resolve($data);
}
public static function render($value)
{
if (is_object($value) === true) {
// replace actual object with intercepting proxy class
$object = Interceptor::replace($value);
if (method_exists($object, 'toResponse') === true) {
return $object->toResponse();
}
if (method_exists($object, 'toArray') === true) {
return $object->toArray();
}
throw new Exception('The object "' . get_class($object) . '" cannot be rendered. Try querying one of its methods instead.');
}
return $value;
}
public static function run($input, $model = null) public static function run($input, $model = null)
{ {
// string queries // string queries
@ -97,9 +32,11 @@ class Kql
return $result; return $result;
} }
$query = $input['query'] ?? 'site'; $query = $input['query'] ?? 'site';
$select = $input['select'] ?? null; $select = $input['select'] ?? null;
$options = ['pagination' => $input['pagination'] ?? null]; $options = [
'pagination' => $input['pagination'] ?? null,
];
// check for invalid queries // check for invalid queries
if (is_string($query) === false) { if (is_string($query) === false) {
@ -107,14 +44,74 @@ class Kql
} }
$result = static::query($query, $model); $result = static::query($query, $model);
return static::select($result, $select, $options); return static::select($result, $select, $options);
} }
public static function select( public static function fetch($model, $key, $selection)
$data, {
array|string|null $select = null, // simple key/value
array $options = [] if ($selection === true) {
) { return static::render($model->$key());
}
// selection without additional query
if (is_array($selection) === true && empty($selection['query']) === true) {
return static::select($model->$key(), $selection['select'] ?? null, $selection['options'] ?? []);
}
// nested queries
return static::run($selection, $model);
}
public static function query(string $query, $model = null)
{
$kirby = kirby();
$site = $kirby->site();
$model = $model ?? $site;
$query = new Query($query, [
'collection' => function (string $id) use ($kirby) {
return $kirby->collection($id);
},
'file' => function (string $id) use ($kirby) {
return $kirby->file($id);
},
'kirby' => $kirby,
'page' => function (string $id) use ($site) {
return $site->find($id);
},
'site' => $site,
'user' => function (string $id = null) use ($kirby) {
return $kirby->user($id);
},
$model::CLASS_ALIAS => $model
]);
return $query->result();
}
public static function render($value)
{
if (is_object($value) === true) {
$object = Interceptor::replace($value);
if (method_exists($object, 'toResponse') === true) {
return $object->toResponse();
}
if (method_exists($object, 'toArray') === true) {
return $object->toArray();
}
throw new Exception('The object "' . get_class($object) . '" cannot be rendered. Try querying one of its methods instead.');
}
return $value;
}
public static function select($data, $select, array $options = [])
{
if ($select === null) { if ($select === null) {
return static::render($data); return static::render($data);
} }
@ -123,23 +120,20 @@ class Kql
return static::help($data); return static::help($data);
} }
if ($data instanceof Collection) { if (is_a($data, 'Kirby\Cms\Collection') === true) {
return static::selectFromCollection($data, $select, $options); return static::selectFromCollection($data, $select, $options);
} }
if (is_object($data) === true) { if (is_object($data) === true) {
return static::selectFromObject($data, $select); return static::selectFromObject($data, $select, $options);
} }
if (is_array($data) === true) { if (is_array($data) === true) {
return static::selectFromArray($data, $select); return static::selectFromArray($data, $select, $options);
} }
} }
/** public static function selectFromArray($array, $select, array $options = [])
* @internal
*/
public static function selectFromArray(array $array, array $select): array
{ {
$result = []; $result = [];
@ -159,14 +153,8 @@ class Kql
return $result; return $result;
} }
/** public static function selectFromCollection(Collection $collection, $select, array $options = [])
* @internal {
*/
public static function selectFromCollection(
Collection $collection,
array|string $select,
array $options = []
): array {
if ($options['pagination'] ?? false) { if ($options['pagination'] ?? false) {
$collection = $collection->paginate($options['pagination']); $collection = $collection->paginate($options['pagination']);
} }
@ -193,14 +181,8 @@ class Kql
return $data; return $data;
} }
/** public static function selectFromObject($object, $select, array $options = [])
* @internal {
*/
public static function selectFromObject(
object $object,
array|string $select
): array {
// replace actual object with intercepting proxy class
$object = Interceptor::replace($object); $object = Interceptor::replace($object);
$result = []; $result = [];

81
public/site/plugins/kql/src/Kql/Query.php
View file

@ -2,28 +2,71 @@
namespace Kirby\Kql; namespace Kirby\Kql;
use Kirby\Query\Query as BaseQuery; use Kirby\Toolkit\Query as BaseQuery;
/**
* Extends the core Query class with the KQL-specific
* functionalities to intercept the segments chain calls
*
* @package Kirby KQL
* @author Nico Hoffmann <nico@getkirby.com>
* @link https://getkirby.com
* @copyright Bastian Allgeier
* @license https://getkirby.com/license
*/
class Query extends BaseQuery class Query extends BaseQuery
{ {
/** protected function interceptor($object)
* Intercepts the chain of segments called
* on each other by replacing objects with
* their corresponding Interceptor which
* handles blocking calls to restricted methods
*/
public function intercept(mixed $result): mixed
{ {
return is_object($result) ? Interceptor::replace($result): $result; return Interceptor::replace($object);
}
/**
* Resolves the query if anything
* can be found. Otherwise returns null.
*
* @param string $query
* @return mixed
*/
protected function resolve(string $query)
{
// direct key access in arrays
if (is_array($this->data) === true && array_key_exists($query, $this->data) === true) {
$value = $this->data[$query];
// closure resolver
if (is_a($value, 'Closure') === true) {
$value = $value();
}
return $this->interceptor($value);
}
$parts = $this->parts($query);
$data = $this->data;
$value = null;
while (count($parts)) {
$part = array_shift($parts);
$info = $this->part($part);
$method = $info['method'];
$value = null;
if (is_array($data)) {
$value = $data[$method] ?? null;
} elseif (is_object($data)) {
$data = $this->interceptor($data);
if (method_exists($data, $method) || method_exists($data, '__call')) {
$value = $data->$method(...$info['args']);
}
} elseif (is_scalar($data)) {
return $data;
} else {
return null;
}
if (is_a($value, 'Closure') === true) {
$value = $value(...$info['args']);
}
if (is_array($value) === true) {
$data = $value;
} elseif (is_object($value) === true) {
$data = $this->interceptor($value);
}
}
return $value;
} }
} }

175
public/site/plugins/kql/tests/InterceptorTest.php Normal file
View file

@ -0,0 +1,175 @@
<?php
namespace Kirby\Kql;
use Kirby\Cms\App;
use Kirby\Cms\Blueprint;
use Kirby\Cms\Content;
use Kirby\Cms\Field;
use Kirby\Cms\File;
use Kirby\Cms\FileBlueprint;
use Kirby\Cms\FileVersion;
use Kirby\Cms\Page;
use Kirby\Cms\PageBlueprint;
use Kirby\Cms\Role;
use Kirby\Cms\Site;
use Kirby\Cms\SiteBlueprint;
use Kirby\Cms\User;
use Kirby\Cms\UserBlueprint;
use PHPUnit\Framework\TestCase;
class AppExtended extends App
{
}
class FileExtended extends File
{
}
class PageExtended extends Page
{
}
class RoleExtended extends User
{
}
class SiteExtended extends Site
{
}
class UserExtended extends User
{
}
class InterceptorTest extends TestCase
{
public function objectProvider()
{
return [
[
new App(),
'Kirby\\Kql\\Interceptors\\Cms\\App'
],
[
new AppExtended(),
'Kirby\\Kql\\Interceptors\\Cms\\App'
],
[
new Blueprint([
'model' => new Page([
'slug' => 'test'
]),
'name' => 'test',
]),
'Kirby\\Kql\\Interceptors\\Cms\\Blueprint'
],
[
new Content(),
'Kirby\\Kql\\Interceptors\\Cms\\Content'
],
[
new Field(null, 'key', 'value'),
'Kirby\\Kql\\Interceptors\\Cms\\Field'
],
[
new File(['filename' => 'test.jpg']),
'Kirby\\Kql\\Interceptors\\Cms\\File'
],
[
new FileBlueprint([
'model' => new File([
'filename' => 'test.jpg'
]),
'name' => 'test',
]),
'Kirby\\Kql\\Interceptors\\Cms\\Blueprint'
],
[
new FileExtended(['filename' => 'test.jpg']),
'Kirby\\Kql\\Interceptors\\Cms\\File'
],
[
new FileVersion([
'original' => new File([
'filename' => 'test.jpg',
]),
'url' => '/test.jpg'
]),
'Kirby\\Kql\\Interceptors\\Cms\\FileVersion'
],
[
new Page(['slug' => 'test']),
'Kirby\\Kql\\Interceptors\\Cms\\Page'
],
[
new PageBlueprint([
'model' => new Page([
'slug' => 'test'
]),
'name' => 'test',
]),
'Kirby\\Kql\\Interceptors\\Cms\\Blueprint'
],
[
new PageExtended(['slug' => 'test']),
'Kirby\\Kql\\Interceptors\\Cms\\Page'
],
[
new Role(['name' => 'admin']),
'Kirby\\Kql\\Interceptors\\Cms\\Role'
],
[
new Site(),
'Kirby\\Kql\\Interceptors\\Cms\\Site'
],
[
new SiteBlueprint([
'model' => new Site(),
'name' => 'test',
]),
'Kirby\\Kql\\Interceptors\\Cms\\Blueprint'
],
[
new SiteExtended(),
'Kirby\\Kql\\Interceptors\\Cms\\Site'
],
[
new User(['email' => 'test@getkirby.com']),
'Kirby\\Kql\\Interceptors\\Cms\\User'
],
[
new UserBlueprint([
'model' => new User(['email' => 'test@getkirby.com']),
'name' => 'test',
]),
'Kirby\\Kql\\Interceptors\\Cms\\Blueprint'
],
[
new UserExtended(['email' => 'test@getkirby.com']),
'Kirby\\Kql\\Interceptors\\Cms\\User'
]
];
}
/**
* @dataProvider objectProvider
*/
public function testReplace($object, $inspector)
{
$result = Interceptor::replace($object);
$this->assertInstanceOf($inspector, $result);
}
public function testReplaceNonObject()
{
$this->expectException('Exception');
$this->expectExceptionMessage('Unsupported value: string');
$result = Interceptor::replace('hello');
}
public function testReplaceUnknownObject()
{
$this->expectException('Kirby\Exception\PermissionException');
$this->expectExceptionMessage('Access to the class "stdClass" is not supported');
$object = new \stdClass();
$result = Interceptor::replace($object);
}
}

158
public/site/plugins/kql/tests/KqlTest.php Normal file
View file

@ -0,0 +1,158 @@
<?php
namespace Kirby\Kql;
use Kirby\Cms\App;
use PHPUnit\Framework\TestCase;
class KqlTest extends TestCase
{
public function setUp(): void
{
$this->app = new App([
'roots' => [
'index' => '/dev/null'
],
'site' => [
'children' => [
[
'slug' => 'projects'
],
[
'slug' => 'about'
],
[
'slug' => 'contact'
]
],
'content' => [
'title' => 'Test Site'
],
]
]);
}
public function testForbiddenMethod()
{
$this->expectException("Kirby\Exception\PermissionException");
$this->expectExceptionMessage('The method "Kirby\Cms\Page::delete()" is not allowed in the API context');
$result = Kql::run('site.children.first.delete');
}
public function testRun()
{
$result = Kql::run('site.title');
$expected = 'Test Site';
$this->assertSame($expected, $result);
}
public function testQuery()
{
$result = Kql::run([
'query' => 'site.children',
'select' => 'slug'
]);
$expected = [
[
'slug' => 'projects',
],
[
'slug' => 'about',
],
[
'slug' => 'contact',
]
];
$this->assertSame($expected, $result);
}
public function testSelectWithAlias()
{
$result = Kql::run([
'select' => [
'myTitle' => 'site.title'
]
]);
$expected = [
'myTitle' => 'Test Site',
];
$this->assertSame($expected, $result);
}
public function testSelectWithArray()
{
$result = Kql::run([
'select' => ['title', 'url']
]);
$expected = [
'title' => 'Test Site',
'url' => '/'
];
$this->assertSame($expected, $result);
}
public function testSelectWithBoolean()
{
$result = Kql::run([
'select' => [
'title' => true
]
]);
$expected = [
'title' => 'Test Site'
];
$this->assertSame($expected, $result);
}
public function testSelectWithQuery()
{
$result = Kql::run([
'select' => [
'children' => [
'query' => 'site.children',
'select' => 'slug'
]
]
]);
$expected = [
'children' => [
[
'slug' => 'projects',
],
[
'slug' => 'about',
],
[
'slug' => 'contact',
]
]
];
$this->assertSame($expected, $result);
}
public function testSelectWithString()
{
$result = Kql::run([
'select' => [
'title' => 'site.title.upper'
]
]);
$expected = [
'title' => 'TEST SITE'
];
$this->assertSame($expected, $result);
}
}

25
public/site/plugins/kql/tests/bootstrap.php Normal file
View file

@ -0,0 +1,25 @@
<?php
error_reporting(E_ALL);
ini_set('memory_limit', '512M');
ini_set('display_errors', 'on');
ini_set('display_startup_errors', 'on');
require_once dirname(__DIR__, 1) . '/vendor/autoload.php';
// regular setup
$bootstrapper = dirname(__DIR__, 4) . '/kirby/bootstrap.php';
if (is_file($bootstrapper)) {
require_once $bootstrapper;
}
// sandbox
$bootstrapper = dirname(__DIR__, 5) . '/kirby/bootstrap.php';
if (is_file($bootstrapper)) {
require_once $bootstrapper;
}
kirby();

29
vite.config.js
View file

@ -1,16 +1,33 @@
import { defineConfig } from "vite"; import { defineConfig } from 'vite';
import vue from "@vitejs/plugin-vue"; import vue from '@vitejs/plugin-vue';
export default defineConfig({ export default defineConfig({
plugins: [vue()], plugins: [vue()],
base: "/", base: '/',
build: { build: {
outDir: "dist", outDir: 'dist',
rollupOptions: { rollupOptions: {
output: { output: {
entryFileNames: "assets/dist/[name].js", entryFileNames: 'assets/dist/[name].js',
assetFileNames: "assets/dist/[name].[ext]", assetFileNames: 'assets/dist/[name].[ext]',
}, },
}, },
}, },
server: {
watch: {
ignored: [
'**/node_modules/**',
'**/.git/**',
'**/.cache/**',
'**/.vite/**',
'**/dist/**',
'**/*.log',
'**/.idea/**',
'**/.vscode/**',
'**/public/assets/**',
'**/local/**',
'/public/**',
],
},
},
}); });