Skip to content

Commit

Permalink
Updated basic Zend\View docs
Browse files Browse the repository at this point in the history
  • Loading branch information
padraic committed Jul 5, 2012
1 parent bf1076e commit 2478e7a
Show file tree
Hide file tree
Showing 4 changed files with 38 additions and 52 deletions.
4 changes: 2 additions & 2 deletions documentation/manual/en/module_specs/zend.view.helpers.xml
Original file line number Diff line number Diff line change
Expand Up @@ -280,7 +280,7 @@ I have seen 'The Jerk' 3 time(s).
script as part of your helper. This is why we define the
<methodname>setView()</methodname> and <methodname>getView()</methodname> methods. As an
example, we could rewrite the <classname>SpecialPurpose</classname> helper as follows to
take advantage of the <classname>Escape</classname> helper:
take advantage of the <classname>EscapeHtml</classname> helper:
</para>

<programlisting language="php"><![CDATA[
Expand All @@ -296,7 +296,7 @@ class SpecialPurpose extends AbstractHelper
{
$this->count++;
$output = sprintf("I have seen 'The Jerk' %d time(s).", $this->count);
$escaper = $this->getView()->plugin('escape');
$escaper = $this->getView()->plugin('escapehtml');
return $escaper($output);
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,8 @@
<?php foreach ($this->books as $key => $val): ?>
<tr>
<td><?php echo $this->escape($val['author']) ?></td>
<td><?php echo $this->escape($val['title']) ?></td>
<td><?php echo $this->escapeHtml($val['author']) ?></td>
<td><?php echo $this->escapeHtml($val['title']) ?></td>
</tr>
<?php endforeach; ?>
Expand All @@ -90,59 +90,31 @@
One of the most important tasks to perform in a view script is to make sure that output
is escaped properly; among other things, this helps to avoid cross-site scripting
attacks. Unless you are using a function, method, or helper that does escaping on its
own, you should always escape variables when you output them.
own, you should always escape variables when you output them and pay careful attention
to applying the correct escaping strategy to each HTML context you use.
</para>

<para>
The <classname>PhpRenderer</classname> includes an <classname>Escape</classname> helper
you can utilize for this purpose.
The <classname>PhpRenderer</classname> includes a selection of helpers you can use for
this purpose: <classname>EscapeHtml</classname>, <classname>EscapeHtmlAttr</classname>
<classname>EscapeJs</classname>, <classname>EscapeCss</classname>, and
<classname>EscapeUrl</classname>. Matching the correct helper (or combination of
helpers) to the context into which you are injecting untrusted variables will ensure
that you are protected against Cross-Site Scripting (XSS) vulnerabilities.
</para>

<programlisting language="php"><![CDATA[
// bad view-script practice:
echo $this->variable;
// good view-script practice:
echo $this->escape($this->variable);
]]></programlisting>

<para>
By default, the escape() method uses the <acronym>PHP</acronym>
<function xlink:href="http://php.net/htmlspecialchars">htmlspecialchars()</function> function for escaping, using UTF-8 as the
characterset, and the <constant>ENT_QUOTES</constant> setting. However, depending on
your environment, you may wish for escaping to occur in a different way. You may change
either the encoding or callback used, using the <methodname>setEncoding()</methodname>
or <methodname>setCallback()</methodname> method of the helper.
</para>

<programlisting language="php"><![CDATA[
// $view is a PhpRenderer instance
$escaper = $view->plugin('escape');
echo $this->escapeHtml($this->variable);
// specify a different encoding to use for the default htmlspecialchars usage
$escaper->setEncoding('ISO-8859-1');
// tell it to use htmlentities as the escaping callback
$escaper->setCallback('htmlentities');
// or tell it to use a static class method as the callback
$escaper->setCallback(array('SomeClass', 'methodName'));
// or an instance method
$obj = new SomeClass();
$escaper->setCallback(array($obj, 'methodName'));
// or use a closure to curry arguments to another function,
// or inline an escaping mechanism.
$escaper->setCallback(function ($value) {
$value = str_rot13($value);
return base64_encode($value);
});
// and remember context is always relevant!
<script type="text/javascript">
var foo = "<?php echo $this->escapeJs($variable) ?>";
</script>
]]></programlisting>

<para>
The callback function or method should take the value to be escaped as its first
parameter, and all other parameters should be optional.
</para>
</section>
</section>
Original file line number Diff line number Diff line change
Expand Up @@ -424,7 +424,7 @@ class ArticleController extends AbstractActionController
<!-- This is from the $articleView view model, and the "content/article"
template -->
<article class="twelve columns">
<?php echo $this->escape('article') ?>
<?php echo $this->escapeHtml('article') ?>
</article>
<?php // "content/main-sidebar template ?>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -292,8 +292,8 @@ $renderer->render($model);
<?php foreach ($this->books as $key => $val): ?>
<tr>
<td><?php echo $this->escape($val['author']) ?></td>
<td><?php echo $this->escape($val['title']) ?></td>
<td><?php echo $this->escapeHtml($val['author']) ?></td>
<td><?php echo $this->escapeHtml($val['title']) ?></td>
</tr>
<?php endforeach; ?>
Expand All @@ -309,17 +309,31 @@ $renderer->render($model);
<note xml:id="zend.view.renderer.php-renderer.usage.escape">
<title>Escape Output</title>



<para>
The security mantra is "Filter input, escape output." If you are unsure of the
source of a given variable -- which is likely most of the time -- you should escape
it.
it based on which HTML context it is being injected into. The primary contexts to
be aware of are HTML Body, HTML Attribute, Javascript, CSS and URI. Each context
has a dedicated helper available to apply the escaping strategy most appropriate to
each context. You should be aware that escaping does vary significantly between
contexts - there is no one single escaping strategy that can be globally applied.
</para>

<para>
In the example above, there are calls to an <methodname>escape()</methodname>
In the example above, there are calls to an <methodname>escapeHtml()</methodname>
method. The method is actually a <link linkend="zend.view.helpers">helper</link>,
a plugin available via method overloading, but the salient point is: use it to
escape your output, and thus help prevent cross-site scripting (XSS) attacks.
a plugin available via method overloading. Additional escape helpers provide the
<methodname>escapeHtmlAttr()</methodname>, <methodname>escapeJs()</methodname>,
<methodname>escapeCss()</methodname>, and <methodname>escapeUrl()</methodname>
methods for each of the HTML contexts you are most likely to encounter.
</para>

<para>
By using the provided helpers and being aware of your variables' contexts, you
will prevent your templates from running afoul of Cross-Site Scripting (XSS)
vulnerabilities.
</para>
</note>

Expand Down

0 comments on commit 2478e7a

Please sign in to comment.