diff --git a/doc/book/helpers/escape.md b/doc/book/helpers/escape.md new file mode 100644 index 00000000..e38fbb60 --- /dev/null +++ b/doc/book/helpers/escape.md @@ -0,0 +1,248 @@ +# 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, +zend-view provides the following helpers: + +* [`EscapeCss`](#escapecss) +* [`EscapeHtml`](#escapehtml) +* [`EscapeHtmlAttr`](#escapehtmlattr) +* [`EscapeJs`](#escapejs) +* [`EscapeUrl`](#escapeurl) + +More informations to the operation and the background of security can be found +in the +[documentation of zend-escaper](https://docs.zendframework.com/zend-escaper/configuration/). + +> ### Installation Requirements +> +> The escape helpers depends on the zend-escaper component, so be sure to have +> it installed before getting started: +> +> ```bash +> $ composer require zendframework/zend-escaper +> ``` + +## EscapeCss + +```php +$css = <<'); +} +CSS; + +echo $this->escapeCss($css); +``` + +Output: + +```css +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 + +```php +$html = ""; + +echo $this->escapeHtml($html); +``` + +Output: + +```html +<script>alert('zend-framework')</script> +``` + +## EscapeHtmlAttr + +```php+html + + +escapeHtmlAttr($html) ?>>click +``` + +Output: + +```html +click +``` + +## EscapeJs + +```php +$js = "window.location = 'https://framework.zend.com/?cookie=' + document.cookie"; + +echo $this->escapeJs($js); +``` + +Output: + +```js +window.location\x20\x3D\x20\x27https\x3A\x2F\x2Fframework.zend.com\x2F\x3Fcookie\x3D\x27\x20\x2B\x20document.cookie +``` + +## EscapeUrl + +```php + + +click +``` + +Output: + +```html +click +``` + +## Using Encoding + +```php +$this->escapeHtml()->setEncoding('iso-8859-15'); +``` + +All allowed encodings can be found in the +[documentation of zend-escaper](https://docs.zendframework.com/zend-escaper/configuration/). + +### Get Current Value + +To get the current value of this option, use the `getEncoding()` method. + +```php +$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: + +```php +$html = [ + 'headline' => '

Foo

', + 'content' => [ + 'paragraph' => '

Bar

', + ], +]; + +var_dump($this->escapeHtml($html, Zend\View\Helper\EscapeHtml::RECURSE_ARRAY)); +``` + +Output: + +```php +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: + +```php +$object = new class { + public function __toString() : string + { + return '

Foo

'; + } +}; + +echo $this->escapeHtml($object); // "<h1>Foo</h1>" +``` + +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: + +```php +$object = new class { + public function toArray() : array + { + return ['headline' => '

Foo

']; + } +}; + +var_dump($this->escapeHtml($object, Zend\View\Helper\EscapeHtml::RECURSE_OBJECT)); +``` + +Output: + +```php +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`: + +```php +$object = new class { + public $headline = '

Foo

'; +}; + +var_dump($this->escapeHtml($object, Zend\View\Helper\EscapeHtml::RECURSE_OBJECT)); +``` + +Output: + +```php +array(1) { + 'headline' => + string(3) "<h1>Foo</h1>" +} +``` + +## Using Custom Escaper + +Create an own instance of `Zend\Escaper\Escaper` and set to any of the escape +helpers: + +```php +$escaper = new Zend\Escaper\Escaper('utf-8'); + +$this->escapeHtml()->setEscaper($escaper); +``` + +### Get Current Value + +To get the current value, use the `getEscaper()` method. + +```php +escapeHtml()->setEscaper($escaper); + +var_dump($this->escapeHtml()->getEscaper()); // instance of Zend\Escaper\Escaper +``` + +### Default Value + +The default value is an instance of `Zend\Escaper\Escaper`, created by the +helper. diff --git a/mkdocs.yml b/mkdocs.yml index fd188f24..8e7493f3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ pages: - BasePath: helpers/base-path.md - Cycle: helpers/cycle.md - Doctype: helpers/doctype.md + - Escape: helpers/escape.md - FlashMessenger: helpers/flash-messenger.md - Gravatar: helpers/gravatar.md - HeadLink: helpers/head-link.md