Skip to content

Commit 0ad9656

Browse files
terabytesoftwterabytesoftw
authored
Add docs. (#2)
1 parent cd5c688 commit 0ad9656

File tree

12 files changed

+557
-300
lines changed

12 files changed

+557
-300
lines changed

‎README.md‎

Lines changed: 213 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,10 @@
2727
</a>
2828
</p>
2929

30+
HTML Helper is a PHP library that simplifies the creation of HTML content. It provides a set of functions to generate
31+
HTML elements in a programmatic and reusable way.
32+
33+
3034
## Installation
3135

3236
The preferred way to install this extension is through [composer](https://getcomposer.org/download/).
@@ -47,7 +51,215 @@ to the require section of your `composer.json` file.
4751

4852
## Usage
4953

50-
[Check the documentation docs](docs/README.md) to learn about usage.
54+
### Add CSS classes
55+
56+
The `CssClasses::class` helper can be used to add CSS classes to an HTML element.
57+
58+
The method accepts three parameters:
59+
60+
- `attributes:` (array): The HTML attributes of the element.
61+
- `classes:` (array|string): The CSS classes to add.
62+
- `overwrite:` (bool): Whether to overwrite the `class` attribute or not. For default, it is `false`.
63+
64+
```php
65+
<?php
66+
67+
declare(strict_types=1);
68+
69+
use PHPForge\Html\Helper\CssClasses;
70+
71+
private array $attributes = [];
72+
73+
$classes = CssClasses::add($this->attributes, ['btn', 'btn-primary', 'btn-lg']);
74+
```
75+
76+
Overwriting the `class` attribute:
77+
78+
```php
79+
<?php
80+
81+
declare(strict_types=1);
82+
83+
use PHPForge\Html\Helper\CssClasses;
84+
85+
private array $attributes = ['class' => 'btn'];
86+
87+
$classes = CssClasses::add($this->attributes, ['btn-primary', 'btn-lg'], true);
88+
```
89+
90+
### Convert regular expression to pattern
91+
92+
The `Utils::class` helper can be used to normalize a regular expression.
93+
94+
The method accepts one parameter:
95+
96+
- `regexp:` (string): The pattern to normalize.
97+
- `delimiter:` (string): The delimiter to use. For default, it is `null`.
98+
99+
```php
100+
<?php
101+
102+
declare(strict_types=1);
103+
104+
use PHPForge\Html\Helper\Utils;
105+
106+
$pattern = Utils::convertToPattern('/([a-z0-9-]+)/im'); // return: `([a-z0-9-]+)`
107+
```
108+
109+
### Encode content
110+
111+
The `Encode::class` helper can be used to encode HTML content.
112+
113+
The method accepts tree parameters:
114+
115+
- `content:` (string): The content to encode.
116+
- `doubleEncode:` (bool): Whether to double encode the content or not. For default, it is `true`.
117+
- `charset:` (string): The charset to use. For default, it is `UTF-8`.
118+
119+
```php
120+
<?php
121+
122+
declare(strict_types=1);
123+
124+
use PHPForge\Html\Helper\Encode;
125+
126+
$content = Encode::html('<script>alert("Hello, World!")</script>');
127+
```
128+
129+
### Encode value
130+
131+
The `Encode::class` helper can be used to encode HTML value.
132+
133+
The method accepts tree parameters:
134+
135+
- `value:` (string): The value to encode.
136+
- `doubleEncode:` (bool): Whether to double encode the value or not. For default, it is `true`.
137+
- `charset:` (string): The charset to use. For default, it is `UTF-8`.
138+
139+
```php
140+
<?php
141+
142+
declare(strict_types=1);
143+
144+
use PHPForge\Html\Helper\Encode;
145+
146+
$value = Encode::value('<script>alert("Hello, World!")</script>');
147+
```
148+
149+
### Get short class name
150+
151+
The `Utils::class` helper can be used to get the short class name.
152+
153+
The method accepts one parameter:
154+
155+
- `class:` (string): The class name to get the short name.
156+
157+
```php
158+
<?php
159+
160+
declare(strict_types=1);
161+
162+
use PHPForge\Html\Helper\Utils;
163+
164+
$shortName = Utils::getShortClassName('PHPForge\Html\Helper\Utils'); // return: `Utils`
165+
```
166+
167+
### Generate arrayable name
168+
169+
The `ArrayableName::class` helper can be used to generate an arrayable name.
170+
171+
The method accepts one parameter:
172+
173+
- `name:` (string): The name to generate.
174+
175+
```php
176+
<?php
177+
178+
declare(strict_types=1);
179+
180+
use PHPForge\Html\Helper\Utils;
181+
182+
$name = Utils::generateArrayableName('name');
183+
```
184+
185+
### Generate input id
186+
187+
The `Utils::class` helper can be used to generate an input id.
188+
189+
The method accepts tree parameters:
190+
191+
- `fieldModel:` (string): The name of the field model.
192+
- `property:` (string): The name of the property.
193+
- `charset:` (string): The charset to use. For default, it is `UTF-8`.
194+
195+
```php
196+
<?php
197+
198+
declare(strict_types=1);
199+
200+
use PHPForge\Html\Helper\Utils;
201+
202+
$id = Utils::generateInputId('user', 'name');
203+
```
204+
205+
### Generate input name
206+
207+
The `Utils::class` helper can be used to generate an input name.
208+
209+
The method accepts tree parameters:
210+
211+
- `fieldModel:` (string): The name of the field model.
212+
- `property:` (string): The name of the property.
213+
- `arrayable:` (bool): Whether the name is arrayable or not. For default, it is `false`.
214+
215+
```php
216+
<?php
217+
218+
declare(strict_types=1);
219+
220+
use PHPForge\Html\Helper\Utils;
221+
222+
$name = Utils::generateInputName('user', 'name');
223+
```
224+
225+
### Sanitize content
226+
227+
The `Sanitize::class` helper can be used to sanitize HTML content.
228+
229+
The method accepts one parameter:
230+
231+
- `content:` (...string|RenderInterface): The content to sanitize. It can be a string or an object that implements the
232+
`RenderInterface::class`.
233+
234+
```php
235+
<?php
236+
237+
declare(strict_types=1);
238+
239+
use PHPForge\Html\Helper\Sanitize;
240+
241+
$content = Sanitize::html('<script>alert("Hello, World!")</script>');
242+
```
243+
244+
### Render HTML attributes
245+
246+
The `Attributes::class` helper can be used to `render` HTML attributes in a programmatic way.
247+
248+
```php
249+
<?php
250+
251+
declare(strict_types=1);
252+
253+
use PHPForge\Html\Helper\Attributes;
254+
255+
$attributes = Attributes::render(
256+
[
257+
'class' => 'btn btn-primary',
258+
'id' => 'submit-button',
259+
'disabled' => true,
260+
]
261+
);
262+
```
51263

52264
## Testing
53265

‎src/CssClass.php‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,21 +23,21 @@ final class CssClass
2323
* effect.
2424
*
2525
* @param array $attributes The attributes to be modified.
26-
* @param array|string $class The CSS class(es) to be added.
26+
* @param array|string $classes The CSS class(es) to be added.
2727
* @param bool $override Whether to override existing CSS class(es) with new one.
2828
*
29-
* @psalm-param string|string[] $class
29+
* @psalm-param string|string[] $classes
3030
*/
31-
public static function add(array &$attributes, array|string $class, bool $override = false): void
31+
public static function add(array &$attributes, array|string $classes, bool $override = false): void
3232
{
33-
if ($class === '' || $class === []) {
33+
if ($classes === '' || $classes === []) {
3434
return;
3535
}
3636

3737
if ($override) {
38-
$classArray = is_array($class)
39-
? $class
40-
: preg_split('/\s+/', $class, flags: PREG_SPLIT_NO_EMPTY);
38+
$classArray = is_array($classes)
39+
? $classes
40+
: preg_split('/\s+/', $classes, flags: PREG_SPLIT_NO_EMPTY);
4141

4242
$attributes['class'] = implode(' ', $classArray);
4343

@@ -54,9 +54,9 @@ public static function add(array &$attributes, array|string $class, bool $overri
5454
flags: PREG_SPLIT_NO_EMPTY
5555
);
5656

57-
$newClasses = is_array($class)
58-
? $class
59-
: preg_split('/\s+/', $class, -1, PREG_SPLIT_NO_EMPTY);
57+
$newClasses = is_array($classes)
58+
? $classes
59+
: preg_split('/\s+/', $classes, -1, PREG_SPLIT_NO_EMPTY);
6060

6161
$mergedClasses = self::merge($existingClasses, $newClasses);
6262

@@ -65,9 +65,9 @@ public static function add(array &$attributes, array|string $class, bool $overri
6565
return;
6666
}
6767

68-
$classArray = is_array($class)
69-
? $class
70-
: preg_split('/\s+/', $class, flags: PREG_SPLIT_NO_EMPTY);
68+
$classArray = is_array($classes)
69+
? $classes
70+
: preg_split('/\s+/', $classes, flags: PREG_SPLIT_NO_EMPTY);
7171

7272
$attributes['class'] = implode(' ', $classArray);
7373
}

0 commit comments

Comments
 (0)