Download the PHP package carlcs/craft-helpers without Composer
On this page you can find all versions of the php package carlcs/craft-helpers. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package craft-helpers
Helpers plugin for Craft CMS
A collection of Twig functions.
Installation
The plugin is available on Packagist and can be installed using Composer. You can also download the latest release and copy the files into craft/plugins/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 )
Reads a JSON file, parses and converts its contents.
path
(required) – The path to the file to read.
readYaml( path )
Reads a YAML file, parses and converts its contents.
path
(required) – The path to the file to read.
readCsv( path )
Reads a CSV file, parses and converts its contents.
path
(required) – The path to the file to read.associative
(defaulttrue
) – Whether an associative array should be returned for each row. The keys are provided from the first CSV row.
readPhp( path )
Executes a PHP file’s return statement and returns the value.
path
(required) – The path to the file to read.
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.
String Helpers
truncate( length, suffix, preserve )
Truncates a string to a given length.
length
(default30
) – The number of characters, beyond which the text should be truncated.suffix
(default'…'
) – The string to be appended if truncating occurs.preserve
(defaulttrue
) – Ensures that the filter doesn’t split words.
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
(default30
) – The number of characters, beyond which the text should be truncated.suffix
(default'…'
) – The string to be appended if truncating occurs.preserve
(defaulttrue
) – Ensures that the filter doesn’t split words.
highlight( terms, format )
Highlights given terms in a text.
terms
(required) – A term or an array of terms that will be searched.format
(default'<mark>\1</mark>'
) – The replacement string with a backreference to the found term. The default string can be overridden with thehighlightFormat
config setting.
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).separator
(default', '
) – The separator between the other strings.
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 thetitleizeIgnore
config setting.
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.
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
(defaulttrue
) – Controls whether case is ignored or respected.
stripPunctuation
Returns the input string stripped from all punctuation.
htmlEntityDecode
Returns the input string with all HTML entities converted to their applicable characters.
Number Helpers
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.
locale
(defaulten_US
) – The language name abbreviation to set the ouput language.
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 and currency symbols.
locale
(defaulten_US
) – The language name abbreviation to set the ouput language.currency
(default''
) – The international currency symbol to set the ouput currency.decPoint
(defaultnull
) – The separator for the decimal point.
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
or1
does only map0
to this value (i.e.0
→myZero
) and leaves negative number untouched.
unitPrefix( system, decimals, trailingZeros, decPoint, thousandsSep, unitSep)
Formats a number with unit prefixes.
system
(defaultdecimal
) – Either a string (e.g. "decimal") to use a predefined configuration or an array of custom settings.decimals
(default1
) – The number of decimal points.trailingZeros
(defaultfalse
) – 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.
fractionToFloat( precision )
Converts a fraction to a decimal number.
precision
(default4
) – The precision (number of digits after the decimal point) the returned value gets rounded to.
floatToFraction( tolerance )
Converts a decimal number to a fraction.
tolerance
(default0.001
) – The allowed tolerance for the fraction calculation. So, for example,0.7143
gets converted to5/7
instead of7138/9993
.
Miscellaneous Helpers
randomString( length, extendedChars )
Generates a random string of a given length.
length
(default36
) – The length of the generated string.extendedChars
(defaultfalse
) – Whether to use an extended set of characters.
md5( string )
Generates the md5 hash of a string.
string
(required) – The string to generate the hash from.
json_decode( assoc, depth, options )
Decodes a JSON string.
assoc
(defaultfalse
) – Whether objects should be converted into associative arrays.depth
(default512
) – The recursion depth.options
(defaultnull
) – Bitmask of JSON decode options.
setNotice( message )
Stores a notice in the user’s flash data.
message
(required) – The message.
setError( message )
Stores an error message in the user’s flash data.
message
(required) – The message.
Settings
You can override plugin defaults with a helpers.php config file, which you need to create in your craft/config/ folder.
basePath
The basePath
is used by the inline
and file reading functions. The default setting uses the value of your BASE_PATH
environment variable if you have that set, otherwise falls back your the web root. You can override it with something like, for example CRAFT_CONFIG_PATH.'data/'
.
highlightFormat
A setting for the highlight
filter, which defines how matched terms are replaced. The term itself is available from the \1
backreference.
titleizeIgnore
List of words which should not be capitalized by the titleize
filter.
Requirements
- PHP 5.4+
All versions of craft-helpers with dependencies
php Version >=5.4.0
danielstjules/stringy Version ^3.1
kwn/number-to-words Version ^1.3
league/csv Version ^8.2
symfony/yaml Version ^3.3