<commit_before>.. _zend.escaper.theory-of-operation:

Theory of Operation
===================

``Zend\Escaper`` provides methods for escaping output data, dependent on the context in which the data will be used.
Each method is based on peer-reviewed rules and is in compliance with the current OWASP recommendations.

The escaping follows a well known and fixed set of encoding rules for each key HTML context, which are defined by
OWASP. These rules cannot be impacted or negated by browser quirks or edge-case HTML parsing unless the browser 
suffers a catastrophic bug in it's HTML parser or Javascript interpreter - both of these are unlikely.

The contexts in which ``Zend\Escaper`` should be used are **HTML Body**, **HTML Attribute**, **Javascript**, **CSS**
and **URL/URI** contexts.

.. _zend.escaper.theory-of-operation.problem-with-inconsistent-functionality

The Problem with Inconsistent Functionality
-------------------------------------------

At present, programmers orient towards the following PHP functions for each common HTML context:

 - **HTML Body**: htmlspecialchars() or htmlentities()
 - **HTML Attribute**: htmlspecialchars() or htmlentities()
 - **Javascript**: addslashes() or json_encode()
 - **CSS**: n/a
 - **URL/URI**: rawurlencode() or urlencode()<commit_msg>try to explain a bit how the escaper works<commit_after>.. _zend.escaper.theory-of-operation:

Theory of Operation
===================

``Zend\Escaper`` provides methods for escaping output data, dependent on the context in which the data will be used.
Each method is based on peer-reviewed rules and is in compliance with the current OWASP recommendations.

The escaping follows a well known and fixed set of encoding rules for each key HTML context, which are defined by
OWASP. These rules cannot be impacted or negated by browser quirks or edge-case HTML parsing unless the browser 
suffers a catastrophic bug in it's HTML parser or Javascript interpreter - both of these are unlikely.

The contexts in which ``Zend\Escaper`` should be used are **HTML Body**, **HTML Attribute**, **Javascript**, **CSS**
and **URL/URI** contexts.

Every escaper method will take the data to be escaped, make sure it is utf-8 encoded data, or try to convert it to
utf-8, do the context-based escaping, encode the escaped data back to it's original encoding and return the data to
the caller.

The actual escaping of the data differs between each method, they all have their own set of rules according to which
the escaping is done. An example will allow us to clearly demonstrate the difference, and how the
same characters are being escaped differently between contexts:

.. code-block:: php
    :linenos:

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

    // &lt;script&gt;alert(&quot;zf2&quot;)&lt;/script&gt;
    echo $escaper->escapeHtml('<script>alert("zf2")</script>');
    // &lt;script&gt;alert&#x28;&quot;zf2&quot;&#x29;&lt;&#x2F;script&gt;
    echo $escaper->escapeHtmlAttr('<script>alert("zf2")</script>');
    // \x3Cscript\x3Ealert\x28\x22zf2\x22\x29\x3C\x2Fscript\x3E
    echo $escaper->escapeJs('<script>alert("zf2")</script>');
    // \3C script\3E alert\28 \22 zf2\22 \29 \3C \2F script\3E 
    echo $escaper->escapeCss('<script>alert("zf2")</script>');
    // %3Cscript%3Ealert%28%22zf2%22%29%3C%2Fscript%3E
    echo $escaper->escapeUrl('<script>alert("zf2")</script>');


More detailed examples will be given in later chapters.

.. _zend.escaper.theory-of-operation.problem-with-inconsistent-functionality

The Problem with Inconsistent Functionality
-------------------------------------------

At present, programmers orient towards the following PHP functions for each common HTML context:

 - **HTML Body**: htmlspecialchars() or htmlentities()
 - **HTML Attribute**: htmlspecialchars() or htmlentities()
 - **Javascript**: addslashes() or json_encode()
 - **CSS**: n/a
 - **URL/URI**: rawurlencode() or urlencode()
{'fraction_non_alphanumeric': 0.13837920489296637, 'fraction_numerical': 0.01452599388379205, 'mean_word_length': 4.212483399734396, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 18, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5935162', 'n_tokens_mistral': 1167, 'n_tokens_neox': 1087, 'n_words': 441}