@@ -13,13 +13,13 @@ pipeline, and the browser will treat it as plain text, not HTML.
13
13
This document describes the right way to build HTML components so they are safe
14
14
from XSS and render correctly. Broadly:
15
15
16
- - Use @{function@libphutil :phutil_tag} (and @{function:javelin_tag}) to build
16
+ - Use @{function@arcanist :phutil_tag} (and @{function:javelin_tag}) to build
17
17
tags.
18
- - Use @{function@libphutil :hsprintf} where @{function@libphutil :phutil_tag}
18
+ - Use @{function@arcanist :hsprintf} where @{function@arcanist :phutil_tag}
19
19
is awkward.
20
20
- Combine elements with arrays, not string concatenation.
21
21
- @{class:AphrontView} subclasses should return a
22
- @{class@libphutil :PhutilSafeHTML} object from their `render()` method.
22
+ @{class@arcanist :PhutilSafeHTML} object from their `render()` method.
23
23
- @{class:AphrontView} subclasses act like tags when rendering.
24
24
- @{function:pht} has some special rules.
25
25
- There are some other things that you should be aware of.
@@ -28,7 +28,7 @@ See below for discussion.
28
28
29
29
= Building Tags: phutil_tag() =
30
30
31
- Build HTML tags with @{function@libphutil :phutil_tag}. For example:
31
+ Build HTML tags with @{function@arcanist :phutil_tag}. For example:
32
32
33
33
phutil_tag(
34
34
'div',
@@ -37,10 +37,10 @@ Build HTML tags with @{function@libphutil:phutil_tag}. For example:
37
37
),
38
38
$content);
39
39
40
- @{function@libphutil :phutil_tag} will properly escape the content and all the
41
- attributes, and return a @{class@libphutil :PhutilSafeHTML} object. The rendering
40
+ @{function@arcanist :phutil_tag} will properly escape the content and all the
41
+ attributes, and return a @{class@arcanist :PhutilSafeHTML} object. The rendering
42
42
pipeline knows that this object represents a properly escaped HTML tag. This
43
- allows @{function@libphutil :phutil_tag} to render tags with other tags as
43
+ allows @{function@arcanist :phutil_tag} to render tags with other tags as
44
44
content correctly (without double-escaping):
45
45
46
46
phutil_tag(
@@ -52,14 +52,14 @@ content correctly (without double-escaping):
52
52
$content));
53
53
54
54
In Phabricator, the @{function:javelin_tag} function is similar to
55
- @{function@libphutil :phutil_tag}, but provides special handling for the
55
+ @{function@arcanist :phutil_tag}, but provides special handling for the
56
56
`sigil` and `meta` attributes.
57
57
58
58
= Building Blocks: hsprintf() =
59
59
60
- Sometimes, @{function@libphutil :phutil_tag} can be particularly awkward to
61
- use. You can use @{function@libphutil :hsprintf} to build larger and more
62
- complex blocks of HTML, when @{function@libphutil :phutil_tag} is a poor fit.
60
+ Sometimes, @{function@arcanist :phutil_tag} can be particularly awkward to
61
+ use. You can use @{function@arcanist :hsprintf} to build larger and more
62
+ complex blocks of HTML, when @{function@arcanist :phutil_tag} is a poor fit.
63
63
@{function:hsprintf} has `sprintf()` semantics, but `%s` escapes HTML:
64
64
65
65
// Safely build fragments or unwieldy blocks.
@@ -72,13 +72,13 @@ complex blocks of HTML, when @{function@libphutil:phutil_tag} is a poor fit.
72
72
- You need to build a block with a lot of tags, like a table with rows and
73
73
cells.
74
74
- You need to build part of a tag (usually you should avoid this, but if you
75
- do need to, @{function@libphutil :phutil_tag} can not do it).
75
+ do need to, @{function@arcanist :phutil_tag} can not do it).
76
76
77
77
Note that it is unsafe to provide any user-controlled data to the first
78
- parameter of @{function@libphutil :hsprintf} (the `sprintf()`-style pattern).
78
+ parameter of @{function@arcanist :hsprintf} (the `sprintf()`-style pattern).
79
79
80
- Like @{function@libphutil :phutil_tag}, this function returns a
81
- @{class@libphutil :PhutilSafeHTML} object.
80
+ Like @{function@arcanist :phutil_tag}, this function returns a
81
+ @{class@arcanist :PhutilSafeHTML} object.
82
82
83
83
= Composing Tags =
84
84
@@ -99,7 +99,7 @@ Instead, use an array:
99
99
// Render a tag containing other tags safely.
100
100
phutil_tag('div', array(), array($header, $body));
101
101
102
- If you concatenate @{class@libphutil :PhutilSafeHTML} objects, they revert to
102
+ If you concatenate @{class@arcanist :PhutilSafeHTML} objects, they revert to
103
103
normal strings and are no longer marked as properly escaped tags.
104
104
105
105
(In the future, these objects may stop converting to strings, but for now they
@@ -118,7 +118,7 @@ If you need to build a list of items with some element in between each of them
118
118
= AphrontView Classes =
119
119
120
120
Subclasses of @{class:AphrontView} in Phabricator should return a
121
- @{class@libphutil :PhutilSafeHTML} object. The easiest way to do this is to
121
+ @{class@arcanist :PhutilSafeHTML} object. The easiest way to do this is to
122
122
return `phutil_tag()` or `javelin_tag()`:
123
123
124
124
return phutil_tag('div', ...);
@@ -130,8 +130,8 @@ You can use an @{class:AphrontView} subclass like you would a tag:
130
130
= Internationalization: pht() =
131
131
132
132
The @{function:pht} function has some special rules. If any input to
133
- @{function:pht} is a @{class@libphutil :PhutilSafeHTML} object, @{function:pht}
134
- returns a @{class@libphutil :PhutilSafeHTML} object itself. Otherwise, it returns
133
+ @{function:pht} is a @{class@arcanist :PhutilSafeHTML} object, @{function:pht}
134
+ returns a @{class@arcanist :PhutilSafeHTML} object itself. Otherwise, it returns
135
135
normal text.
136
136
137
137
This is generally safe because translations are not permitted to have more tags
@@ -146,23 +146,23 @@ like you would expect, but it is worth being aware of.
146
146
NOTE: This section describes dangerous methods which can bypass XSS protections.
147
147
If possible, do not use them.
148
148
149
- You can build @{class@libphutil :PhutilSafeHTML} out of a string explicitly by
149
+ You can build @{class@arcanist :PhutilSafeHTML} out of a string explicitly by
150
150
calling @{function:phutil_safe_html} on it. This is **dangerous**, because if
151
151
you are wrong and the string is not actually safe, you have introduced an XSS
152
152
vulnerability. Consequently, you should avoid calling this if possible.
153
153
154
- You can use @{function@libphutil :phutil_escape_html_newlines} to escape HTML
154
+ You can use @{function@arcanist :phutil_escape_html_newlines} to escape HTML
155
155
while converting newlines to `<br />`. You should not need to explicitly use
156
- @{function@libphutil :phutil_escape_html} anywhere.
156
+ @{function@arcanist :phutil_escape_html} anywhere.
157
157
158
158
If you need to apply a string function (such as `trim()`) to safe HTML, use
159
- @{method@libphutil :PhutilSafeHTML::applyFunction}.
159
+ @{method@arcanist :PhutilSafeHTML::applyFunction}.
160
160
161
- If you need to extract the content of a @{class@libphutil :PhutilSafeHTML}
161
+ If you need to extract the content of a @{class@arcanist :PhutilSafeHTML}
162
162
object, you should call `getHTMLContent()`, not cast it to a string. Eventually,
163
163
we would like to remove the string cast entirely.
164
164
165
- Functions @{function@libphutil :phutil_tag} and @{function@libphutil :hsprintf}
165
+ Functions @{function@arcanist :phutil_tag} and @{function@arcanist :hsprintf}
166
166
are not safe if you pass the user input for the tag or attribute name. All the
167
167
following examples are dangerous:
168
168
0 commit comments