Download the PHP package fewagency/fluent-html without Composer

Fluent interface HTML builder for PHP

This package can be used on its own for building complex HTML structures, but most of its power comes when extended for specific purposes.

For example, fewagency/fluent-form, one of our other packages, helps you create accessible, well-formated, yet customizable HTML forms extending FluentHtmlElement.

• Introduction
  • What's the point?
  • Advanced Bootstrap example
  • When to use (and not)
  • Naming principles
• Installation
• Usage
  • Collections as input
    • Conditional output
  • Closures as input
  • Multiple attribute values
  • In Blade templates
• Methods reference
• Development
• Alternatives
• Authors - FEW Agency
• License

Introduction

Woha, that's a very elaborate way of writing:

So, then what's the point of it all? The power of FluentHtml comes from the ability to add collections of values, closures and conditions to the html building process. When the complexity grows you can build elements step by step and and trust the end result to be correct and well-formatted HTML in every situation.

For example when generating Bootstrap form-groups for an input or input-group with label, validation states, and help-text ...the desired HTML would look like this:

Generating the above in a PHP template could be a hassle. With if-statements repeated all over the place, it would be very prone to errors sneaking in. Using FluentHtml the code would probably take about the same space, but it would be a lot more readable, guaranteed to print correct and well-formatted HTML, and can be split in manageable and reusable chunks, like this:

When to use (and not)

FluentHtml should be used for those cases where you build complex html structures with many if-statements. Stay with your standard html views or templates for all the simple stuff!

If you're making something that should be reusable, consider creating a package of Elements extending FluentHtmlElement and publish it!

Naming principles

Public methods available on implementations of FluentHtmlElement (of which FluentHtml is one) should be named to hint their return types.

Any method that can, should return the called upon element ($this) to enable fluent chaining. Any method name not hinting about returning something else, should be fluent.

Methods not returning the same element

Methods that create, insert and return new FluentHtml instances relative to the current element ends with ...Element. Like containingElement(), precededByElement(), and wrappedInElement(). Extending packages may add similarly named methods that return specific types of elements, see fewagency/fluent-form for some examples.

Methods starting with get... of course returns values of the expected type, like getParentElement() returning an implementation of FluentHtmlElement and getId() returning a string.

Methods returning booleans start with is..., has..., or will....

Fluent methods - returning the same element

Method names starting with with... should always return the current element for fluent chaining. Like withContent() and withAttribute(), and in this category we also find withoutAttribute().

Methods adding conditions to an element may have names containing If or Unless, like onlyDisplayedIfHasContent().

Methods adding callbacks that will be triggered at certain events start with on..., before..., or after.... afterInsertion() is the only event currently supported.

Any other methods not following the above patterns, should return the current element for fluent chaining.

Installation & configuration

composer require fewagency/fluent-html

Optional facades

You may add Laravel facades in the aliases array of your project's config/app.php configuration file:

Dependencies

This package takes advantage of the Collection implementation (docs) and the Arrayable and Htmlable interfaces from Laravel's Illuminate components.

Internally FluentHtmlElement depends on HtmlBuilder to render html elements as strings and HtmlIdRegistrar to keep track of used element ids so they can be kept unique.

Usage

Collections as method input

Most methods accept arrays or collections (and other implementations of Arrayable) as input parameters. A value may sometimes also be a nested collection, in which case the whole collection is recursively flattened (with preserved associative keys). When flattening a collection, any duplicate associative keys will be merged over by those appearing later in the collection. Values with numeric keys are always appended.

Conditional output

String keys are usually displayed instead of their value if their corresponding evaluated value is truthy. This makes it possible to conditionally show or hide html contents and element attributes, depending on their value being true or false.

Closures as method input

Most values can be PHP closures in which case their evaluation is deferred as long as possible, usually until the object is rendered as a string. When a closure is evaluated it may return a value, boolean, arrayable, or even another closure, which in turn will be evaluated and merged into the collection of its context. All closures will receive the current FluentHtmlElement instance as their first parameter, this can be used for pretty advanced conditionals.

Multiple attribute values

If an html attribute is supplied more than one value, they will be concatenated into a comma-separated list.

Usage with Blade templates

Echoing the result in a template is easy because the string conversion as well as toHtml()of a FluentHtmlElement implementation always returns the full HTML structure from the top element down.

Both the escaping and the non-escaping Blade echo statements will render the full html tree:

Blade sections are available to yield as content using Blade's $__env variable:

Within Blade echo statements newlines as well as php comments are accepted, making it easy to enhance readability:

Methods reference

• Methods creating new elements
  • FluentHtml::create()
  • new FluentHtml()
• Methods modifying and returning the same element
  • Adding content
    • withContent()
    • withPrependedContent()
    • withRawHtmlContent()
    • withContentWrappedIn()
    • withDefaultContent()
  • Adding siblings
    • withPrecedingSibling()
    • withFollowingSibling()
    • withPrecedingRawHtml()
    • withFollowingRawHtml()
  • Manipulating attributes
    • withAttribute()
    • withoutAttribute()
    • withId()
    • withClass()
    • withoutClass()
  • Other fluent methods
    • withHtmlElementName()
    • onlyDisplayedIf()
    • onlyDisplayedIfHasContent()
    • afterInsertion()
• Methods returning a new element relative to the current
  • Inserting within the current element
    • containingElement()
    • startingWithElement()
  • Inserting next to the current element
    • followedByElement()
    • precededByElement()
  • Wrapping around the current element
    • wrappedInElement()
    • siblingsWrappedInElement()
• Methods for structure navigation
  • Finding ancestors
    • getParentElement()
    • getSiblingsCommonParent()
    • getRootElement()
    • getAncestorInstanceOf()
• Element state methods
  • getId()
  • hasClass()
  • getAttribute()
  • hasContent()
  • getContentCount()
  • willRenderInHtml()

Methods creating new elements

The FluentHtml constructor and the static create() function share the same signature:

Each FluentHtmlElement instance can be the start of a new chain of fluent method calls for modifying and adding more elements relative the previous. This is also true for the returned FluentHtml of methods returning a new element relative to the current.

A falsy $html_element_name makes the element render only its contents. The $html_element_name may also be a callable in which case it's evaluated just before rendering and that callable's return value will be used as the element name.

The optional $tag_contents will be inserted in the same manner as withContent().

The optional $tag_attributes will be inserted in the same manner as withAttribute().

Methods modifying and returning the same element

These methods can be chained to modify the current element step by step.

Adding content

These methods put html content inside the current element.

withContent($html_contents)

Add html content after existing content in the current element. Accepts multiple arguments that can be:

• strings (will be escaped)
• objects implementing Htmlable
• another instance of FluentHtmlElement
• arrayables containing any types from this list (including other arrayables)
• callables returning any types from this list (including other callables)

Alias for withAppendedContent()

withPrependedContent($html_contents)

Add html content before existing content in the current element. Same parameter options as withContent().

withRawHtmlContent($raw_html_content)

Add a raw string of html content last within this element.

withContentWrappedIn($html_contents, $wrapping_html_element_name, $wrapping_tag_attributes = [])

Add html contents last within this element, with each inserted new content wrapped in an element.

withDefaultContent($html_contents)

Set html content to display as default if no other content is set. Same parameter options as withContent().

Adding siblings

These methods put html siblings next to the current element and have the same parameter options as withContent() or just one string for the raw html ones.

withPrecedingSibling($html_siblings)

Add html outside and before this element in the tree.

withFollowingSibling($html_siblings)

Add html outside and after this element in the tree.

withPrecedingRawHtml($raw_html_sibling)

Add a raw string of html outside and before this element in the tree.

withFollowingRawHtml($raw_html_sibling)

Add a raw string of html outside and after this element in the tree.

Manipulating attributes

withAttribute($attributes, $value = true)

Add one or more named attributes with value to the current element. Overrides any set attributes with same name. Attributes evaluating to falsy will be unset. Use withClass() instead for those attributes.

The first parameter in the simplest form is the attribute name as string, but it can also be an array of attribute names and values, or a callable returning such an array.

If the first parameter is an attribute name string, its value is taken from the second parameter. Boolean values makes the attribute name print only if truthy. The attribute is omitted from print if the value is falsy.

withoutAttribute($attributes)

Remove one or more named attributes from the current element.

withId($desired_id)

Set the id attribute on the current element. Will check if the desired id is already taken and if so set another unique id.

withClass($classes)

Add one or more class names to the current element.

withoutClass($classes)

Remove one or more class names from the current element.

Other fluent methods

withHtmlElementName($html_element_name)

Set the html element name. The parameter can be a string or a callable returning a string.

onlyDisplayedIf($condition)

Will not display current element if any added condition evaluates to false. The parameter may be a boolean or a callable returning a boolean.

onlyDisplayedIfHasContent()

Will not display current element if it has no content. Useful to get rid of empty lists or other containers.

afterInsertion($callback)

Register callbacks to run after the current element is placed in an element tree.

The closure will receive the current FluentHtml instance as the first parameter, as with other closures as input.

It's usually a good idea to check for some condition on the element before manipulating it within the closure, because an element may be inserted into other elements many times throughout its lifetime.

Methods returning a new element relative to the current

These methods creates a new element, adds it relative the current element and returns that new element. This makes any chained methods switch to operate on the new element after the call.

Most of these methods share signature with the constructor.

Inserting within the current element

containingElement($html_element_name = null, $tag_contents = [], $tag_attributes = [])

Adds a new element last among this element's children and returns the new element.

Alias for endingWithElement()

startingWithElement($html_element_name, $tag_contents = [], $tag_attributes = [])

Adds a new element first among this element's children and returns the new element.

Inserting next to the current element

followedByElement($html_element_name, $tag_contents = [], $tag_attributes = [])

Adds a new element just after this element and returns the new element.

precededByElement($html_element_name, $tag_contents = [], $tag_attributes = [])

Adds a new element just before this element and returns the new element.

Wrapping around the current element

The wrapping methods have no parameter for setting contents. This is of course because the content is already there to be wrapped.

wrappedInElement($html_element_name = null, $tag_attributes = [])

Wraps only this element in a new element and returns the new element.

siblingsWrappedInElement($html_element_name, $tag_attributes = [])

Wraps this element together with its siblings in a new element and returns the new element.

Methods for structure navigation

These methods returns a found existing element or a new empty element put in the requested position. Useful for referencing other elements in the current tree, especially within closures as input but can also be used in a method chain to switch elements.

getParentElement()

Get or generate the closest parent for this element, even if it's unnamed.

getSiblingsCommonParent()

Get the closest named parent element or an unnamed parent if none found. This is the common parent of this element and its siblings as rendered in html.

getRootElement()

Get the root element of this element's tree.

getAncestorInstanceOf($type)

Get the closest ancestor in the tree that is an instance of the supplied type. Remember to supply the fully qualified class name. Returns null if none found.

Element state methods

These methods are used to query the properties and states of an element. Useful for conditionals within closures as input.

getId($desired_id = null)

Get the element's id string if set, or generate a new id. The optional parameter can be used to try a desired id string which will be used if not already taken, just like withId().

hasClass($class)

Find out if this element will have a specified class when rendered. The parameter should be a string and the return value is a boolean.

getAttribute($attribute)

Get the evaluated value of a named attribute. If an attribute has been set with a callable, it will be evaluated before returning.

The parameter should be a string and the returned value is usually a string or a boolean, but can be a collection if the attribute has been set with an arrayable. The returned value is null if the attribute hasn't been set.

hasContent()

Find out if this element will contain any content when rendered. Will return true if this element has content to render after evaluation.

getContentCount()

Get the number of content pieces in this element. Empty contents are counted too.

willRenderInHtml()

Find out if this element is set to render. Returns false if any condition for rendering the element fails.

Development

Testing

vendor/bin/phpunit

Alternatives

https://github.com/spatie/html-element has another interesting way of generating html.

Authors

I, Björn Nilsved, created this package while working at FEW.

License

The Fluent HTML builder is open-sourced software licensed under the MIT license