Extension

Type

Class

Namespace

craft\web\twig

Inherits

craft\web\twig\Extension » Twig\Extension\AbstractExtension

Implements

Twig\Extension\GlobalsInterface

Since

3.0.0

Class Extension

View source (opens new window)

Protected Properties

Property	Description
environment	\Twig\Environment, null (opens new window)
view	craft\web\View, null (opens new window)

environment

Type

\Twig\Environment, null (opens new window)

Default value

null

View source (opens new window)

view

Type

craft\web\View, null (opens new window)

Default value

null

View source (opens new window)

Public Methods

Method	Description
__construct()	Constructor
addressFilter()
appendFilter()	Appends HTML to the end of the given tag.
atomFilter()	Converts a date to the Atom format.
attrFilter()	Modifies a HTML tag’s attributes, supporting the same attribute definitions as craft\helpers\Html::renderTagAttributes() (opens new window).
camelFilter()	CamelCases a string.
cloneFunction()	Returns a clone of the given variable.
collectFunction()	Returns a new collection.
currencyFilter()	Formats the value as a currency number.
dataUrlFunction()	Generates a base64-encoded data URL (opens new window) for the given file path or asset.
dateFilter()	Extending Twig's
dateFunction()	Converts an input to a DateTime (opens new window) instance.
datetimeFilter()	Formats the value as a date+time.
dumpFunction()	Displays a variable(s).
encencFilter()	Encrypts and base64-encodes a string.
expressionFunction()
filesizeFilter()	Formats the value in bytes as a size in human readable form for example 12 kB.
filterFilter()	Filters an array.
getFilters()
getFunctions()
getGlobals()	Registers global variables.
getNodeVisitors()
getTests()
getTokenParsers()
gqlFunction()	Executes a GraphQL query against the full schema.
groupFilter()	Groups an array by a the results of an arrow function, or value of a property.
httpdateFilter()	Converts a date to the HTTP format (used by HTTP headers such as Expires).
indexOfFilter()	Returns the index of an item in a string or array, or -1 if it cannot be found.
jsonEncodeFilter()	This method will JSON encode a variable. We're overriding Twig's default implementation to set some stricter encoding options on text/html/xml requests.
kebabFilter()	Kebab-cases a string.
lcfirstFilter()	Lowercases the first character of a multibyte string.
lengthFilter()	Returns the length of an array, or the total result count of a query.
literalFilter()	Escapes commas and asterisks in a string so they are not treated as special characters in craft\helpers\Db::parseParam().
markdownFilter()	Parses text through Markdown.
mergeFilter()	Merges an array with another one.
moneyFilter()	Outputs a value from a Money object.
multisortFilter()	Duplicates an array and sorts it with craft\helpers\ArrayHelper::multisort() (opens new window).
numberFilter()	Formats the value as a decimal number.
parseAttrFilter()	Parses an HTML tag to find its attributes.
parseRefsFilter()	Parses a string for reference tags.
pascalFilter()	PascalCases a string.
percentageFilter()	Formats the value as a percent number with "%" sign.
pluginFunction()	Returns a plugin instance by its handle.
prependFilter()	Prepends HTML to the beginning of given tag.
purifyFilter()	Purifies the given HTML using HTML Purifier.
pushFilter()	Pushes one or more items onto the end of an array.
removeClassFilter()	Removes a class (or classes) from the given HTML tag.
renderObjectTemplate()
replaceFilter()	Replaces Twig's
rssFilter()	Converts a date to the RSS format.
seqFunction()	Returns the next number in a given sequence, or the current number in the sequence.
shuffleFunction()	Shuffles an array.
snakeFilter()	Snake_cases a string.
sortFilter()	Sorts an array.
svgFunction()	Returns the contents of a given SVG file.
tagFunction()	Generates a complete HTML tag.
timeFilter()	Formats the value as a time.
timestampFilter()	Formats the value as a human-readable timestamp.
translateFilter()	Translates the given message.
truncateFilter()	Truncates the string to a given length, while ensuring that it does not split words.
ucfirstFilter()	Uppercases the first character of a multibyte string.
ucwordsFilter()	Uppercases the first character of each word in a string.
unshiftFilter()	Prepends one or more items to the beginning of an array.
widontFilter()	Inserts a non-breaking space between the last two words of a string.
withoutFilter()	Returns an array without certain values.
withoutKeyFilter()	Returns an array without a certain key.

__construct()

Constructor

View source (opens new window)

Arguments

• $view (craft\web\View)
• $environment (\Twig\Environment)

addressFilter()

Since

4.0.0

View source (opens new window)

Arguments

• $address (craft\elements\Address, null (opens new window))
• $options (array (opens new window))
• $formatter (\CommerceGuys\Addressing\Formatter\FormatterInterface, null (opens new window))

Returns

string (opens new window)

appendFilter()

Since

3.3.0

Appends HTML to the end of the given tag.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag that $html should be appended to
• $html (string (opens new window)) – The HTML to append to $tag.
• $ifExists (string (opens new window), null (opens new window)) – What to do if $tag already contains a child of the same type as the element defined by $html. Set to 'keep' if no action should be taken, or 'replace' if it should be replaced by $tag.

Returns

string (opens new window) – The modified HTML

atomFilter()

Converts a date to the Atom format.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTime (opens new window), DateTimeInterface (opens new window), string (opens new window)) – A date
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged

Returns

string (opens new window) – The formatted date

attrFilter()

Since

3.3.0

Modifies a HTML tag’s attributes, supporting the same attribute definitions as craft\helpers\Html::renderTagAttributes() (opens new window).

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag whose attributes should be modified.
• $attributes (array (opens new window)) – The attributes to be added to the tag.

Returns

string (opens new window) – The modified HTML tag.

camelFilter()

CamelCases a string.

View source (opens new window)

Arguments

• $string (mixed) – The string

Returns

string (opens new window)

cloneFunction()

Returns a clone of the given variable.

View source (opens new window)

Arguments

• $var (mixed)

Returns

mixed

collectFunction()

Since

4.0.0

Returns a new collection.

View source (opens new window)

Arguments

• $var (mixed)

Returns

\Illuminate\Support\Collection

currencyFilter()

Since

3.6.0

Formats the value as a currency number.

View source (opens new window)

Arguments

• $value (mixed)
• $currency (string (opens new window), null (opens new window))
• $options (array (opens new window))
• $textOptions (array (opens new window))
• $stripZeros (boolean (opens new window))

Returns

string (opens new window)

dataUrlFunction()

Since

3.5.13

Generates a base64-encoded data URL (opens new window) for the given file path or asset.

View source (opens new window)

Arguments

• $file (string (opens new window), craft\elements\Asset) – A file path on an asset
• $mimeType (string (opens new window), null (opens new window)) – The file’s MIME type. If null then it will be determined automatically.

Returns

string (opens new window) – The data URL

Throws

• yii\base\InvalidConfigException (opens new window)
  if $file is an invalid file path, or an asset with a missing/invalid volume ID
• craft\errors\AssetException
  if a stream could not be created for the asset

dateFilter()

Extending Twig's |date filter so we can run any translations on the output.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTimeInterface (opens new window), DateInterval (opens new window), string (opens new window)) – A date
• $format (string (opens new window), null (opens new window)) – The target format, null to use the default
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged
• $locale (string (opens new window), null (opens new window)) – The target locale the date should be formatted for. By default the current system locale will be used.

Returns

string (opens new window)

dateFunction()

Converts an input to a DateTime (opens new window) instance.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTimeInterface (opens new window), string (opens new window), array (opens new window), null (opens new window)) – A date, or null to use the current time
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged

Returns

DateTimeInterface (opens new window)

datetimeFilter()

Formats the value as a date+time.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTimeInterface (opens new window), string (opens new window)) – A date
• $format (string (opens new window), null (opens new window)) – The target format, null to use the default
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged
• $locale (string (opens new window), null (opens new window)) – The target locale the date should be formatted for. By default the current systme locale will be used.

Returns

string (opens new window)

dumpFunction()

Since

4.4.0

Displays a variable(s).

View source (opens new window)

Arguments

• $context (array (opens new window))
• $vars

Returns

string (opens new window)

encencFilter()

Encrypts and base64-encodes a string.

View source (opens new window)

Arguments

• $str (mixed) – The string

Returns

string (opens new window)

expressionFunction()

Since

3.1.0

View source (opens new window)

Arguments

• $expression (mixed)
• $params (array (opens new window))
• $config (array (opens new window))

Returns

yii\db\Expression (opens new window)

filesizeFilter()

Since

3.6.0

Formats the value in bytes as a size in human readable form for example 12 kB.

View source (opens new window)

Arguments

• $value (mixed)
• $decimals (integer (opens new window), null (opens new window))
• $options (array (opens new window))
• $textOptions (array (opens new window))

Returns

string (opens new window)

filterFilter()

Filters an array.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $arr (iterable)
• $arrow (callable (opens new window), null (opens new window))

Returns

array (opens new window)

getFilters()

View source (opens new window)

getFunctions()

View source (opens new window)

getGlobals()

Registers global variables.

View source (opens new window)

getNodeVisitors()

View source (opens new window)

getTests()

View source (opens new window)

getTokenParsers()

View source (opens new window)

gqlFunction()

Since

3.3.12

Executes a GraphQL query against the full schema.

View source (opens new window)

Arguments

• $query (string (opens new window)) – The GraphQL query
• $variables (array (opens new window), null (opens new window)) – Query variables
• $operationName (string (opens new window), null (opens new window)) – The operation name

Returns

array (opens new window) – The query result

groupFilter()

Groups an array by a the results of an arrow function, or value of a property.

View source (opens new window)

Arguments

• $arr (iterable)
• $arrow (callable (opens new window), string (opens new window)) – The arrow function or property name that determines the group the item should be grouped in

Returns

array (opens new window)[] – The grouped items

Throws

• \Twig\Error\RuntimeError
  if $arr is not of type array or Traversable

httpdateFilter()

Since

3.6.10

Converts a date to the HTTP format (used by HTTP headers such as Expires).

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTime (opens new window), DateTimeInterface (opens new window), string (opens new window)) – A date
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged

Returns

string (opens new window) – The formatted date

indexOfFilter()

Returns the index of an item in a string or array, or -1 if it cannot be found.

View source (opens new window)

Arguments

• $haystack (mixed)
• $needle (mixed)

Returns

integer (opens new window)

jsonEncodeFilter()

This method will JSON encode a variable. We're overriding Twig's default implementation to set some stricter encoding options on text/html/xml requests.

View source (opens new window)

Arguments

• $value (mixed) – The value to JSON encode.
• $options (integer (opens new window), null (opens new window)) – Either null or a bitmask consisting of JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_NUMERIC_CHECK, JSON_PRETTY_PRINT, JSON_UNESCAPED_SLASHES, JSON_FORCE_OBJECT
• $depth (integer (opens new window)) – The maximum depth

Returns

string (opens new window), false (opens new window) – The JSON encoded value.

kebabFilter()

Kebab-cases a string.

View source (opens new window)

Arguments

• $string (mixed) – The string
• $glue (string (opens new window)) – The string used to glue the words together (default is a hyphen)
• $lower (boolean (opens new window)) – Whether the string should be lowercased (default is true)
• $removePunctuation (boolean (opens new window)) – Whether punctuation marks should be removed (default is true)

Returns

string (opens new window) – The kebab-cased string

lcfirstFilter()

Lowercases the first character of a multibyte string.

View source (opens new window)

Arguments

• $string (mixed) – The multibyte string.

Returns

string (opens new window) – The string with the first character converted to lowercase.

lengthFilter()

Since

4.2.0

Returns the length of an array, or the total result count of a query.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $value (mixed) – A variable

Returns

integer (opens new window) – The length of the value

literalFilter()

Escapes commas and asterisks in a string so they are not treated as special characters in craft\helpers\Db::parseParam().

View source (opens new window)

Arguments

• $value (mixed) – The param value.

Returns

string (opens new window) – The escaped param value.

markdownFilter()

Parses text through Markdown.

View source (opens new window)

Arguments

• $markdown (mixed) – The markdown text to parse
• $flavor (string (opens new window), null (opens new window)) – The markdown flavor to use. Can be 'original', 'gfm' (GitHub-Flavored Markdown), 'gfm-comment' (GFM with newlines converted to <br>s), or 'extra' (Markdown Extra). Default is 'original'.
• $inlineOnly (boolean (opens new window)) – Whether to only parse inline elements, omitting any <p> tags.

Returns

string (opens new window)

mergeFilter()

Since

3.4.0

Merges an array with another one.

View source (opens new window)

Arguments

• $arr1 (iterable) – An array
• $arr2 (iterable) – An array
• $recursive (boolean (opens new window)) – Whether the arrays should be merged recursively using yii\helpers\BaseArrayHelper::merge() (opens new window)

Returns

array (opens new window) – The merged array

moneyFilter()

Outputs a value from a Money object.

View source (opens new window)

Arguments

• $money (\Money\Money, null (opens new window))
• $formatLocale (string (opens new window), null (opens new window))

Returns

string (opens new window), null (opens new window)

multisortFilter()

Duplicates an array and sorts it with craft\helpers\ArrayHelper::multisort() (opens new window).

View source (opens new window)

Arguments

• $array (mixed) – The array to be sorted. The array will be modified after calling this method.
• $key (string (opens new window), callable (opens new window), array (opens new window)) – The key(s) to be sorted by. This refers to a key name of the sub-array elements, a property name of the objects, or an anonymous function returning the values for comparison purpose. The anonymous function signature should be: function($item). To sort by multiple keys, provide an array of keys here.
• $direction (integer (opens new window), array (opens new window)) – The sorting direction. It can be either SORT_ASC or SORT_DESC. When sorting by multiple keys with different sorting directions, use an array of sorting directions.
• $sortFlag (integer (opens new window), array (opens new window)) – The PHP sort flag. Valid values include SORT_REGULAR, SORT_NUMERIC, SORT_STRING, SORT_LOCALE_STRING, SORT_NATURAL and SORT_FLAG_CASE. Please refer to PHP manual (opens new window) for more details. When sorting by multiple keys with different sort flags, use an array of sort flags.

Returns

array (opens new window) – The sorted array

Throws

• yii\base\InvalidArgumentException (opens new window)
  if the $direction or $sortFlag parameters do not have correct number of elements as that of $key.

numberFilter()

Since

3.6.0

Formats the value as a decimal number.

View source (opens new window)

Arguments

• $value (mixed)
• $decimals (integer (opens new window), null (opens new window))
• $options (array (opens new window))
• $textOptions (array (opens new window))

Returns

string (opens new window)

parseAttrFilter()

Since

3.4.0

Parses an HTML tag to find its attributes.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag to parse

Returns

array (opens new window) – The parsed HTML tag attributes

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $tag doesn't contain a valid HTML tag

parseRefsFilter()

Parses a string for reference tags.

View source (opens new window)

Arguments

• $str (mixed)
• $siteId (integer (opens new window), null (opens new window))

Returns

string (opens new window)

pascalFilter()

PascalCases a string.

View source (opens new window)

Arguments

• $string (mixed) – The string

Returns

string (opens new window)

percentageFilter()

Since

3.6.0

Formats the value as a percent number with "%" sign.

View source (opens new window)

Arguments

• $value (mixed)
• $decimals (integer (opens new window), null (opens new window))
• $options (array (opens new window))
• $textOptions (array (opens new window))

Returns

string (opens new window)

pluginFunction()

Since

3.1.0

Returns a plugin instance by its handle.

View source (opens new window)

Arguments

• $handle (string (opens new window)) – The plugin handle

Returns

craft\base\PluginInterface, null (opens new window) – The plugin, or null if it’s not installed

prependFilter()

Since

3.3.0

Prepends HTML to the beginning of given tag.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag that $html should be prepended to
• $html (string (opens new window)) – The HTML to prepend to $tag.
• $ifExists (string (opens new window), null (opens new window)) – What to do if $tag already contains a child of the same type as the element defined by $html. Set to 'keep' if no action should be taken, or 'replace' if it should be replaced by $tag.

Returns

string (opens new window) – The modified HTML

purifyFilter()

Since

3.4.0

Purifies the given HTML using HTML Purifier.

View source (opens new window)

Arguments

• $html (string (opens new window)) – The HTML to be purified
• $config (string (opens new window), array (opens new window), null (opens new window)) – The HTML Purifier config. This can either be the name of a JSON file within config/htmlpurifier/ (sans .json extension) or a config array.

Returns

string (opens new window) – The purified HTML

pushFilter()

Since

3.5.0

Pushes one or more items onto the end of an array.

View source (opens new window)

Arguments

• $array (array (opens new window))

Returns

array (opens new window)

removeClassFilter()

Since

3.7.0

Removes a class (or classes) from the given HTML tag.

View source (opens new window)

Arguments

• $tag (string (opens new window)) – The HTML tag to modify
• $class (string (opens new window), string (opens new window)[])

Returns

string (opens new window) – The modified HTML tag

renderObjectTemplate()

View source (opens new window)

Arguments

• $template (string (opens new window))
• $object (mixed)

Returns

string (opens new window)

replaceFilter()

Replaces Twig's |replace filter, adding support for passing in separate search and replace arrays.

View source (opens new window)

Arguments

• $str (mixed)
• $search (mixed)
• $replace (mixed)

Returns

mixed

rssFilter()

Converts a date to the RSS format.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTime (opens new window), DateTimeInterface (opens new window), string (opens new window)) – A date
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged

Returns

string (opens new window) – The formatted date

seqFunction()

Since

3.0.31

Returns the next number in a given sequence, or the current number in the sequence.

View source (opens new window)

Arguments

• $name (string (opens new window)) – The sequence name.
• $length (integer (opens new window), null (opens new window)) – The minimum string length that should be returned. (Numbers that are too short will be left-padded with 0s.)
• $next (boolean (opens new window)) – Whether the next number in the sequence should be returned (and the sequence should be incremented). If set to false, the current number in the sequence will be returned instead.

Returns

integer (opens new window), string (opens new window)

Throws

• Throwable (opens new window)
  if reasons
• yii\db\Exception (opens new window)

shuffleFunction()

Shuffles an array.

View source (opens new window)

Arguments

• $arr (iterable)

Returns

array (opens new window)

snakeFilter()

Snake_cases a string.

View source (opens new window)

Arguments

• $string (mixed) – The string

Returns

string (opens new window)

sortFilter()

Since

4.3.2

Sorts an array.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $array (iterable)
• $arrow (string (opens new window), callable (opens new window), null (opens new window))

Returns

array (opens new window)

Throws

• \Twig\Error\RuntimeError

svgFunction()

Returns the contents of a given SVG file.

View source (opens new window)

Arguments

• $svg (string (opens new window), craft\elements\Asset) – An SVG asset, a file path, or raw SVG markup
• $sanitize (boolean (opens new window), null (opens new window)) – Whether the SVG should be sanitized of potentially malicious scripts. By default the SVG will only be sanitized if an asset or markup is passed in. (File paths are assumed to be safe.)
• $namespace (boolean (opens new window), null (opens new window)) – Whether class names and IDs within the SVG should be namespaced to avoid conflicts with other elements in the DOM. By default the SVG will only be namespaced if an asset or markup is passed in.
• $class (string (opens new window), null (opens new window)) – A CSS class name that should be added to the <svg> element. (This argument is deprecated. The |attr filter should be used instead.)

Returns

string (opens new window)

tagFunction()

Since

3.3.0

Generates a complete HTML tag.

View source (opens new window)

Arguments

• $type (string (opens new window)) – The tag type ('p', 'div', etc.)
• $attributes (array (opens new window)) – The HTML tag attributes in terms of name-value pairs. If text is supplied, the value will be HTML-encoded and included as the contents of the tag. If 'html' is supplied, the value will be included as the contents of the tag, without getting encoded.

Returns

string (opens new window)

timeFilter()

Formats the value as a time.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $date (DateTimeInterface (opens new window), string (opens new window)) – A date
• $format (string (opens new window), null (opens new window)) – The target format, null to use the default
• $timezone (DateTimeZone (opens new window), string (opens new window), false (opens new window), null (opens new window)) – The target timezone, null to use the default, false to leave unchanged
• $locale (string (opens new window), null (opens new window)) – The target locale the date should be formatted for. By default the current systme locale will be used.

Returns

string (opens new window)

timestampFilter()

Since

3.6.0

Formats the value as a human-readable timestamp.

View source (opens new window)

Arguments

• $value (mixed)
• $format (string (opens new window), null (opens new window))
• $withPreposition (boolean (opens new window))

Returns

string (opens new window)

translateFilter()

Translates the given message.

View source (opens new window)

Arguments

• $message (mixed) – The message to be translated.
• $category (string (opens new window), array (opens new window), null (opens new window)) – The message category.
• $params (array (opens new window), string (opens new window), null (opens new window)) – The parameters that will be used to replace the corresponding placeholders in the message.
• $language (string (opens new window), null (opens new window)) – The language code (e.g. en-US, en). If this is null, the current application language (opens new window) will be used.

Returns

string (opens new window) – The translated message.

truncateFilter()

Since

3.5.10

Truncates the string to a given length, while ensuring that it does not split words.

View source (opens new window)

Arguments

• $string (string (opens new window)) – The string to truncate
• $length (integer (opens new window)) – The maximum number of characters for the truncated string
• $suffix (string (opens new window)) – The string that should be appended to $string, if it must be truncated
• $splitSingleWord (boolean (opens new window)) – Whether to split up $string if it only contains one word

Returns

string (opens new window) – The truncated string

ucfirstFilter()

Uppercases the first character of a multibyte string.

View source (opens new window)

Arguments

• $string (mixed) – The multibyte string.

Returns

string (opens new window) – The string with the first character converted to upercase.

ucwordsFilter()

Uppercases the first character of each word in a string.

View source (opens new window)

Arguments

• $env (\Twig\Environment)
• $string (string (opens new window))

Returns

string (opens new window)

unshiftFilter()

Since

3.5.0

Prepends one or more items to the beginning of an array.

View source (opens new window)

Arguments

• $array (array (opens new window))

Returns

array (opens new window)

widontFilter()

Since

3.7.0

Inserts a non-breaking space between the last two words of a string.

View source (opens new window)

Arguments

• $string (string (opens new window))

Returns

string (opens new window)

withoutFilter()

Returns an array without certain values.

View source (opens new window)

Arguments

• $arr (mixed)
• $exclude (mixed)
• $strict (boolean (opens new window))

Returns

array (opens new window)

withoutKeyFilter()

Since

3.2.0

Returns an array without a certain key.

View source (opens new window)

Arguments

• $arr (mixed)
• $key (string (opens new window), string (opens new window)[])

Returns

array (opens new window)