https://github.com/drupol/htmltag
A fast and extensible helper library for generating HTML, create tags, their attributes and content.
https://github.com/drupol/htmltag
Last synced: 5 months ago
JSON representation
A fast and extensible helper library for generating HTML, create tags, their attributes and content.
- Host: GitHub
- URL: https://github.com/drupol/htmltag
- Owner: drupol
- License: mit
- Archived: true
- Created: 2018-08-30T06:51:32.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2020-10-16T20:34:19.000Z (over 5 years ago)
- Last Synced: 2025-10-29T00:42:42.491Z (7 months ago)
- Language: PHP
- Homepage: https://not-a-number.io/htmltag
- Size: 436 KB
- Stars: 11
- Watchers: 2
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[![Latest Stable Version][latest stable version]][packagist collection]
[![GitHub stars][github stars]][packagist collection]
[![Total Downloads][total downloads]][packagist collection]
[![GitHub Workflow Status][github workflow status]][collection actions]
[![Scrutinizer code quality][code quality]][scrutinizer code quality]
[![Type Coverage][type coverage]][sheperd type coverage]
[![Code Coverage][code coverage]][scrutinizer code quality]
[![License][license]][packagist collection]
[![Donate!][donate github]][github sponsor]
[![Donate!][donate paypal]][paypal sponsor]
# HTMLTag
## Description
This is a PHP library that handles the generation of HTML tags, their attributes and content.
The focus is on security, speed and usability.
## Requirements
* PHP >= 7.1.3
## Installation
```composer require drupol/htmltag```
## Usage
```php
'author']);
$meta->attr('content', 'pol dellaiera');
// Title object.
$title = \drupol\htmltag\HtmlTag::tag('h1', ['class' => 'title'], 'Welcome to HTMLTag');
// Paragraph object.
$paragraph = \drupol\htmltag\HtmlTag::tag('p', ['class' => 'section']);
$paragraph->attr('class')->append('paragraph');
$paragraph->content('This library helps you create HTML.');
// Simple footer
$footer = \drupol\htmltag\HtmlTag::tag('footer', [], 'Thanks for using it!');
// Body tag.
// Add content that can be transformed into strings.
$body = \drupol\htmltag\HtmlTag::tag('body', [], [$title, $paragraph, $footer]);
// Fix something that was already added.
$paragraph->attr('class')->remove('section')->replace('paragraph', 'description');
// Alter the values of a specific attributes.
$meta->attr('content')->alter(
function ($values) {
return array_map('strtoupper', $values);
}
);
echo $meta . $body;
```
Will print:
```html
Welcome to HTMLTag
This library helps you create HTML.
Thanks for using it!
```
# HTML Builder
The library comes with an HTML Builder class that allows you to quickly create HTML content.
```php
c(' Comment 1 ') // Add a comment
->p(['class' => ['paragraph']], 'some content')
->div(['class' => 'container'], 'this is a simple div')
->_() // End tag
->c(' Comment 2 ')
->region([], 'region with tags')
->_()
->c(' Comment 3 ')
->a()
->c(' Comment 4 ')
->span(['class' => 'link'], 'Link content')
->_()
->div(['class' => 'Unsecure "classes"'], 'Unsecure content')
->_()
->c(' Comment 5 ');
echo $html;
```
This will produce:
```html
some content
this is a simple div
region with <unsafe> tags
Unsecure <a href="#">content</a>
```
## Technical notes
### Tag analysis
```
The tag name An attribute The content
| | |
++-+ +-----+-----+ +----+-----+
| | | | | |
Hello world!
| |
+-----------------------+-----------------------+
|
The attributes
```
The library is built around 3 objects.
* The Tag object that handles the attributes, the tag name and the content,
* The Attributes object that handles the attributes,
* The Attribute object that handles an attribute which is composed of name and its value(s).
The Tag object uses the Attributes object which is, basically, the storage of Attribute objects.
You may use each of these objects individually.
All methods are documented through interfaces and your IDE should be able to autocomplete when needed.
Most methods parameters are [variadics](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list) and
accept unlimited nested values or array of values.
You can also chain most of the methods.
The allowed type of values can be almost anything. If it's an object, it must implements the `__toString()` method.
#### Examples
Method chaining:
```php
attr('class', ['FRONT', ['NODE', ['sidebra']], 'node', ' a', ' b ', [' c']])
->replace('sidebra', 'sidebar')
->alter(
function ($values) {
$values = array_map('strtolower', $values);
$values = array_unique($values);
$values = array_map('trim', $values);
natcasesort($values);
return $values;
}
);
$tag->content('Hello world');
echo $tag; // Hello world
```
The following examples will all produce the same HTML.
```php
attr('class', ['front', ['node', ['sidebar']]]);
$tag->content('Hello world');
echo $tag; // Hello world
```
```php
attr('class', 'front', 'node', 'sidebar');
$tag->content('Hello world');
echo $tag; // Hello world
```
```php
attr('class', ['front', 'node', 'sidebar']);
$tag->content('Hello world');
echo $tag; // Hello world
```
```php
attr('class', 'front node sidebar');
$tag->content('Hello world');
echo $tag; // Hello world
```
### Tag object
```php
attr('class', 'front');
$tag->content('Hello world');
echo $tag; // Hello world
```
### Attributes object
```php
append('class', 'a', 'b', 'c');
$attributes->append('id', 'htmltag');
// Hence the trailing space before the class attribute.
echo $attributes; // class="a b c" id="htmltag"
```
### Attribute object
```php
attr('class', 'E', 'C', ['A', 'B'], 'D', 'A', ' F ');
// Add a random attribute and the same values.
$tag->attr('data-original', 'e', 'c', ['a', 'b'], 'd', 'a', ' f ');
echo $tag; //
```
The same mechanism goes for the `Tag` class.
## Security
To avoid security issues, every printed objects are escaped.
If objects are used as input and if they implement the `__toString()` method, they will be converted to string.
It's up to the user to make sure that they print **unsafe** output so they are not escaped twice.
## Code quality, tests and benchmarks
Every time changes are introduced into the library, [Travis CI](https://travis-ci.org/drupol/htmltag/builds) run the tests and the benchmarks.
The library has tests written with [PHPSpec](http://www.phpspec.net/).
Feel free to check them out in the `spec` directory. Run `composer phpspec` to trigger the tests.
[PHPBench](https://github.com/phpbench/phpbench) is used to benchmark the library, to run the benchmarks: `composer bench`
[PHPInfection](https://github.com/infection/infection) is used to ensure that your code is properly tested, run `composer infection` to test your code.
## Contributing
Feel free to contribute to this library by sending Github pull requests. I'm quite reactive :-)
[packagist collection]: https://packagist.org/packages/drupol/htmltag
[latest stable version]: https://img.shields.io/packagist/v/drupol/htmltag.svg?style=flat-square
[github stars]: https://img.shields.io/github/stars/drupol/htmltag.svg?style=flat-square
[total downloads]: https://img.shields.io/packagist/dt/drupol/htmltag.svg?style=flat-square
[github workflow status]: https://img.shields.io/github/workflow/status/drupol/htmltag/Continuous%20Integration?style=flat-square
[code quality]: https://img.shields.io/scrutinizer/quality/g/drupol/htmltag/master.svg?style=flat-square
[scrutinizer code quality]: https://scrutinizer-ci.com/g/drupol/htmltag/?branch=master
[type coverage]: https://shepherd.dev/github/drupol/htmltag/coverage.svg
[sheperd type coverage]: https://shepherd.dev/github/drupol/htmltag
[code coverage]: https://img.shields.io/scrutinizer/coverage/g/drupol/htmltag/master.svg?style=flat-square
[license]: https://img.shields.io/packagist/l/drupol/htmltag.svg?style=flat-square
[donate github]: https://img.shields.io/badge/Sponsor-Github-brightgreen.svg?style=flat-square
[donate paypal]: https://img.shields.io/badge/Sponsor-Paypal-brightgreen.svg?style=flat-square
[github sponsor]: https://github.com/sponsors/drupol
[paypal sponsor]: https://www.paypal.me/drupol
[collection actions]: https://github.com/drupol/htmltag/actions