aviator/html

3.0.5 2020-12-08 21:25 UTC

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

MIT

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>