PHPackages                             formular/formular - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. formular/formular

AbandonedLibrary[Utility & Helpers](/categories/utility)

formular/formular
=================

Form Builder

25.8k↓16.7%1PHP

Since Aug 7Pushed 11y ago1 watchersCompare

[ Source](https://github.com/bigwhoop/formular)[ Packagist](https://packagist.org/packages/formular/formular)[ RSS](/packages/formular-formular/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (1)

Formular
========

[](#formular)

[![Build Status](https://camo.githubusercontent.com/640a4e454c2b1b4ff56139531178792390aaf9f672d974178bb58b0639b6720a/68747470733a2f2f7472617669732d63692e6f72672f62696777686f6f702f666f726d756c61722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/bigwhoop/formular)[![Code Coverage](https://camo.githubusercontent.com/7d6724dc4f0b31b186862fd82657497a0e4e82d537899ea1c98b0f375d6c08eb/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f62696777686f6f702f666f726d756c61722f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/bigwhoop/formular/?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/75ee2c1c903bd835376264c07d5ac76cbefa973a315c1a6d5882ee2f249b1449/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f62696777686f6f702f666f726d756c61722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/bigwhoop/formular/?branch=master)

A light-weight, template-oriented form builder.

Installation
------------

[](#installation)

Use composer to install package `formular/formular`.

Features
--------

[](#features)

- Build custom forms writing re-usable templates/view scripts.
- Re-use existing templates with support for front-end frameworks like Bootstrap.
- Write PHP, no need to learn a new syntax.
- Non-intrusive filtering and validation support. Take your 3rd party library and plug it in using the available adapters.
- Light-weight, extensible and unit tested.

Terminology
-----------

[](#terminology)

- **Template**: A view script written in PHP and HTML.
- **Template Value**: A value inside a template. Most likely coming from an element definition.
- **Element**: A part of the form that is rendered using a specific template.

A simple example
----------------

[](#a-simple-example)

Consider the following:

```
// ./templates/input.phtml

     >

// ./templates/submit.phtml

// ./src/form.php
use bigwhoop\Formular\Form;
use bigwhoop\Formular\TemplateFactory\FileBasedFactory;

$templateFactory = new FileBasedFactory();
$templateFactory->addTemplatesPath(__DIR__ . '/../templates');

$form = new Form();
$form->setTemplatesFactory($templateFactory);
$form->addElement('input', ['id,name' => 'name', 'placeholder' => 'Your name']);
$form->addElement('input', ['id,name,type' => 'email', 'placeholder' => 'Your email address']);
$form->addElement('submit', ['label' => 'Register']);
echo $form->render();

```

This will output ...

```

    Register

```

So what is happening here?

First we create some `.phtml` files in a directory. This templates directory we then register with the form using a new `FileBasedFactory`. The name of the files minus the extension are used as the template's name. Next we define some elements using the available templates. When rendering the specified element, its attributes will get passed on to the templates.

### Conventions

[](#conventions)

Here are the conventions you need to know.

- All elements are added to a queue.
- This means that ...
- the elements are rendered in the same order they were added to the form.
- each element is only rendered once.

Templates
---------

[](#templates)

Templates are provided by template factories. The easiest factory is a the file-based `FileBasedFactory`; as seen in the first example. There templates are `.phtml` files laying around in directories. You can add as many such directories to your form as you wish.

### Template namespaces

[](#template-namespaces)

Let's have a look at the following example:

```
// ./templates1/input.phtml
// ./templates2/input.phtml
...
$templateFactory->addTemplatesPath('./templates1');
$templateFactory->addTemplatesPath('./templates2');
...
$form->addElement('input');
$form->render();

```

This will make Formular go BOOM becaue it doesn't know which `input` template to use. To solve this problem you can use namespaces.

```
$templateFactory->addTemplatesPath('./templates1');
$templateFactory->addTemplatesPath('./templates2', 'foo');
...
$form->addElement('input');     // uses ./templates1/input
$form->addElement('input@foo'); // uses ./templates2/input

```

You can also define a default namespace.

```
$templateFactory->addTemplatesPath('./templates1', 'fu');
$templateFactory->addTemplatesPath('./templates2', 'foo');
$templateFactory->setDefaultNamespace('foo');
...
$form->addElement('input@fu');  // => uses ./templates1/input
$form->addElement('input');     // => uses ./templates2/input
$form->addElement('input@foo'); // => uses ./templates2/input

```

### Template values

[](#template-values)

Inside templates you can access the element data/attributes using `$this->[KEY]`. This will provide access to a `Value` object with a set of little helpers to make things easier. Even if the attribute does not exist you'll get such an object. It's default value will be `null`.

```
// Returns a Value object representing attribute 'foo'.
                 # instance of \bigwhoop\Formular\Template\Value

// Prints an escaped string representing attribute 'foo'.
                          # '[SAFE_VALUE]' or '' if value is empty
                   # '[SAFE_VALUE]' or '' if value is empty
              # '[SAFE_VALUE]' or 'bar' if value is empty

// Returns the value the attribute encapsulates.
          # [VALUE] or null if no value was set
     # [VALUE] or 'bar' if value is empty

// Prints a string in the format of '[KEY]="[VALUE]"'. Prints an empty string if the value is empty.
                  # 'foo="[SAFE_VALUE]"' or '' if value is empty
             # 'foo="[SAFE_VALUE]"' or 'foo="bar"' if value is empty

// Prints a string in the format of '[KEY]'. Prints an empty string if the value is empty.
                  # 'foo'/[KEY] or '' if value is empty
              # 'foo'/[KEY]
             # 'foo'/[KEY] or '' if value is empty

```

Template helpers
----------------

[](#template-helpers)

Inside templates you can also use some helper methods using `$this->[HELPER]()`.

```
// Pass the current element data to a different template

// Render multiple attributes at once

... same as ...

// Render multiple properties at once

... same as ...

```

Providers
---------

[](#providers)

The following forms/templates have been created so far:

- [Bootstrap 3](https://github.com/bigwhoop/formular-form-bootstrap3)

Other packages:

- [Laravel Integration](https://github.com/bigwhoop/formular-provider-laravel)

Bindings
--------

[](#bindings)

### Continue binding

[](#continue-binding)

Use the continue binding to define where the next template should be rendered. By default the next template is rendered and appended to the current template.

For ...

```