mallardduck/html-formatter

HTML beautifier and minifier library for development and testing.

Fund package maintenance!
navindex

1.0.1 2022-02-27 23:38 UTC

This package is auto-updated.

Last update: 2024-06-28 04:42:18 UTC


README

HTML Formatter Latest Version

Unit tests Code analysis Coverage Status License: MIT

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.

Name Type Description
tab string Character(s) used for indentation. Defaults to 4 spaces.
self-closing.tag array Here you can add more self-closing tags. see below
inline.tag array Here you can add more inline tags, or change any block tags and make them inline. see below
formatted.tag array Here you can add more tags to be exluded of formatting. see below
attributes.trim boolean Remove leading and trailing whitespace in the attribute values.
attribute.cleanup boolean Replace all whitespaces with a single space in the attribute values.
cdata.cleanup boolean Replace all whitespaces with a single space in CDATA.
cdata.trim boolean Remove leading and trailing whitespace in CDATA.

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:

Setting Type Description
formatted.tag.cleanup-empty boolean Removes the inner content if it has only whitespace.
formatted.tag.opening-break boolean Inserts a line break after the opening tag.
formatted.tag.closing-break boolean Inserts a line break before the closing tag.
formatted.tag.trim boolean Removes the leading and trailing whitespace of the content.

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:

Setting Type Description
cleanup-empty boolean Removes the inner content if it has only whitespace.
opening-break boolean Inserts a line break after the opening tag.
closing-break boolean Inserts a line break before the closing tag.
trim boolean Removes the leading and trailing whitespace of the content.

6. Methods

Name Attributes Description Example
constructor Config|array|null Creates a Formatter class instance $f = new Formatter($config);
getConfig - Configuration getter $config = $f->getConfig();
getConfigArray - Configuration getter $config = $f->getConfigArray();
setConfig Config|array|null Configuration setter $f->setConfig($config);
beautify string Beautifies the input string $output = $f->beautify($html);
minify string Minifies the input string $output = $f->minify($html);

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.