|
| 1 | +html5gen |
| 2 | += |
| 3 | +An easy to use HTML5 generator written in PHP. Creates valid and secure HTML5 code. |
| 4 | + |
| 5 | +## Installation |
| 6 | +To install the library I would recommend to use Composer. Execute the following command |
| 7 | +```bash |
| 8 | +$ composer require patrickschur/html5gen |
| 9 | +``` |
| 10 | +or add this to your `composer.json` |
| 11 | +```json |
| 12 | +{ |
| 13 | + "require": { |
| 14 | + "patrickschur/html5gen": "*" |
| 15 | + } |
| 16 | +} |
| 17 | +``` |
| 18 | +Because the script is not really big you could also copy the `Html5Gen.php` out of the `src` folder to use the script without Composer. |
| 19 | + |
| 20 | +## Usage |
| 21 | +```php |
| 22 | +require 'vendor/autoload.php'; |
| 23 | + |
| 24 | +use Html5Gen\Html5Gen as H; // shorthand |
| 25 | + |
| 26 | +echo |
| 27 | +H::html([], function() { |
| 28 | + H::head(); |
| 29 | + H::body(); |
| 30 | +}); |
| 31 | +``` |
| 32 | +outputs: |
| 33 | +```html |
| 34 | +<!DOCTYPE html> |
| 35 | +<html> |
| 36 | +<head></head> |
| 37 | +<body></body> |
| 38 | +</html> |
| 39 | +``` |
| 40 | + |
| 41 | +#### Attributes |
| 42 | +All elements have one thing in common, all of them expect attributes. |
| 43 | +That is also the reason why it is the first parameter of all methods. |
| 44 | +You can specify attributes by an array. Where the key is the name of the attribute and the value the attribute value. |
| 45 | +If you do not want to specify attributes, leave the array empty. |
| 46 | +You can also omit the array if you do not use a callback. |
| 47 | +```php |
| 48 | +echo |
| 49 | +H::html(['lang' => 'en', 'dir' => 'ltr'], function() { |
| 50 | + H::head(); |
| 51 | + H::body([], function () { |
| 52 | + H::p(['class' => 'foo bar']); |
| 53 | + }); |
| 54 | +}); |
| 55 | +``` |
| 56 | +outputs: |
| 57 | +```html |
| 58 | +<!DOCTYPE html> |
| 59 | +<html lang="en" dir="ltr"> |
| 60 | +<head></head> |
| 61 | +<body><p class="foo bar"></p></body> |
| 62 | +</html> |
| 63 | +``` |
| 64 | + |
| 65 | +#### Callbacks |
| 66 | +The second and last parameter is the a callback function defined by the user. |
| 67 | +This lets you write a more generic code and allows the nesting of elements. |
| 68 | +With the `yield` keyword it is possible to write text into the current element without terminating the function. |
| 69 | +> Notice: Elements like `base`, `br`, `meta`, `area`, `input`, `wbr`, `hr`, `link`, `param`, `source`, `col` and `img` can not have a callback, only attributes. |
| 70 | +
|
| 71 | +```php |
| 72 | +echo |
| 73 | +H::html([], function() { |
| 74 | + H::head([], function () { |
| 75 | + H::meta(['charset' => 'UTF-8']); |
| 76 | + }); |
| 77 | + H::body([], function () |
| 78 | + { |
| 79 | + foreach (range(0, 10) as $number) { |
| 80 | + H::p([], function () use ($number) { |
| 81 | + yield $number; |
| 82 | + }); |
| 83 | + } |
| 84 | + }); |
| 85 | +}); |
| 86 | +``` |
| 87 | +outputs: |
| 88 | +```html |
| 89 | +<!DOCTYPE html> |
| 90 | +<html> |
| 91 | +<head><meta charset="UTF-8"></head> |
| 92 | +<body> |
| 93 | +<p>0</p> |
| 94 | +<p>1</p> |
| 95 | +<p>2</p> |
| 96 | +<p>3</p> |
| 97 | +<p>4</p> |
| 98 | +<p>5</p> |
| 99 | +<p>6</p> |
| 100 | +<p>7</p> |
| 101 | +<p>8</p> |
| 102 | +<p>9</p> |
| 103 | +<p>10</p> |
| 104 | +</body> |
| 105 | +</html> |
| 106 | +``` |
| 107 | + |
| 108 | +#### Automatically Escaped Values |
| 109 | +The script will automatically detect if it is useful to escape a value or not. |
| 110 | +For example if you want to define a `script` tag, it would not be useful to escape, because that destroys the logic of a script. |
| 111 | +But if you use a `pre` tag it makes much more sense to escape the value. Also works for attributes. |
| 112 | + |
| 113 | +```php |
| 114 | +echo |
| 115 | +H::html([], function() { |
| 116 | + H::head([]); |
| 117 | + H::body([], function () { |
| 118 | + // A really bad attribute value |
| 119 | + H::pre(['id' => '"\'"'], function () { |
| 120 | + yield '<script>alert(1);</script>'; // maybe some user code? |
| 121 | + }); |
| 122 | + |
| 123 | + // Be careful with that and do not use user code in it |
| 124 | + H::script([], function () { |
| 125 | + yield 'var x = Math.floor(Math.random() * 100);'; |
| 126 | + yield 'alert(0 < x < 100);'; |
| 127 | + }); |
| 128 | + }); |
| 129 | +}); |
| 130 | +``` |
| 131 | +outputs: |
| 132 | +```html |
| 133 | +<!DOCTYPE html> |
| 134 | +<html> |
| 135 | +<head></head> |
| 136 | +<body> |
| 137 | +<pre id=""'""><script>alert(1);</script></pre> |
| 138 | +<script>var x = Math.floor(Math.random() * 100);alert(0 < x < 100);</script> |
| 139 | +</body> |
| 140 | +</html> |
| 141 | +``` |
| 142 | + |
| 143 | +#### [TODO] Checklist: |
| 144 | +- [ ] Exists the attribute for the element? |
| 145 | +- [ ] Is the given attribute value allowed for the specified attribute? |
| 146 | +- [ ] Is the element allowed in the current element? |
| 147 | +- [ ] Check the document for bad practices. For example duplicate id references. |
| 148 | +- [ ] Check the `nonce` and `integrity` attribute on the correctness. |
| 149 | + |
| 150 | +## Contributing |
| 151 | +Feel free to contribute. Any help is welcome. |
| 152 | + |
| 153 | +## License |
| 154 | +This projects is licensed under the terms of the MIT license. |
0 commit comments