Debian Codegraph @

vendor/ipl/html/src/Html.php

raw
1 <?php
2
3 namespace ipl\Html;
4
5 use InvalidArgumentException;
6
7 use function ipl\Stdlib\get_php_type;
8 use function ipl\Stdlib\iterable_key_first;
9
10 /**
11 * Main utility class when working with ipl\Html
12 */
13 abstract class Html
14 {
15 /**
16 * Create a HTML element from the given tag, attributes and content
17 *
18 * This method does not render the HTML element but creates a {@link HtmlElement}
19 * instance from the given tag, attributes and content
20 *
21 * @param string $name The desired HTML tag name
22 * @param mixed $attributes HTML attributes or content for the element
23 * @param mixed $content The content of the element if no attributes have been given
24 *
25 * @return HtmlElement The created element
26 */
27 public static function tag($name, $attributes = null, $content = null)
28 {
29 if ($content !== null) {
30 // If not null, it's html content, no question
31 $content = static::wantHtmlList($content);
32 } elseif ($attributes instanceof ValidHtml || is_scalar($attributes)) {
33 // Otherwise $attributes may be $content, but only if definitely **NOT** attributes
34 $content = static::wantHtmlList($attributes);
35 $attributes = null;
36 }
37
38 if ($attributes !== null) {
39 if (! is_iterable($attributes) || ! is_int(iterable_key_first($attributes))) {
40 // Not an array (e.g. instance of Attributes) or an associative array
41 $attributes = Attributes::wantAttributes($attributes);
42 } elseif (is_iterable($attributes)) {
43 // $attributes may still be $content, in case of a sequenced array
44 if ($content !== null) {
45 // But not if there's already $content
46 throw new InvalidArgumentException('Value of argument $attributes are no attributes');
47 }
48
49 $content = static::wantHtmlList($attributes);
50 $attributes = null;
51 }
52 }
53
54 return new HtmlElement($name, $attributes, ...($content ?: []));
55 }
56
57 /**
58 * Convert special characters to HTML5 entities using the UTF-8 character
59 * set for encoding
60 *
61 * This method internally uses {@link htmlspecialchars} with the following
62 * flags:
63 *
64 * * Single quotes are not escaped (ENT_COMPAT)
65 * * Uses HTML5 entities, disallowing &#013; (ENT_HTML5)
66 * * Invalid characters are replaced with � (ENT_SUBSTITUTE)
67 *
68 * Already existing HTML entities will be encoded as well.
69 *
70 * @param string $content The content to encode
71 *
72 * @return string The encoded content
73 */
74 public static function escape($content)
75 {
76 return htmlspecialchars($content, ENT_COMPAT | ENT_HTML5 | ENT_SUBSTITUTE, 'UTF-8');
77 }
78
79 /**
80 * Factory for {@link sprintf()}-like formatted HTML strings
81 *
82 * This allows to use {@link sprintf()}-like format strings with {@link ValidHtml} element arguments, but with the
83 * advantage that they'll not be rendered immediately.
84 *
85 * # Example Usage
86 * ```
87 * echo Html::sprintf('Hello %s!', Html::tag('strong', $name));
88 * ```
89 *
90 * @param string $format
91 * @param mixed ...$args
92 *
93 * @return FormattedString
94 */
95 public static function sprintf($format, ...$args)
96 {
97 return new FormattedString($format, $args);
98 }
99
100 /**
101 * Wrap each item of then given list
102 *
103 * $wrapper is a simple HTML tag per entry if a string is given,
104 * otherwise the given callable is called with key and value of each list item as parameters.
105 *
106 * @param iterable $list
107 * @param string|callable $wrapper
108 *
109 * @return HtmlDocument
110 */
111 public static function wrapEach($list, $wrapper)
112 {
113 if (! is_iterable($list)) {
114 throw new InvalidArgumentException(sprintf(
115 'Html::wrapEach() requires a traversable list, got "%s"',
116 get_php_type($list)
117 ));
118 }
119 $result = new HtmlDocument();
120 foreach ($list as $name => $value) {
121 if (is_string($wrapper)) {
122 $result->addHtml(Html::tag($wrapper, $value));
123 } elseif (is_callable($wrapper)) {
124 $result->add($wrapper($name, $value));
125 } else {
126 throw new InvalidArgumentException(sprintf(
127 'Wrapper must be callable or a string in Html::wrapEach(), got "%s"',
128 get_php_type($wrapper)
129 ));
130 }
131 }
132
133 return $result;
134 }
135
136 /**
137 * Ensure that the given content of mixed type is converted to an instance of {@link ValidHtml}
138 *
139 * Returns the very same element in case it's already an instance of {@link ValidHtml}.
140 *
141 * @param mixed $any
142 *
143 * @return ValidHtml
144 *
145 * @throws InvalidArgumentException In case the given content is of an unsupported type
146 */
147 public static function wantHtml($any)
148 {
149 if ($any instanceof ValidHtml) {
150 return $any;
151 } elseif (static::canBeRenderedAsString($any)) {
152 return new Text($any);
153 } elseif (is_iterable($any)) {
154 $html = new HtmlDocument();
155 foreach ($any as $el) {
156 if ($el !== null) {
157 $html->addHtml(static::wantHtml($el));
158 }
159 }
160
161 return $html;
162 } else {
163 throw new InvalidArgumentException(sprintf(
164 'String, Html Element or Array of such expected, got "%s"',
165 get_php_type($any)
166 ));
167 }
168 }
169
170 /**
171 * Accept any input and return it as list of ValidHtml
172 *
173 * @param mixed $content
174 *
175 * @return ValidHtml[]
176 */
177 public static function wantHtmlList($content)
178 {
179 $list = [];
180
181 if ($content === null) {
182 return $list;
183 } elseif (! is_iterable($content)) {
184 $list[] = static::wantHtml($content);
185 } elseif ($content instanceof ValidHtml) {
186 $list[] = $content;
187 } else {
188 foreach ($content as $part) {
189 $list = array_merge($list, static::wantHtmlList($part));
190 }
191 }
192
193 return $list;
194 }
195
196 /**
197 * Get whether the given variable be rendered as a string
198 *
199 * @param mixed $any
200 *
201 * @return bool
202 */
203 public static function canBeRenderedAsString($any)
204 {
205 return is_scalar($any) || is_null($any) || (
206 is_object($any) && method_exists($any, '__toString')
207 );
208 }
209
210 /**
211 * Forward inaccessible static method calls to {@link Html::tag()} with the method's name as tag
212 *
213 * @param string $name
214 * @param array $arguments
215 *
216 * @return HtmlElement
217 */
218 public static function __callStatic($name, $arguments)
219 {
220 $attributes = array_shift($arguments);
221 $content = array_shift($arguments);
222
223 return static::tag($name, $attributes, $content);
224 }
225
226 /**
227 * @deprecated Use {@link Html::encode()} instead
228 */
229 public static function escapeForHtml($content)
230 {
231 return static::escape($content);
232 }
233
234 /**
235 * @deprecated Use {@link Error::render()} instead
236 */
237 public static function renderError($error)
238 {
239 return Error::render($error);
240 }
241 }