',
$div_id);
@{function:hsprintf} can be especially useful when:
- You need to build a block with a lot of tags, like a table with rows and
cells.
- You need to build part of a tag (usually you should avoid this, but if you
do need to, @{function@libphutil:phutil_tag} can not do it).
Note that it is unsafe to provide any user-controlled data to the first
parameter of @{function@libphutil:hsprintf} (the `sprintf()`-style pattern).
Like @{function@libphutil:phutil_tag}, this function returns a
@{class@libphutil:PhutilSafeHTML} object.
= Composing Tags =
When you are building a view which combines smaller components, like a section
with a header and a body:
$header = phutil_tag('h1', ...);
$body = phutil_tag('p', ...);
...you should NOT use string concatenation:
COUNTEREXAMPLE
// Not dangerous, but does the wrong thing.
phutil_tag('div', array(), $header.$body);
Instead, use an array:
// Render a tag containing other tags safely.
phutil_tag('div', array(), array($header, $body));
If you concatenate @{class@libphutil:PhutilSafeHTML} objects, they revert to
normal strings and are no longer marked as properly escaped tags.
(In the future, these objects may stop converting to strings, but for now they
must to maintain backward compatibility.)
If you need to build a list of items with some element in between each of them
(like a middot, comma, or vertical bar) you can use
@{function:phutil_implode_html}:
// Render links with commas between them.
phutil_tag(
'div',
array(),
phutil_implode_html(', ', $list_of_links));
= AphrontView Classes =
Subclasses of @{class:AphrontView} in Phabricator should return a
@{class@libphutil:PhutilSafeHTML} object. The easiest way to do this is to
return `phutil_tag()` or `javelin_tag()`:
return phutil_tag('div', ...);
You can use an @{class:AphrontView} subclass like you would a tag:
phutil_tag('div', array(), $view);
= Internationalization: pht() =
The @{function:pht} function has some special rules. If any input to
@{function:pht} is a @{class@libphutil:PhutilSafeHTML} object, @{function:pht}
returns a @{class@libphutil:PhutilSafeHTML} object itself. Otherwise, it returns
normal text.
This is generally safe because translations are not permitted to have more tags
than the original text did (so if the original text had no tags, translations
can not add any).
Normally, this just means that @{function:pht} does the right thing and behaves
like you would expect, but it is worth being aware of.
= Special Cases =
NOTE: This section describes dangerous methods which can bypass XSS protections.
If possible, do not use them.
You can build @{class@libphutil:PhutilSafeHTML} out of a string explicitly by
calling @{function:phutil_safe_html} on it. This is **dangerous**, because if
you are wrong and the string is not actually safe, you have introduced an XSS
vulnerability. Consequently, you should avoid calling this if possible.
You can use @{function@libphutil:phutil_escape_html_newlines} to escape HTML
while converting newlines to `
`. You should not need to explicitly use
@{function@libphutil:phutil_escape_html} anywhere.
If you need to apply a string function (such as `trim()`) to safe HTML, use
@{method@libphutil:PhutilSafeHTML::applyFunction}.
If you need to extract the content of a @{class@libphutil:PhutilSafeHTML}
object, you should call `getHTMLContent()`, not cast it to a string. Eventually,
we would like to remove the string cast entirely.
Functions @{function@libphutil:phutil_tag} and @{function@libphutil:hsprintf}
are not safe if you pass the user input for the tag or attribute name. All the
following examples are dangerous:
counterexample
phutil_tag($evil);
phutil_tag('span', array($evil => $evil2));
phutil_tag('span', array('onmouseover' => $evil));
// Use PhutilURI to check if $evil is valid HTTP link.
hsprintf('
', $evil);
hsprintf('<%s>%s', $evil, $evil2, $evil);
// We have a lint rule disallowing this.
hsprintf($evil);