Download the PHP package monolyth/formulaic without Composer

Formulaic

Object-oriented form utilities for PHP8.1+

HTML forms suck. Well, no, they're superduper handy, but writing them and validating them server-side can be a pain. Formulaic offers a set of utilities to ease that pain.

Basic usage

Define a form with some fields and other requirements:

In your template, either use the API to manually tweak your output, or simply __toString the form to use the defaults:

You can __toString individual fields:

To validate your form:

To get a list of errors:

Forms can contain fieldsets:

And in your output:

Custom elements in forms

Simply add strings to the form; they will be outputted verbatim:

Under the hood

As you will have guessed, the Post and Get forms look at posted and get data respectively. This means any matching data in the superglobal (which, for Post, includes $_FILES) is automagically set on the form. For elements in groups (excluding fieldsets), Formulaic assumes they will be in a sub-array:

This will match $_GET['foo']['bar'] for a value.

For checkbox groups (a set of related checkboxes, e.g. for settings), the values are presumed to be in their own array. E.g. with a checkbox group named 'foo' the values will be passed as $_POST['foo'] = [1, 2, 3].

Adding tests

Form elements can contain tests, which the vaild() and error() methods use to produce output. A number of tests (like isRequired()) are pre-supplied, but you can easily add your own via the addTest method on elements:

The above test will fail unless the user enters "bar" into the text input.

Binding models

Where Formulaic also really shines is in propagating the form data to your models. All the boilerplate code containing numerous isset calls? Gone!

Your model is an object. Literally any object. What you want is for any property's previously filled value to be automatically set on your form, and for any value entered by the user to be updated on the object (which you can then persist to a database or whatever, that's up to you). Guess what? It's easy!

In the above example, the form in question - when __toStringed - will have a default value of "bar" for the foo input. If $_POST['foo'] happens to contain "buzz", it will instead contain that. Even better, after the call to bind it will also be so that $model->foo === 'buzz' equals true. Awesome! That's a gazillion lines of code you no longer have to think about!

Binding can be done on any level, just remember that it needs to be on an object and that its (sub)properties must match the element's names.

You'll notice that this ties the model structure to the form buildup; however, that doesn't matter. The form elements are displayed "as is", it's just their names that need to match the model.

Transforming data

In the real world, model objects are often a lot more complicated than HTML forms, which basically deal with strings. Enter transformers: Formulaic's way of converting data to and from your models.

All elements support the withTransformer method, which basically accepts a callable. The idea here is that the callable's argument is type hinted (so as to determine which transformer to use) and it returns a suitable value based on that type. An acceptable transformer for a certain situation might be:

You can define multiple transformers in one go with the withTransformers method (note the plural). Each argument is a callable.

Typically, you'll need two transformers: one from the model to the form, and one from the form back to the model. In some cases, the input may vary depending on the complexity of your project; define as many transformers as you need.

The input type hint may be a union in which case the transformer is valid for multiple types. Intersection type hints are not supported as they wouldn't really make sense in a transformation context.

GET forms gotcha!

In PHP, it is not possible to distinguish a "regular" page load from one triggered by a submitted GET form (unlike POST requests). To determine whether or not the user supplied values, Formulaic simply checks $_GET for truthiness. Note that this may or may not be sufficient for your needs; theoretically, an entirely empty form could be submitted which should still trigger this, or the URL may already contain (unrelated) GET-parameters.

In these corner cases, extend the Get form and implement your own wasSubmitted method doing an alternative check, e.g. for a hidden form field or a named submit button.

For post forms, the user is assumed to have supplied values whenever $_SERVER['REQUEST_METHOD'] == 'POST'. Again, situations may arise where this check is not good enough for you - extend and override, again.

Other methods than GET or POST

In casu, PUT or DELETE may crop up. These are not supported out of the box, since Formulaic is an HTML form library, and HTML only supports GET and POST. However, it is not unthinkable you would like to use validation and binding logic in controllers handling AJAX calls for instance. In that case, feel free to extend your own form class.

Any extension will want to implement the getSource method, e.g. for PUT you will manually parse file_get_contents('php://input'). Since we can't know what that contains (likely JSON, but assumption is the mother of all fuckup...) you'll need to write your own implementation suiting your needs.

Similarly, DELETE can contain GET data in the URL. We're not really sure when this would be necessary, but there you have it - a custom Delete form would likely extend GET.