aviator / html
Installs: 1 285
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: >=7.2.0
- aviator/delegate: 1.*
- cocur/slugify: ^4.0
Requires (Dev)
- illuminate/support: ^7.0
- larapack/dd: ^1.1
- phpunit/phpunit: ^8.5
- vimeo/psalm: ^3.2
README
Html
Html is a simple package for building snippets of valid HTML. It can be used to augment a templating system where you want to encapsulate more logic in a class vs a template file.
Getting Started
Prerequisites
This package requires PHP 7 or higher.
Installing
Via Composer:
composer require aviator/html
Testing
Run:
composer test
Usage
Tags
To build a block of HTML, make a new tag:
$tag = new Tag('div');
Or, using the static constructor:
$tag = Tag::make('div');
Or, using magic static calls:
$tag = Tag::div();
Or, using the global helper function:
$tag = tag('div');
To render the tag, call render()
:
echo $tag->render();
Which produces:
<div></div>
The Tag
class will only accept valid HTML tags. Trying to create an invalid tag will throw an exception.
Content
Tags can have contents. You can pass in a string, a Tag
, or an array of either or both.
Strings
Use the with()
method to add content to a tag:
$tag = tag('div')->with('some content');
This will render as:
<div>some content</div>
Additionally, with()
will attempt to get a string representation of any non-string, non-renderable passed in, including objects that implement __toString()
.
Nested Tag
Tags can be nested:
$tag = tag('div')->with( tag('p')->with('some content') );
Render:
<div><p>some content</p></div>
Array
You can also use an array:
$tag = tag('ul')->with([ tag('li')->with('list item 1'), tag('li')->with('list item 2'), 'misplaced text', ]);
Which will render:
<ul> <li>list item 1</li> <li>list item 2</li> misplaced text </ul>
Void tags
The Tag
class knows which tags are void and need no closing tag. There's no need to do anything for <input>
, <hr>
, etc.
Void tags cannot have content. Trying to add content to them will throw an exception.
Fragments
Direct siblings can be rendered using a Fragment
. A fragment is simply an un-nested collection of tags (or other renderables, even other fragments):
$fragment = new Fragment([ new Tag('p'), new Tag('div'), ]); // Or Fragment::make([...]);
$fragment->render()
:
<p></p><div></div>
Conditional Tags
You can create a conditional tag that will only render sometimes:
$tag = new Tag('div'); // Evaluates equality, eg truthy and falsey values $tag->setShouldRender(false);
or
$tag = Tag::when(false, 'div');
$tag->render()
:
''
CSS Classes
To specify CSS classes for your tags, pass in a second parameter:
$tag = tag('div', 'some-class');
Render:
<div class="some-class"></div>
Multiple CSS classes may be passed in via array:
$tag = tag('div', ['class-one', 'class-two'])
Render:
<div class="class-one class-two"></div>
After instantiation
If you need to add classes after instantiation, you can call addClass()
, which accepts the same string or array as the constructor:
$tag = tag('div'); $tag->addClass('some-class'); $tag->addClass(['class2', 'class3']);
Attributes
Attributes are passed in as the third parameter. Attributes with values are passed by association. Boolean attributes are simply a value.
$tag = tag('input', 'some-class', [ 'value' => 'content', 'disabled' ]);
Render:
<input value="content" disabled>
After instantiation
If you need to add attributes after instantiation, you can call addAttribute()
, which accepts the same array as the constructor:
$tag = tag('input'); $tag->addAttribute(['autocomplete' => 'off']); $tag->addAttribute(['disabled']);
Validation
Attributes are validated to make sure they belong to the tag you've applied them to. For instance adding the max
attribute to a <div>
will throw an exception.
Getting attribute values
If you want to retrieve an attribute from a Tag
instance, call attribute($name)
. If your attribute exists you'll get the value (boolean attributes always return true
), otherwise you'll get null.
echo tag('input')->addAttribute(['name' => 'some_name'])->attribute('name'); // Result: 'some_name' echo tag('input')->addAttribute(['disabled'])->attribute('disabled'); // Result: true echo tag('input')->attribute('foo'); // Result: null
Options
If you want to render an open tag, call the dontClose()
method:
echo tag('div')->dontClose()->render()
Result:
<div>