Helpers

Escape

The following helpers can escape output in view scripts and defend from XSS and related vulnerabilities. To escape different contexts of a HTML document, laminas-view provides the following helpers:

• EscapeCss
• EscapeHtml
• EscapeHtmlAttr
• EscapeJs
• EscapeUrl

More information to the operation and the background of security can be found in the documentation of laminas-escaper.

Installation Requirements

The escape helpers depends on the laminas-escaper component, so be sure to have it installed before getting started:

$ composer require laminas/laminas-escaper

EscapeCss

$css = <<<CSS
body {
    background-image: url('http://example.com/foo.jpg?</style><script>alert(1)</script>');
}
CSS;

echo $this->escapeCss($css);

Output:

body\20 \7B \D \A \20 \20 \20 \20 background\2D image\3A \20 url\28 \27 http\3A \2F \2F example\2E com\2F foo\2E jpg\3F \3C \2F style\3E \3C script\3E alert\28 1\29 \3C \2F script\3E \27 \29 \3B \D \A \7D

EscapeHtml

$html = "<script>alert('laminas-framework')</script>";

echo $this->escapeHtml($html);

Output:

<script>alert('laminas-framework')</script>

EscapeHtmlAttr

<?php $html = 'faketitle onmouseover=alert(/laminas-framework/);'; ?>

<a title=<?= $this->escapeHtmlAttr($html) ?>>click</a>

Output:

<a title=faketitle&#x20;onmouseover&#x3D;alert&#x28;&#x2F;laminas-framework&#x2F;&#x29;&#x3B;>click</a>

EscapeJs

$js = "window.location = 'https://getlaminas.org/?cookie=' + document.cookie";

echo $this->escapeJs($js);

Output:

window.location\x20\x3D\x20\x27https\x3A\x2F\x2Fgetlaminas.org\x2F\x3Fcookie\x3D\x27\x20\x2B\x20document.cookie

EscapeUrl

<?php
$url = <<<JS
" onmouseover="alert('laminas')
JS;
?>

<a href="http://example.com/?name=<?= $this->escapeUrl($url) ?>">click</a>

Output:

<a href="http://example.com/?name=%22%20onmouseover%3D%22alert%28%27laminas%27%29">click</a>

Using Encoding

$this->escapeHtml()->setEncoding('iso-8859-15');

All allowed encodings can be found in the documentation of laminas-escaper.

Get Current Value

To get the current value of this option, use the getEncoding() method.

$this->escapeHtml()->setEncoding('iso-8859-15');

echo $this->escapeHtml()->getEncoding(); // iso-8859-15

Default Value

The default value for all escape helpers is utf-8.

Using Recursion

All escape helpers can use recursion for the given values during the escape operation. This allows the escaping of the datatypes array and object.

Escape an Array

To escape an array, the second parameter $recurse must be use the constant RECURSE_ARRAY of an escape helper:

$html = [
    'headline' => '<h1>Foo</h1>',
    'content'  => [
        'paragraph' => '<p>Bar</p>',
    ],
];

var_dump($this->escapeHtml($html, Laminas\View\Helper\EscapeHtml::RECURSE_ARRAY));

Output:

array(2) {
  'headline' =>
  string(24) "<h1>Foo</h1>"
  'content' =>
  array(1) {
    'paragraph' =>
    string(22) "<p>Bar</p>"
  }
}

Escape an Object

An escape helper can use the __toString() method of an object. No additional parameter is needed:

$object = new class {
    public function __toString() : string
    {
        return '<h1>Foo</h1>';
    }
};

echo $this->escapeHtml($object); // "&lt;h1&gt;Foo&lt;/h1&gt;"

An escape helper can also use the toArray() method of an object. The second parameter $recurse must be use the constant RECURSE_OBJECT of an escape helper:

$object = new class {
    public function toArray() : array
    {
        return ['headline' => '<h1>Foo</h1>'];
    }
};

var_dump($this->escapeHtml($object, Laminas\View\Helper\EscapeHtml::RECURSE_OBJECT));

Output:

array(1) {
  'headline' =>
  string(3) "<h1>Foo</h1>"
}

If the object does not contains the methods __toString() or toArray() then the object is casted to an array:

$object = new class {
    public $headline = '<h1>Foo</h1>';
};

var_dump($this->escapeHtml($object, Laminas\View\Helper\EscapeHtml::RECURSE_OBJECT));

Output:

array(1) {
  'headline' =>
  string(3) "<h1>Foo</h1>"
}

Using Custom Escaper

Create an own instance of Laminas\Escaper\Escaper and set to any of the escape helpers:

$escaper = new Laminas\Escaper\Escaper('utf-8');

$this->escapeHtml()->setEscaper($escaper);

Get Current Value

To get the current value, use the getEscaper() method.

<?php
$escaper = new Laminas\Escaper\Escaper('utf-8');
$this->escapeHtml()->setEscaper($escaper);

var_dump($this->escapeHtml()->getEscaper()); // instance of Laminas\Escaper\Escaper

Default Value

The default value is an instance of Laminas\Escaper\Escaper, created by the helper.