PHPackages                             berraisabdelaziz/craft-helpers - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. berraisabdelaziz/craft-helpers

ActiveCraft-plugin

berraisabdelaziz/craft-helpers
==============================

The plugin provides functions, which allow to read and convert JSON, YAML, CSV and PHP file contents. Using the readText or inline function you can read an entire file into a string.

03[1 issues](https://github.com/berraisabdelaziz/craft-helpers/issues)PHPCI failing

Since May 26Pushed 5y ago1 watchersCompare

[ Source](https://github.com/berraisabdelaziz/craft-helpers)[ Packagist](https://packagist.org/packages/berraisabdelaziz/craft-helpers)[ RSS](/packages/berraisabdelaziz-craft-helpers/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Helpers plugin for Craft CMS
============================

[](#helpers-plugin-for-craft-cms)

A collection of Twig functions. this plugin is craft 3 plugin, this plugin is an update of the craft 2 modules

Installation
------------

[](#installation)

The plugin is available on Packagist and can be installed using Composer. You can also download the [latest release](https://github.com/berraisabdelaziz/craft-helpers/releases/latest) and copy the files into craft/plugins/helpers/.

```
$ composer require berraisabdelaziz/craft-helpers

```

File Helpers
------------

[](#file-helpers)

The plugin provides functions, which allow to read and convert JSON, YAML, CSV and PHP file contents. Using the `readText` or `inline` function you can read an entire file into a string.

All functions take a `path` argument, this can be either a relative or absolute path, or full URL to the file. A relative path is interpreted as relative to the web root by default, but this can be changed with the `basePath` config setting.

Here are some ideas for what you can do with reading files:

- read SVG files or “above-the-fold” CSS files and inline them into your templates
- read documents written in markdown that you version control in Git
- read mock data from JSON or YAML files for prototyping
- read Element API endpoints without Ajax requests
- read mapping tables for all sorts of things (keywords to element IDs, keywords to common sets of Atomic CSS classes, …)

#### readJson( path )

[](#readjson-path-)

Reads a JSON file, parses and converts its contents.

- **`path`** (required) – The path to the file to read.

```
{% for article in readJson('https://example.com/api/news') %}
    {{ article.body }}
{% endfor %}
```

#### readYaml( path )

[](#readyaml-path-)

Reads a YAML file, parses and converts its contents.

- **`path`** (required) – The path to the file to read.

```
{% set c = readYaml('tachyons/base.yaml') %}

{# outputs "br-100 pa1 ba b--black-10 h3 w3" #}
```

#### readCsv( path )

[](#readcsv-path-)

Reads a CSV file, parses and converts its contents.

- **`path`** (required) – The path to the file to read.
- **`associative`** (default `true`) – Whether an associative array should be returned for each row. The keys are provided from the first CSV row.

```
{% for customer in readCsv('data/customers.csv') %}
    {{ customer['First Name'] }}
{% endfor %}

{# outputs "Paul Clara Max Thomas Simone" #}
```

#### readPhp( path )

[](#readphp-path-)

Executes a PHP file’s return statement and returns the value.

- **`path`** (required) – The path to the file to read.

```
{% for element in readPhp('data/elements.php') %}
    {{ element.getUrl() }}
{% endfor %}
```

#### readText( path )

[](#readtext-path-)

Reads a file’s contents into a string. The plugin also provides an alias for this function with `inline( path )`.

- **`path`** (required) – The path to the file to read.

```
{{ readText('data/notes.md')|md }}
```

```
{{ inline('assets/svg/logo.svg') }}
```

```
{% set data = inline(url('api/elements.json')) %}

```

String Helpers
--------------

[](#string-helpers)

#### truncate( length, suffix, preserve )

[](#truncate-length-suffix-preserve-)

Truncates a string to a given length.

- **`length`** (default `30`) – The number of characters, beyond which the text should be truncated.
- **`suffix`** (default `'…'`) – The string to be appended if truncating occurs.
- **`preserve`** (default `true`) – Ensures that the filter doesn’t split words.

```
{{ 'This is some very long text and it is causing a lot of problems.'|truncate(30) }}

{# outputs "This is some very long text…" #}
```

#### truncateHtml( length, suffix, preserve )

[](#truncatehtml-length-suffix-preserve-)

A version of the `truncate` filter that is capable of handling HTML as an input string. `truncateHtml` closes HTML tags, if they’d be cut off by the truncation. Please note that its performance is worse than the normal `truncate` filter, so only use it when you need to.

- **`length`** (default `30`) – The number of characters, beyond which the text should be truncated.
- **`suffix`** (default `'…'`) – The string to be appended if truncating occurs.
- **`preserve`** (default `true`) – Ensures that the filter doesn’t split words.

```
{{ 'This is some very long text and it is causing a lot of problems.'|truncateHtml(30) }}

{# outputs "This is some very long text and…" #}
```

#### highlight( terms, format )

[](#highlight-terms-format-)

Highlights given terms in a text.

- **`terms`** (required) – A term or an array of terms that will be searched.
- **`format`** (default `'\1'`) – The replacement string with a backreference to the found term. The default string can be overridden with the `highlightFormat` config setting.

```
{% set terms = 'we craf'|split(' ') %}
{{ 'We just installed Craft!'|highlight(terms) }}

{# outputs "We just installed Craft!" #}
```

#### sentenceList( and, separator )

[](#sentencelist-and-separator-)

Generates a comma separated list from an array of strings, where the last two strings are joined with “and”.

- **`and`** (default `', and '`) – The separator between the last two strings (translatable using [translation files](https://craftcms.com/support/static-translations)).
- **`separator`** (default `', '`) – The separator between the other strings.

```
{% set names = ['Patrick', 'Clarisse', 'Caitlin', 'Danny', 'Loretta'] %}
{{ names|sentenceList }}

{# outputs "Patrick, Clarisse, Caitlin, Danny, and Loretta" #}
```

#### titleize( ignore )

[](#titleize-ignore-)

Returns a string with the first letter of each word capitalized.

- **`ignore`** (default `['the', 'to', ...]`) – A list of words which should not be capitalized. The default list can be overridden with the `titleizeIgnore` config setting.

```
{{ 'i like to watch television'|titleize }}

{# outputs "I Like to Watch Television" #}
```

#### collapseWhitespace

[](#collapsewhitespace)

Trims the string and replaces consecutive whitespace characters with a single space. This includes tabs and newline characters, as well as multibyte whitespace such as the thin space and ideographic space.

```
{{ '     where that  extra whitespace  might come from? '|collapseWhitespace }}

{# outputs "where that extra whitespace might come from?" #}
```

#### stripWords( wordlist, ignoreCase )

[](#stripwords-wordlist-ignorecase-)

Returns the input string stripped from all words of a given list of words.

- **`wordlist`** (required) – The array of words that should get stripped from the input string.
- **`ignoreCase`** (default `true`) – Controls whether case is ignored or respected.

```
{% set string = 'In theory it removes both the A and AN, but not the THE.' %}
{{ string|stripWords(['a', 'an']) }}

{# outputs "In theory it removes both the and , but not the THE." #}
```

#### stripPunctuation

[](#strippunctuation)

Returns the input string stripped from all punctuation.

```
{% set string = 'In theory it removes .,:;*# but not ßøü.' %}
{{ string|stripPunctuation }}

{# outputs "In theory it removes but not ßøü" #}
```

#### htmlEntityDecode

[](#htmlentitydecode)

Returns the input string with all HTML entities converted to their applicable characters.

```
{% set string = 'Ein Anführungszeichen ist <b>fett</b&gt' %}
{{ string|htmlEntityDecode }}

{# outputs "Ein Anführungszeichen ist fett" #}
```

Number Helpers
--------------

[](#number-helpers)

#### numbersToWords( locale )

[](#numberstowords-locale-)

Converts a number to its word representation. The filter uses the Numbers\_Words library to generate the output. Have a look at its documentation for a [list of supported languages](https://github.com/pear/Numbers_Words).

- **`locale`** (default `en_US`) – The language name abbreviation to set the ouput language.

```
{{ 42|numbersToWords('de') }}

{# outputs "zweiundvierzig" #}
```

#### currencyToWords( locale, currency, decPoint)

[](#currencytowords-locale-currency-decpoint)

Converts a currency value to word representation. The filter uses the Numbers\_Words library to generate the output. Have a look at its documentation for a [list of supported languages](https://github.com/pear/Numbers_Words) and currency symbols.

- **`locale`** (default `en_US`) – The language name abbreviation to set the ouput language.
- **`currency`** (default `''`) – The international currency symbol to set the ouput currency.
- **`decPoint`** (default `null`) – The separator for the decimal point.

```
{{ 1700.99|currencyToWords('en_US', 'EUR') }}

{# outputs "one thousand seven hundred euros ninety-nine euro-cents" #}
```

#### numeralSystem( numeralSystem, zero )

[](#numeralsystem-numeralsystem-zero-)

Converts a number (arabic numeral system) to a representation of that number in another numeral system. If applied to a rational number (float), the filter rounds it to the closest integer first.

- **`numeralSystem`** (required) – The numeral system the number gets converted to. You can convert to the roman numberal system (`'roman'`, `'upperRoman'` or `'lowerRoman'`) or to the alphabetical equivalent to the input number (`'alpha'`, `'upperAlpha'` or `'lowerAlpha'`).
- **`zero`** (default `-1`) – Maps all negative numbers and zero. Setting this argument to `-1` gives you a decimal number to alphabetical character mapping like so: `-1` → `-B`, `0` → `-A`, `1` → `A`. Any other argument value other than `-1` or `1` does only map `0` to this value (i.e. `0` → `myZero`) and leaves negative number untouched.

```
{{ 42|numeralSystem('roman') }}

{# outputs "XLII" #}
```

#### unitPrefix( system, decimals, trailingZeros, decPoint, thousandsSep, unitSep)

[](#unitprefix-system-decimals-trailingzeros-decpoint-thousandssep-unitsep)

Formats a number with unit prefixes.

- **`system`** (default `decimal`) – Either a string (e.g. "decimal") to use a predefined configuration or an array of custom settings.
- **`decimals`** (default `1`) – The number of decimal points.
- **`trailingZeros`** (default `false`) – Whether to show trailing zeros.
- **`decPoint`** (default `'.'`) – The separator for the decimal point.
- **`thousandsSep`** (default `''`) – The thousands separator.
- **`unitSep`** (default `' '`) – The separator between number and unit.

```
{{ 72064|unitPrefix }}

{# outputs "72.1 k" #}
```

#### fractionToFloat( precision )

[](#fractiontofloat-precision-)

Converts a fraction to a decimal number.

- **`precision`** (default `4`) – The precision (number of digits after the decimal point) the returned value gets rounded to.

```
{{ '2/3'|fractionToFloat }}

{# outputs "0.6667" #}
```

#### floatToFraction( tolerance )

[](#floattofraction-tolerance-)

Converts a decimal number to a fraction.

- **`tolerance`** (default `0.001`) – The allowed tolerance for the fraction calculation. So, for example, `0.7143` gets converted to `5/7` instead of `7138/9993`.

```
{{ 0.7143|floatToFraction }}

{# outputs "5/7" #}
```

Miscellaneous Helpers
---------------------

[](#miscellaneous-helpers)

#### randomString( length, extendedChars )

[](#randomstring-length-extendedchars-)

Generates a random string of a given length.

- **`length`** (default `36`) – The length of the generated string.
- **`extendedChars`** (default `false`) – Whether to use an extended set of characters.

```
{{ randomString(6) }}

{# outputs "mRU1wI" #}
```

#### md5( string )

[](#md5-string-)

Generates the md5 hash of a string.

- **`string`** (required) – The string to generate the hash from.

```
{% set string = 'Lorem ipsum dolor sit amet.' %}
{{ string|md5 }}

{# outputs "eb76f38646cca9420296bfc6731f94b5" #}
```

#### json\_decode( assoc, depth, options )

[](#json_decode-assoc-depth-options-)

Decodes a JSON string.

- **`assoc`** (default `false`) – Whether objects should be converted into associative arrays.
- **`depth`** (default `512`) – The recursion depth.
- **`options`** (default `null`) – Bitmask of JSON decode options.

```
{% set json = '{"beers":["Alpirsbacher Klosterbräu","Rothaus Tannenzäpfle","Neumarkter Lammsbräu"],"whiskeys":null}' %}
{% set drinks = json|json_decode() %}

{{ drinks.beers[1] }}

{# outputs "Rothaus Tannenzäpfle" #}
```

#### setNotice( message )

[](#setnotice-message-)

Stores a notice in the user’s flash data.

- **`message`** (required) – The message.

```
{% do setNotice('My short message.') %}
{{ craft.session.getFlash('notice') }}

{# outputs "My short message." #}
```

#### setError( message )

[](#seterror-message-)

Stores an error message in the user’s flash data.

- **`message`** (required) – The message.

```
{% do setError('Do panic!') %}
{{ craft.session.getFlash('error') }}

{# outputs "Do panic!" #}
```

Settings
--------

[](#settings)

You can override plugin defaults with a helpers.php config file, which you need to create in your craft/config/ folder.

```