Skip to content

Commit

Permalink
docs: fix syntax errors by using dump function
Browse files Browse the repository at this point in the history
  • Loading branch information
tbreuss committed Jul 8, 2023
1 parent e37a970 commit 79339da
Show file tree
Hide file tree
Showing 10 changed files with 47 additions and 27 deletions.
Empty file added website/site/media/a.gif
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Empty file added website/site/media/abc/a.gif
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Empty file added website/site/media/abc/b.jpg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Empty file added website/site/media/abc/c.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Empty file added website/site/media/b.jpg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Empty file added website/site/media/c.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 47 additions & 27 deletions website/site/pages/2-doc/5-indepth/5-query-builder.md
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.

0 comments on commit 79339da

Please sign in to comment.