mcmanning/form

A lightweight approach for implementing form widget abstraction within PHP applications

Forms!

A lightweight approach for implementing form widget abstraction within PHP applications.

Benefits

• Uses established HTML5 naming conventions for modifying widget attributes to reduce API complexity
• UI framework agnostic. Follows MVC separation of concerns to keep view templates separate from form models
• View engine agnostic. Ships with support for league/plates but may utilize any other view engine for rendering
• No globals, no singletons. Follows modern DI patterns for testable code
• PSR-1, PSR-2, and PSR-4 compliant

Installation

Via Composer:

{
    "repositories": [
        {
            "url": "https://github.com/McManning/Form.git",
            "type": "git"
        }
    ],
    "require": {
        "mcmanning/form": "dev-master"
    }
}

Usage

For users of league/plates

Add a folder to your Plates Engine for your widget templates (check out tests/fixtures/plates for example implementations):

$engine = new League\Plates\Engine();
$engine->addFolder('form', '/path/to/element/templates');

Create a new instance of Form\Renderer\PlatesRenderer, injecting the Plates Engine as a dependency as well as the folder name of your templates:

$renderer = new Renderer\PlatesRenderer($engine, 'form');

Use that renderer as a dependency for new widgets:

$myInput = new Input($renderer);
$myInput
    ->id('my-input')
    ->name('myInput')
    ->maxlength(100)
    ->value('Hello World');

print $myInput;

Alternatively, if doing dependency injection for every widget isn't your style, you can use Form\Factory to perform injection once, and carry forward with all new widgets from that factory:

$factory = new Factory($renderer);

print $factory->input()
        ->id('my-input')
        ->name('myInput');

Testing

$ phpunit

Contributing

Pull requests welcome.

Ensure code follows basic PSR-1, PSR-2 guidelines:

$ phpcs --standard=PSR1,PSR2 src/

License

The MIT License (MIT): https://opensource.org/licenses/MIT

form's Issues

Support passing renderer-specific attributes to widgets

Some UI frameworks may desire additional attributes on widgets unique to that framework implementation. This should support applying those attributes to widgets to be passed through the renderer, independent of attribute magic methods.

Use Cases

• A UI framework that defines left/right justification for form labels. The templates of this framework would then apply that justification class to the widget's <label>.
• Abstracting away row/column containers for grid based UI frameworks (Bootstrap, Materialize, etc). Example of this may include templates in the form:

<div class="row">
  <div class="col s12 m8">
   <input type="text" ... />
   <label>...</label>
 </div>
</div>

And an implementation may look something like:

print $factory->input()
  ->view('medium', 8)
  ->view('small', 12);

Inconsistent documentation (Radioset)

Radioset::options documents parameter to be mapping input[name] to input[value] but that's not the case for the implementation.