README

1. What Is It

HTML Formatter will beautify or minify your HTML string for development and testing. Dedicated for those who suffer from reading a template engine produced markup.

2. What Is It Not

HTML Formatter will not sanitize or otherwise manipulate your output beyond indentation and whitespace replacement. HTML Formatter will only add indentation, without otherwise affecting the markup.

If you are looking to remove malicious code or make sure that your document is standards compliant, consider the following alternatives:

If you need to format your code in the development environment, beware that earlier mentioned libraries will attempt to fix your markup.

3. Installation

This package can be installed through Composer.

composer require mallardduck/html-formatter

4. Usage

use MallardDuck\HtmlFormatter\Formatter;

$input = 'This is your HTML code.';
$formatter = new Formatter();
$output = $formatter->beautify($input);

5. Configuration

Formatter is using Simple config to adjust its configuration settings.

5.1. Inline and block elements

HTML elements are either "inline" elements or "block-level" elements.

An inline element occupies only the space bounded by the tags that define the inline element. The following example demonstrates the inline element's influence:

<p>This is an <span>inline</span> element within a block element.</p>

A block-level element occupies the entire space of its parent element (container), thereby creating a "block." Browsers typically display the block-level element with a new line both before and after the element. The following example demonstrates the block-level element's influence:

<div>
    <p>This is a block element within a block element.</p>
</div>

HTML Formatter identifies the following elements as "inline":

a, abbr, acronym, b, bdo, big, br, button, cite, code, dfn, em,
i, img, kbd, label, samp, small, span, strong, sub, sup, tt, var

This is a subset of the inline elements defined in the MDN. All other elements are treated as block.

You can set additional inline elements by adding them to the inline.tag option.

use MallardDuck\HtmlFormatter\Formatter;

$formatter = new Formatter();
$config = $formatter->getConfig();
$config->append('inline.tag', 'foo')->subtract('inline.tag', ['bar', 'baz']);
$formatter->setConfig($config);

5.2. Self-closing (empty) elements

An empty element is an element from HTML, SVG, or MathML that cannot have any child nodes (i.e., nested elements or text nodes).

HTML Formatter identifies the following elements as "inline":

area, base, br, col, command, embed, hr, img, input,
keygen, link, menuitem, meta, param, source, track, wbr,
animate, stop, path, circle, line, polyline, rect, use

This is a subset of the empty elements defined in the MDN. All other elements require closing tag.

You can set additional self-closing elements by adding them to the self-closing.tag option.

use MallardDuck\HtmlFormatter\Formatter;

$formatter = new Formatter();
$formatter->setConfig($formatter->getConfig()->append('self-closing.tag', ['foo', 'bar']));

5.3. Preformatted elements

Specific element will be not touched by the formatter. The built in preformatted elements are

script, pre, textarea.

You can exclude additional elements by adding them to the formatted.tag option.

There settings for all the formatted tags are the following:

You can also change the settings for a specific tag. For example, disabling the cleanup-empty setting for the script tag looks like this:

use MallardDuck\HtmlFormatter\Formatter;

$formatter = new Formatter();
$config = $formatter->getConfig();
$config->set('formatted.tag.script.cleanup-empty', false);
$formatter->setConfig($config);

5.4. Attributes

Additional settings for formatted tags are the following:

6. Methods

7. Credits

Thanks to Gajus Kuizinas for originally creating gajus/dindent and all the other developers who are tirelessly working on it. HTML Formatter was inspired by Dindent.

mallardduck / html-formatter

Maintainers

Details