Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: fix syntax errors by using dump function #139

Open
wants to merge 2 commits into
base: 2.x
Choose a base branch
from
Open

docs: fix syntax errors by using dump function #139

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
79339da
docs: fix syntax errors by using dump function
tbreuss Jul 8, 2023
6ba8725
docs: remove assets
tbreuss Jul 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 47 additions & 27 deletions website/site/pages/2-doc/5-indepth/5-query-builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,31 +9,51 @@ Herbie provides a fluent query builder interacting with your content and data in

~~~php
$data = [
['title' => 'Foo', 'layout' => 'blog'],
['title' => 'Bar', 'layout' => 'news'],
['title' => 'Baz', 'layout' => 'blog'],
['title' => 'Foo', 'layout' => 'default'],
['title' => 'Bar', 'layout' => 'blog'],
['title' => 'Baz', 'layout' => 'default'],
];
$entries = (new \herbie\QueryBuilder)

var_dump(
(new \herbie\QueryBuilder)
->from($data)
->where('layout=blog')
->offset(10)
->limit(10)
->where('layout=default')
->offset(1)
->limit(1)
->order('title')
->all()
);
~~~

In Twig the same query builder can be instantiated using the `query` function.

~~~twig
{{ '{%' }} set entries = query(data).where("layout=blog").offset(10).limit(10).order('title').all() {{ '%}' }}
{{ '{%' }} set data = [
{
'title': 'Foo',
'layout': 'default',
},
{
'title': 'Bar',
'layout': 'blog',
},
{
'title': 'Baz',
'layout': 'default',
}
] {{ '%}' }}

{{ '{{' }} dump(query(data).where("layout=default").offset(1).limit(1).order('title').all()) {{ '}}' }}
~~~

Some list entites also have a built-in query method, so the query builder can be used as follows.

~~~twig
{{ '{%' }} set entries = site.page_list.where("layout=blog").offset(10).limit(10).order('title').all() {{ '%}' }}
{{ '{{' }} dump(site.page_list.query().where("layout=default").all()) {{ '}}' }}
~~~

NOTE: We are using Twigs `dump` function in these examples. You have to enable the function by setting `components.twigRenderer.debug` to `true` in your configuration file.

## Retrieving Data

A query builder allows you to query, filter, and narrow down the results you desire.
Expand All @@ -44,7 +64,7 @@ The page list query builder allows you to find all the entries in a collection,
The query builder allows you to assemble a query, chain additional constraints onto it, and then invoke the `all` method to get the results:

~~~twig
{{ '{{' }} query(site.page_list).where("layout=blog").limit(5).all() {{ '}}' }}
{{ '{{' }} dump(query(site.page_list).where("layout=default").limit(5).all()) {{ '}}' }}
~~~

This would return a list of the queried items.
Expand All @@ -56,7 +76,7 @@ If you only want to get a single record, you may use the `one` method.
This method will return a single data object:

~~~twig
{{ '{{' }} query(site.page_list).where("layout=blog").one() {{ '}}' }}
{{ '{{' }} dump(query(site.page_list).where("layout=default").one()) {{ '}}' }}
~~~

## Where
Expand Down Expand Up @@ -92,27 +112,27 @@ The String format is best used to specify simple conditions.
For example:

~~~twig
{{ '{{' }} query(data).where("layout=blog", "title*=news") {{ '}}' }}
{{ '{{' }} dump(query(data).where("layout=default", "title*=news")) {{ '}}' }}
~~~

You can chain where clauses, filtering records based on more than one condition with AND:

~~~twig
{{ '{{' }} query(data).where("layout=blog").where("title*=news").where("hidden=false") {{ '}}' }}
{{ '{{' }} dump(query(data).where("layout=default").where("title*=news").where("hidden=false")) {{ '}}' }}
~~~

Values are type hinted according to the type of the field and one of the scalar types bool, float, int, or string.

~~~twig
{{ '{{' }} query(data).where("hidden=false", "size=14.25", "age=24", "layout=blog") {{ '}}' }}
{{ '{{' }} dump(query(data).where("hidden=false", "size=14.25", "age=24", "layout=default")) {{ '}}' }}
~~~

#### Multiple Fields

If you want to match a value in one field or another, you may specify multiple fields separated by a pipe "|" symbol, i.e.

~~~twig
{{ '{{' }} query(data).where("name|title|menu_title=product") {{ '}}' }}
{{ '{{' }} dump(query(data).where("name|title|menu_title=product")) {{ '}}' }}
~~~

Using the above syntax, the condition will match any data that have a name, title, or menu_title field of "product" or "Product".
Expand All @@ -122,15 +142,15 @@ Using the above syntax, the condition will match any data that have a name, titl
You may also specify an either/or value, by separating each of the values that may match with a pipe character "|".

~~~twig
{{ '{{' }} query(data).where("layout=blog|news") {{ '}}' }}
{{ '{{' }} dump(query(data).where("layout=default|blog")) {{ '}}' }}
~~~

#### Array Fields

If the queried field is an array, the operator is applied for each array items as OR conjunction.

~~~twig
{{ '{{' }} query(data).where("tags=blog") {{ '}}' }}
{{ '{{' }} dump(query(data).where("tags=blog")) {{ '}}' }}
~~~

Using the above syntax, the query will match if one of the tags equals to "blog".
Expand All @@ -142,7 +162,7 @@ It is written as an array whose keys are column names and values the correspondi
For example:

~~~twig
{{ '{{' }} query(data).where({layout: "blog", age: 24, size: 178.5, hidden: false}) {{ '}}' }}
{{ '{{' }} dump(query(data).where({layout: "default", age: 24, size: 178.5, hidden: false})) {{ '}}' }}
~~~

### Operator Format
Expand All @@ -151,15 +171,15 @@ The operator format is best used when you have more complex sub queries that are
For example:

~~~twig
{{ '{{' }} query(data).where(["OR", "layout=blog", "title*=blog|news", "date>=2022-12-12") {{ '}}' }}
{{ '{{' }} dump(query(data).where(["OR", "layout=default", "title*=blog|news", "date>=2022-12-12"])) {{ '}}' }}
~~~

With the syntax above, the individual conditions are OR conjuncted.

The AND/OR where clause operators can be nested:

~~~twig
{{ '{{' }} query(data).where(["OR", ["AND", "layout=blog", "title*=blog"], ["AND", "date>=2022-12-12", "cached=true"]]) {{ '}}' }}
{{ '{{' }} dump(query(data).where(["OR", ["AND", "layout=default", "title*=blog"], ["AND", "date>=2022-12-12", "cached=true"]])) {{ '}}' }}
~~~

## Order
Expand All @@ -172,46 +192,46 @@ Here are examples of its usage.
Ordered by title descending:

~~~twig
{{ '{{' }} query(data).order("-title") {{ '}}' }}
{{ '{{' }} dump(query(data).order("-title")) {{ '}}' }}
~~~

Ordered by title ascending:

~~~twig
{{ '{{' }} query(data).order("title") {{ '}}' }}
{{ '{{' }} query(data).order("+title") {{ '}}' }}
{{ '{{' }} dump(query(data).order("title")) {{ '}}' }}
{{ '{{' }} dump(query(data).order("+title")) {{ '}}' }}
~~~

## Limit

You may limit the results by using the `limit` method:

~~~twig
{{ '{{' }} query(data).limit(10) {{ '}}' }}
{{ '{{' }} dump(query(data).limit(10)) {{ '}}' }}
~~~

## Offset

You may skip results by using the `offset` method:

~~~twig
{{ '{{' }} query(data).offset(10).limit(10) {{ '}}' }}
{{ '{{' }} dump(query(data).offset(10).limit(10)) {{ '}}' }}
~~~

## Count

The query builder also provides a count method for retrieving the number of records returned.

~~~twig
{{ '{{' }} query(data).where("layout=blog").count() {{ '}}' }}
{{ '{{' }} dump(query(data).where("layout=default").count()) {{ '}}' }}
~~~

## Paginate

If you want to get paginated results on a query, you may use the `paginate` method and specify the desired number of results per page.

~~~twig
{{ '{{' }} query(data).where("layout=blog").paginate(10); {{ '}}' }}
{{ '{{' }} dump(query(data).where("layout=default").paginate(10)) {{ '}}' }}
~~~

This will return an instance of `herbie\Pagination` that you can use to assemble the pagination style of your choice.