1 Documentation of common HTML utility functions
2 ──────────────────────────────────────────────
4 Please take note of the literature links at the bottom of this file.
6 Functions defined in src/common/include/utils.php → available: always.
9 • string util_html_encode(string $s)
11 util_html_secure('a=1&b=2')
12 ⇒ 'a=1&b=2' // HTML-encoded
14 util_html_secure('a=1&b=2')
15 ⇒ 'a=1&b=2' // changed!
17 Encode a string for use in XHTML even if it is already encoded.
19 • string util_html_secure(string $s)
21 util_html_secure('a=1&b=2')
22 ⇒ 'a=1&b=2' // HTML-encoded
24 util_html_secure('a=1&b=2')
25 ⇒ 'a=1&b=2' // unchanged
27 Encode a string for use in XHTML if it is not already encoded.
28 (So, if you use this for output sanitising, other than a slight
29 performance penalty no harm is done if the output was already
32 • string util_unconvert_htmlspecialchars(string $s)
34 util_unconvert_htmlspecialchars('a=1&b=2')
35 ⇒ 'a=1&b=2' // unchanged
37 util_unconvert_htmlspecialchars('a=1&b=2')
38 ⇒ 'a=1&b=2' // HTML-decoded
40 Undo util_html_encode; be careful, this can decode partially.
43 • string util_gethref(optional(false) string $baseurl,
44 optional(empty) array $args, optional(true) bool $ashtml,
45 optional('&') string $sep)
47 util_gethref("/x.php", array(
51 ⇒ "/x.php?foo=a%2Bb%26c&bar=d%2Bb%26e"
53 util_gethref("/x.php", array(
57 ⇒ /x.php?foo=a%2Bb%26c&bar=d%2Bb%26e
59 util_gethref("/x.php", array(
63 ⇒ "/x.php?foo=a%2Bb%26c;bar=d%2Bb%26e"
65 Construct an URI for use with util_make_url, session_redirect,
66 html_e('a', array('href' => …)), and similar. The first argument
67 ($baseurl) is passed through as-is but, if falsy, defaults to
68 getStringFromServer('PHP_SELF'); the arguments (both keys and
69 values) are urlencoded (entries while values is false are not
70 emitted at all) and appended, with a question mark in front and
71 the $sep separator in between.
73 If $ashtml is true (default), the result will then be run through
74 util_html_encode; set this to false when using in html_e href as
75 value (since html_e will html-encode itself).
77 • string util_make_url(string $path)
79 util_make_url('/foo.php?a=1&b=2')
80 ⇒ 'https://forge.domain.com/fusionforge/foo.php?a=1&b=2'
82 Return an absolute URI for the path in question, containing the
83 system-defined protocol, hostname and (if defined) webroot prefix.
85 Both html-encoded and not html-encoded return values of util_gethref
86 are safe to pass as arguments, if their baseurl was only a path.
88 • integer|false util_nat0(ByRef string $s)
90 If and only if $s is the normalised positive integer (ℕ₀)
91 representation of a number, return that number; false otherwise.
92 Limited by system constraints, i.e. usually [0;2³¹-1].
95 ‣ common non-HTML utility functions
98 • mixed util_ifsetor(ByRef mixed $val, optional(false) mixed $default)
100 If isset($val), return $val, otherwise (no warning) $default.
102 • string debug_string_backtrace(void)
104 Return the current debugging backtrace as string.
110 • http://me.veekun.com/blog/2012/04/09/php-a-fractal-of-bad-design/