PicoTwigExtension
extends AbstractExtension
in package
Pico's Twig extension to implement additional filters
Tags
Table of Contents
- __construct() : mixed
- Constructs a new instance of this Twig extension
- formParamFunction() : mixed
- Filters a HTTP POST parameter with a specified filter
- getFilters() : array<string|int, TwigFilter>
- Returns a list of Pico-specific Twig filters
- getFunctions() : array<string|int, TwigFunction>
- Returns a list of Pico-specific Twig functions
- getKeyOfVar() : mixed
- Returns the value of a variable item specified by a scalar key or a arbitrary deep sub-key using a key path
- getName() : string
- Returns the name of the extension
- getPico() : Pico
- Returns the extensions instance of Pico
- mapFilter() : array<string|int, mixed>
- Returns a array with the values of the given key or key path
- markdownFilter() : string
- Parses a markdown string to HTML
- pagesFunction() : array<string|int, array<string|int, mixed>>
- Returns all pages within a particular branch of Pico's page tree
- sortByFilter() : array<string|int, mixed>
- Sorts an array by one of its keys or a arbitrary deep sub-key
- urlParamFunction() : mixed
- Filters a URL GET parameter with a specified filter
Methods
__construct()
Constructs a new instance of this Twig extension
public
__construct(Pico $pico) : mixed
Parameters
- $pico : Pico
-
current instance of Pico
Return values
mixed —formParamFunction()
Filters a HTTP POST parameter with a specified filter
public
formParamFunction(string $name[, int|string $filter = '' ][, mixed|array<string|int, mixed> $options = null ][, int|string|array<string|int, int>|array<string|int, string> $flags = null ]) : mixed
The Twig function disallows the use of the callback filter.
Parameters
- $name : string
-
name of the HTTP POST parameter to filter
- $filter : int|string = ''
-
the filter to apply
- $options : mixed|array<string|int, mixed> = null
-
either a associative options array to be used by the filter or a scalar default value
- $flags : int|string|array<string|int, int>|array<string|int, string> = null
-
flags and flag strings to be used by the filter
Tags
Return values
mixed —either the filtered data, FALSE if the filter fails, or NULL if the HTTP POST parameter doesn't exist and no default value is given
getFilters()
Returns a list of Pico-specific Twig filters
public
getFilters() : array<string|int, TwigFilter>
Tags
Return values
array<string|int, TwigFilter> —array of Pico's Twig filters
getFunctions()
Returns a list of Pico-specific Twig functions
public
getFunctions() : array<string|int, TwigFunction>
Tags
Return values
array<string|int, TwigFunction> —array of Pico's Twig functions
getKeyOfVar()
Returns the value of a variable item specified by a scalar key or a arbitrary deep sub-key using a key path
public
static getKeyOfVar(array<string|int, mixed>|Traversable|ArrayAccess|object $var, mixed $keyPath) : mixed
Parameters
- $var : array<string|int, mixed>|Traversable|ArrayAccess|object
-
base variable
- $keyPath : mixed
-
scalar key or a array interpreted as key path (when passing e.g. ['foo', 'bar'], the method will return $var['foo']['bar']) specifying the value
Return values
mixed —the requested value or NULL when the given key or key path didn't match
getName()
Returns the name of the extension
public
getName() : string
Tags
Return values
string —the extension name
getPico()
Returns the extensions instance of Pico
public
getPico() : Pico
Tags
Return values
Pico —the extension's instance of Pico
mapFilter()
Returns a array with the values of the given key or key path
public
mapFilter(array<string|int, mixed>|Traversable $var, mixed $mapKeyPath) : array<string|int, mixed>
This method is registered as the Twig map filter. You can use this
filter to e.g. get all page titles ({{ pages|map("title") }}).
Parameters
- $var : array<string|int, mixed>|Traversable
-
variable to map
- $mapKeyPath : mixed
-
key to map; either a scalar or a array interpreted as key path (i.e. ['foo', 'bar'] will return all $item['foo']['bar'] values)
Tags
Return values
array<string|int, mixed> —mapped values
markdownFilter()
Parses a markdown string to HTML
public
markdownFilter(string $markdown[, array<string|int, mixed> $meta = [] ][, bool $singleLine = false ]) : string
This method is registered as the Twig markdown filter. You can use it
to e.g. parse a meta variable ({{ meta.description|markdown }}).
Don't use it to parse the contents of a page, use the content filter
instead, what ensures the proper preparation of the contents.
Parameters
- $markdown : string
-
markdown to parse
- $meta : array<string|int, mixed> = []
-
meta data to use for %meta.*% replacement
- $singleLine : bool = false
-
whether to parse just a single line of markup
Tags
Return values
string —parsed HTML
pagesFunction()
Returns all pages within a particular branch of Pico's page tree
public
pagesFunction([string $start = '' ], int|null $depth, int $depthOffset[, int $offset = 1 ]) : array<string|int, array<string|int, mixed>>
This function should be used most of the time when dealing with Pico's pages array, as it allows one to easily traverse Pico's pages tree (Pico::getPageTree()) to retrieve a subset of Pico's pages array in a very convenient and performant way.
The function's default parameters are $start = "", $depth = 0,
$depthOffset = 0 and $offset = 1. A positive $offset is equivalent
to $depth = $depth + $offset, $depthOffset = $depthOffset + $offset
and $offset = 0.
Consequently the default $start = "", $depth = 0, $depthOffset = 0
and $offset = 1 is equivalent to $depth = 1, $depthOffset = 1 and
$offset = 0. $start = "" instruct the function to start from the
root node (i.e. the node of Pico's main index page at index.md).
$depth tells the function what pages to return. In this example,
$depth = 1 matches the start node (i.e. the zeroth generation) and all
its descendant pages until the first generation (i.e. the start node's
children). $depthOffset instructs the function to exclude some of the
older generations. $depthOffset = 1 specifically tells the function
to exclude the zeroth generation, so that the function returns all of
Pico's main index page's direct child pages (like sub/index.md and
page.md, but not sub/page.md) only.
Passing $depthOffset = -1 only is the same as passing $start = "",
$depth = 1, $depthOffset = 0 and $offset = 0. The only difference
is that $depthOffset won't exclude the zeroth generation, so that the
function returns Pico's main index page as well as all of its direct
child pages.
Passing $depth = 0, $depthOffset = -2 and $offset = 2 is the same
as passing $depth = 2, $depthOffset = 0 and $offset = 0. Both will
return the zeroth, first and second generation of pages. For Pico's main
index page this would be index.md (0th gen), sub/index.md (1st gen),
sub/page.md (2nd gen) and page.md (1st gen). If you want to return
2nd gen pages only, pass $offset = 2 only (with implicit $depth = 0
and $depthOffset = 0 it's the same as $depth = 2, $depthOffset = 2
and $offset = 0).
Instead of an integer you can also pass $depth = null. This is the
same as passing an infinitely large number as $depth, so that this
function simply returns all descendant pages. Consequently passing
$start = "", $depth = null, $depthOffset = 0 and $offset = 0
returns Pico's full pages array.
If $depth is negative after taking $offset into consideration, the
function will throw a TwigRuntimeError exception, since this
would simply make no sense and is likely an error. Passing a negative
$depthOffset is equivalent to passing $depthOffset = 0.
But what about a negative $offset? Passing $offset = -1 instructs
the function not to start from the given $start node, but its parent
node. Consequently $offset = -2 instructs the function to use the
$start node's grandparent node. Obviously this won't make any sense
for Pico's root node, but just image $start = "sub/index". Passing
this together with $offset = -1 is equivalent to $start = "" and
$offset = 0.
Parameters
- $start : string = ''
-
name of the node to start from
- $depth : int|null
-
return pages until the given maximum depth; pass NULL to return all descendant pages; defaults to 0
- $depthOffset : int
-
start returning pages from the given minimum depth; defaults to 0
- $offset : int = 1
-
ascend (positive) or descend (negative) the given number of branches before returning pages; defaults to 1
Tags
Return values
array<string|int, array<string|int, mixed>> —the data of the matched pages
sortByFilter()
Sorts an array by one of its keys or a arbitrary deep sub-key
public
sortByFilter(array<string|int, mixed>|Traversable $var, mixed $sortKeyPath[, string $fallback = 'bottom' ]) : array<string|int, mixed>
This method is registered as the Twig sort_by filter. You can use this
filter to e.g. sort the pages array by a arbitrary meta value. Calling
{{ pages|sort_by([ "meta", "nav" ]) }} returns all pages sorted by the
meta value nav. The sorting algorithm will never assume equality of
two values, it will then fall back to the original order. The result is
always sorted in ascending order, apply Twigs reverse filter to
achieve a descending order.
Parameters
- $var : array<string|int, mixed>|Traversable
-
variable to sort
- $sortKeyPath : mixed
-
key to use for sorting; either a scalar or a array interpreted as key path (i.e. ['foo', 'bar'] will sort $var by $item['foo']['bar'])
- $fallback : string = 'bottom'
-
specify what to do with items which don't contain the specified sort key; use "bottom" (default) to move these items to the end of the sorted array, "top" to rank them first, "keep" to keep the original order, or "remove" to remove these items
Tags
Return values
array<string|int, mixed> —sorted array
urlParamFunction()
Filters a URL GET parameter with a specified filter
public
urlParamFunction(string $name[, int|string $filter = '' ][, mixed|array<string|int, mixed> $options = null ][, int|string|array<string|int, int>|array<string|int, string> $flags = null ]) : mixed
The Twig function disallows the use of the callback filter.
Parameters
- $name : string
-
name of the URL GET parameter to filter
- $filter : int|string = ''
-
the filter to apply
- $options : mixed|array<string|int, mixed> = null
-
either a associative options array to be used by the filter or a scalar default value
- $flags : int|string|array<string|int, int>|array<string|int, string> = null
-
flags and flag strings to be used by the filter
Tags
Return values
mixed —either the filtered data, FALSE if the filter fails, or NULL if the URL GET parameter doesn't exist and no default value is given