ExpressionEngine® 3 User Guide

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


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.

  • $formatter_name (string) – Formatter name
  • $content (mixed) – The content to be formatted

A Formatter object

Return type:


All Formatters

class EllisLab\ExpressionEngine\Service\Formatter\Formatter

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.

Return type:The content

When accessed as a string simply complile the content and return that.

Return type:The content


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.

  • $abbr (bool) – Use the abbreviated form of the byte format
  • $include_markup (bool) – Output with <abbr> HTML. Only affects abbreviated forms.

A Formatter object

Return type:


Text Formatter

class EllisLab\ExpressionEngine\Service\Formatter\Formats\Text

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:

  'form.some_input.value' => ee('Format')->make('String', $content)->attribute_escape()->compile()