29

I'm aware Magento 2 has several methods available to secure the template:

  • $block->escapeHtml()
  • $block->escapeQuote()
  • $block->escapeUrl()
  • $block->escapeXssInUrl()

But I'm wondering when to use each of those methods ?

35

The escaping methods in AbstractBlock all delegate calls to Magento\Framework\Escaper, so you'll find an overview there.

Let's look at the public methods and their documentation:

escapeHtml()

/**
 * Escape string for HTML context. allowedTags will not be escaped, except the following: script, img, embed,
 * iframe, video, source, object, audio
 *
 * @param string|array $data
 * @param array|null $allowedTags
 * @return string|array
 */
public function escapeHtml($data, $allowedTags = null)

This should be your default escaping method for any output. Convention is that the result of all methods that do not contain "Html" must be escaped.

escapeHtmlAttr()

(since Magento 2.2)

/**
 * Escape a string for the HTML attribute context
 *
 * @param string $string
 * @param boolean $escapeSingleQuote
 * @return string
 */
public function escapeHtmlAttr($string, $escapeSingleQuote = true)

Use this to escape output within a HTML attribute, for example

title="<?php echo $block->escapeHtmlAttr($title) ?>"

It will escape HTML, but also quotes (")

By default, it will also escape single quotes, so this works too:

onclick="alert('<?php echo $block->escapeHtmlAttr($message) ?>')"

Set the second parameter to false if this is not desired.

escapeUrl()

/**
 * Escape URL
 *
 * @param string $string
 * @return string
 */
public function escapeUrl($string)

This can be used to output URLs. It will apply the default HTML escaping and additionally removes javascript:, vbscript: and data:. If you want to prevent URLs like this in user provided links, you can use the method.

Until Magento 2.1 this feature was not included and you needed to use escapeXssInUrl() instead. There was no reason to use escapeUrl() at all.

Otherwise, just use $block->escapeHtmlAttr() for URLs.

encodeUrlParam()

(since Magento 2.2)

/**
 * Encode URL
 *
 * @param string $string
 * @return string
 */
public function encodeUrlParam($string)

This applies URL encoding to parameters. For internal URLs you should always use getUrl(), where URL encoding is already done for you, so this is only necessary if you manually construct an external URL.

escapeJs()

(since Magento 2.2)

/**
 * Escape string for the JavaScript context
 *
 * @param string $string
 * @return string
 */
public function escapeJs($string)

Encodes unicode characters for JavaScript, for example becomes \u2665. Use it to escape output within a JS string. For inline Javascript (i.e. onclick attributes), you still need to call escapeHtmlAttr().

Note that if you use json_encode(), it already does the same escaping, in this case, escapeJs() must not be used.

escapeCss()

(since Magento 2.2)

/**
 * Escape string for the CSS context
 *
 * @param string $string
 * @return string
 */
public function escapeCss($string)

Encodes unicode characters for CSS (see escapeJs()), for example to be used in the content CSS attribute.

Deprecated methods (as of Magento 2.2):

  • escapeJsQuote: Use escapeHtmlAttr() instead
  • escapeXssInUrl: Use escapeUrl() instead
  • escapeQuote: Use escapeHtmlAttr() instead
  • 1
    Good job I've added a little note to my answer to refer to yours when using 2.1. Interestingly, the Magento U couse only mentions the methods I've mentionned in my answer. I guess the course is 2.0 only – Raphael at Digital Pianism Jan 26 '17 at 8:09
  • escapeHtmlAttr and escapeHtmlAttr doesn't exist in 2.1.2 ... at least not in /vendor/magento/framework/Escaper.php unless they've added it later and re-tagged magento .. – OZZIE Feb 2 '17 at 14:07
  • 2
    Good catch, my answer actually was based on the latest develop branch. According to the devdocs, the other methods will be deprecated from 2.2 – Fabian Schmengler Feb 2 '17 at 14:39
  • Is there a method that can be used to clean an arbitrary chunk of html that might need to have an img tag in it? – Corgalore Nov 9 '18 at 21:02
  • Clean in which sense? – Fabian Schmengler Nov 9 '18 at 23:28
14

This is for Magento 2.0. For 2.1, refer to Fabian's answer

escapeHtml

Use this function in the case of a string output that should not contain HTML.

Example:

<span class='label'><?php echo $block->escapeHtml($block->getLabel()); ?></span>

escapeQuote

Use this function in the case of HTML attributes

Example:

<span class="<?php echo $block->escapeQuote($block->getSpanClass()); ?>">Description</span>

escapeUrl

Use this function in case of an URL output (without XSS prevention - only character conversion)

Example:

<a href="<?php echo $block->escapeUrl($block->getUrl()); ?>">Link</a>

escapeXssInUrl

Use this function in case of an URL output (with XSS prevention - including character conversation)

Example:

<a href="<?php echo $block->escapeXssInUrl($block->getUrl()); ?>">Link</a>

What does not need escaping ?

  • Type casting and php function count() (example echo (int)$var)
  • Output in single quotes (example echo 'test')
  • Output in double quotes without variables (example echo "test")

The __ method

This one is used for translation purposes. Use it when you know a string can be translated.

For example:

<caption class="table-caption"><?php /* @escapeNotVerified */ echo __('More Information') ?></caption>
  • good job.. rapheal – Amit Bera Jan 25 '17 at 10:13
  • 1
    Should we escape every translation __() too? I'm a bit tired of pasting /* @escapeNotVerified */ everywhere :/ – igloczek Jan 25 '17 at 10:20
  • @BartekIgielski see my updated answer. __ is not for security purpose but for translation purpose – Raphael at Digital Pianism Jan 25 '17 at 10:23
  • 1
    Also I recommend to escape translated strings, like echo $this->escapeHtml(__('Text to translate')) – KAndy Jan 25 '17 at 11:04
  • 2
    There is currently a note on the devdocs page that some methods will be deprecated with 2.2. Make sure to check back on the template security page. devdocs.magento.com/guides/v2.0/frontend-dev-guide/templates/… – Anna Völkl Jan 29 '17 at 17:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.