\PicoTwigExtension

Pico's Twig extension to implement additional filters

Summary

Methods
Properties
Constants
__construct()
getPico()
getName()
getFilters()
getFunctions()
markdownFilter()
mapFilter()
sortByFilter()
getKeyOfVar()
urlParamFunction()
formParamFunction()
pagesFunction()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
$pico
N/A

Properties

$pico

$pico : \Pico

Current instance of Pico

Type

\Pico

Methods

__construct()

__construct(\Pico  $pico) 

Constructs a new instance of this Twig extension

Parameters

\Pico $pico

current instance of Pico

getPico()

getPico() : \Pico

Returns the extensions instance of Pico

Returns

\Pico

the extension's instance of Pico

getName()

getName() : string

Returns the name of the extension

Returns

string —

the extension name

getFilters()

getFilters() : array<mixed,\Twig_SimpleFilter>

Returns a list of Pico-specific Twig filters

Returns

array<mixed,\Twig_SimpleFilter> —

array of Pico's Twig filters

getFunctions()

getFunctions() : array<mixed,\Twig_SimpleFunction>

Returns a list of Pico-specific Twig functions

Returns

array<mixed,\Twig_SimpleFunction> —

array of Pico's Twig functions

markdownFilter()

markdownFilter(string  $markdown, array  $meta = array(), boolean  $singleLine = false) : string

Parses a markdown string to HTML

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

string $markdown

markdown to parse

array $meta

meta data to use for %meta.*% replacement

boolean $singleLine

whether to parse just a single line of markup

Returns

string —

parsed HTML

mapFilter()

mapFilter(array|\Traversable  $var, mixed  $mapKeyPath) : array

Returns a array with the values of the given key or key path

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

array|\Traversable $var

variable to map

mixed $mapKeyPath

key to map; either a scalar or a array interpreted as key path (i.e. ['foo', 'bar'] will return all $item['foo']['bar'] values)

Throws

\Twig_Error_Runtime

Returns

array —

mapped values

sortByFilter()

sortByFilter(array|\Traversable  $var, mixed  $sortKeyPath, string  $fallback = 'bottom') : array

Sorts an array by one of its keys or a arbitrary deep sub-key

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

array|\Traversable $var

variable to sort

mixed $sortKeyPath

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'])

string $fallback

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

Throws

\Twig_Error_Runtime

Returns

array —

sorted array

getKeyOfVar()

getKeyOfVar(array|\Traversable|\ArrayAccess|object  $var, mixed  $keyPath) : mixed

Returns the value of a variable item specified by a scalar key or a arbitrary deep sub-key using a key path

Parameters

array|\Traversable|\ArrayAccess|object $var

base variable

mixed $keyPath

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

Returns

mixed —

the requested value or NULL when the given key or key path didn't match

urlParamFunction()

urlParamFunction(string  $name, integer|string  $filter = '', mixed|array  $options = null, integer|string|array<mixed,integer>|array<mixed,string>  $flags = null) : mixed

Filters a URL GET parameter with a specified filter

The Twig function disallows the use of the callback filter.

Parameters

string $name

name of the URL GET parameter to filter

integer|string $filter

the filter to apply

mixed|array $options

either a associative options array to be used by the filter or a scalar default value

integer|string|array<mixed,integer>|array<mixed,string> $flags

flags and flag strings to be used by the filter

Returns

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

formParamFunction()

formParamFunction(string  $name, integer|string  $filter = '', mixed|array  $options = null, integer|string|array<mixed,integer>|array<mixed,string>  $flags = null) : mixed

Filters a HTTP POST parameter with a specified filter

The Twig function disallows the use of the callback filter.

Parameters

string $name

name of the HTTP POST parameter to filter

integer|string $filter

the filter to apply

mixed|array $options

either a associative options array to be used by the filter or a scalar default value

integer|string|array<mixed,integer>|array<mixed,string> $flags

flags and flag strings to be used by the filter

Returns

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

pagesFunction()

pagesFunction(string  $start = '', integer|null  $depth, integer  $depthOffset, integer  $offset = 1) : array<mixed,array>

Returns all pages within a particular branch of Pico's page tree

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 \Twig_Error_Runtime 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

string $start

name of the node to start from

integer|null $depth

return pages until the given maximum depth; pass NULL to return all descendant pages; defaults to 0

integer $depthOffset

start returning pages from the given minimum depth; defaults to 0

integer $offset

ascend (positive) or descend (negative) the given number of branches before returning pages; defaults to 1

Throws

\Twig_Error_Runtime

Returns

array<mixed,array> —

the data of the matched pages