Legacy Documentation
You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.
Format Service¶
Overview¶
The Format service offers a number of common formatting tasks as a convenience and consolidated way for ExpressionEngine handles these tasks. The Formatter handles common string and number presentational needs.
$display_size = ee('Format')->make('Number', $content)->bytes();
The Format service is a factory to the various formatters available. If you need the factory, use ee('Format'). If you need a Formatter, use ee('Format')->make($formatter, $content).
Format Factory¶
-
class
EllisLab\ExpressionEngine\Service\Formatter\FormatterFactory¶
-
EllisLab\ExpressionEngine\Service\Formatter\FormatterFactory::make($formatter_name, $content)¶ Makes a Formatter object.
Parameters: - $formatter_name (string) – Formatter name
- $content (mixed) – The content to be formatted
Returns: A Formatter object
Return type: Formatter
All Formatters¶
-
class
EllisLab\ExpressionEngine\Service\Formatter\Formatter¶
-
EllisLab\ExpressionEngine\Service\Formatter\Formatter::compile()¶ Compiles and returns the content as a string. Typically this is used when you need to use a content as an array key, or want to json_encode() the content.
Returns: string Return type: The content
-
EllisLab\ExpressionEngine\Service\Formatter\Formatter::__toString()¶ When accessed as a string simply complile the content and return that.
Returns: string Return type: The content
Note
When using Formatters, if you just need the string and not the object for further processing, you can use PHP’s type casting:
$array = array('size' => (string) ee('Format')->make('Number', $content)->bytes());
Number Formatter¶
-
class
EllisLab\ExpressionEngine\Service\Formatter\Formats\Number¶
-
EllisLab\ExpressionEngine\Service\Formatter\Formats\Number::bytes($abbr = TRUE, $include_markup = TRUE)¶ Formats a binary byte multiple into a human-readable measure of units, e.g. B, KB, MB, GB.
Parameters: - $abbr (bool) – Use the abbreviated form of the byte format
- $include_markup (bool) – Output with
<abbr>HTML. Only affects abbreviated forms.
Returns: A Formatter object
Return type: object
Text Formatter¶
-
class
EllisLab\ExpressionEngine\Service\Formatter\Formats\Text¶
-
EllisLab\ExpressionEngine\Service\Formatter\Formats\Text::attributeEscape()¶ Escapes a string for use in an HTML attribute.
Returns: A Formatter object Return type: object
When to use compile()¶
The Formatter object has a magic __toString() method that compiles the object
into a string when the object is treated as a string (see: PHP’s documentation
on the magic __toString() method for more
information). The compile() method exists for those occasions when the
object is treated as an object but you need a string instead. As per PHP’s
documentation on arrays:
“Arrays and objects can not be used as keys. Doing so will result in a warning:
Illegal offset type.” You will also want to compile the object when you want
to JSON encode the content otherwise you will get a JSON object instead of a string.
For example:
ee()->javascript->set_global(array(
'form.some_input.value' => ee('Format')->make('String', $content)->attribute_escape()->compile()
));