Derafu: Form - Declarative Forms, Seamless Rendering
A modern PHP form library that leverages a declarative, schema-based approach to form definition and rendering, compatible with JSON Forms while providing a powerful backend-centric workflow.
WIP: Work In Progress.
Key Features
- Schema-Based Form Definition: Define forms using structured arrays that clearly separate data schemas from UI layouts.
- Backend-First Approach: Built for PHP developers who want control over form generation with minimum effort.
- Symfony-Compatible Twig Extensions: Familiar syntax for Symfony developers, minimizing learning curve.
- Decoupled Rendering System: Separate your form logic from its presentation with specialized renderers.
- JSON Forms Compatibility: Define once, use anywhere - same schema can be used with frontend JSON Forms library.
- Automatic Form Generation: Generate form UI schemas automatically from your data models.
- Extensible Architecture: Easily add custom types, layouts and renderers.
Why Choose This Library?
Compared to Traditional PHP Form Libraries
Traditional PHP form libraries often tightly couple form definition with HTML generation, making it difficult to separate concerns. This library takes a different approach:
- Declarative Rather Than Imperative: Define what your form should be rather than how it should be built, step by step.
- Clear Separation of Concerns: Schema (data structure) is separate from UI schema (presentation) and data (values).
- Powerful Layouts Without HTML Knowledge: Create complex, multi-column layouts without writing HTML.
Compared to Frontend-Only Solutions
Unlike frontend-only form builders, this library:
- Keeps Validation Logic Server-Side: Where it belongs for security-critical applications.
- Provides PHP-Native Form Definition: No need to write JavaScript to define your forms.
- Works With or Without JavaScript: Generate the same forms for both traditional and SPA applications.
Installation
Install the library using Composer:
composer require derafu/form
Basic Usage
Creating a Simple Form
// Define the form structure.
$definition = [
'schema' => [
'type' => 'object',
'properties' => [
'name' => [
'type' => 'string',
'title' => 'Full Name',
],
'email' => [
'type' => 'string',
'format' => 'email',
'title' => 'Email Address',
],
],
'required' => ['name', 'email'],
],
'uischema' => [
'type' => 'VerticalLayout',
'elements' => [
[
'type' => 'Control',
'scope' => '#/properties/name',
],
[
'type' => 'Control',
'scope' => '#/properties/email',
],
],
],
'data' => [
'name' => '',
'email' => '',
],
];
// Create the form.
$form = $formFactory->create($definition);
Rendering with Twig
{# Simple rendering of the entire form. #}
{{ form(form) }}
{# Or with more control over individual components. #}
{{ form_start(form) }}
{{ form_row(form.fields.name) }}
{{ form_row(form.fields.email) }}
<button type="submit" class="btn btn-primary">Submit</button>
{{ form_end(form) }}
Automatic Schema Generation
The library can automatically generate a schema from your data:
$definition = [
'data' => [
'name' => 'John Doe',
'email' => '[email protected]',
'age' => 34,
'birthdate' => "1990-01-01",
],
];
// Schema and UI schema will be automatically generated.
$form = $formFactory->create($definition);
Integration with JSON Forms
This library’s form definitions are compatible with the JSON Forms JavaScript library, allowing you to use the same definitions for both server-side and client-side rendering:
<div id="json-form-container"></div>
// https://raw.githubusercontent.com/derafu/form/refs/heads/main/assets/js/jsonforms-viewer.js
import './jsonforms-viewer.js';
// Render the form and save the reference.
const formDefinition = {{ jsonFormsDefinition | json_encode | raw }};
const formInstance = window.renderJsonForm('json-form-container', formDefinition);
// You can now use `formInstance` to get the form data or its errors.
Development Requirements
To render forms using JSON Forms you must install:
npm install @jsonforms/core @jsonforms/react @jsonforms/material-renderers \
react react-dom @mui/material @emotion/react @emotion/styled
This is already included in the package by default, so you just need to run it:
npm install
Form Layouts
The UI schema supports various layout types by default:
- VerticalLayout: Fields stacked vertically.
- HorizontalLayout: Fields arranged horizontally.
- Group: Logical grouping of fields, often with a label.
- Categorization: Tab-based layouts for complex forms.
Example:
$uischema = [
'type' => 'VerticalLayout',
'elements' => [
[
'type' => 'Group',
'label' => 'Personal Information',
'elements' => [
['type' => 'Control', 'scope' => '#/properties/name'],
['type' => 'Control', 'scope' => '#/properties/email'],
],
],
[
'type' => 'Group',
'label' => 'Address',
'elements' => [
['type' => 'Control', 'scope' => '#/properties/street'],
['type' => 'Control', 'scope' => '#/properties/city'],
],
],
],
];
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
License
This package is open-sourced software licensed under the MIT license.
In the examples, the demo in JavaScript uses the JSON Forms library.