Download the PHP package e0ipso/schema-forms without Composer

Schema Forms

Schema Forms builds forms for PHP frameworks from a JSON Schema that describes the data. You give it the schema and, optionally, a UI schema with per-property display hints. It returns a form definition for the framework.

Drupal is the only supported framework. The generator returns a Drupal Form API render array.

Installation

A Drupal project that uses this library usually requires it already. To require it yourself:

The package requires PHP 8.3 or later. CI runs on PHP 8.3 and 8.4. The Drupal generator uses Drupal core classes, and Drupal core is only a dev dependency here, so run the generator inside a Drupal site.

Usage

Take this JSON Schema for a registration form:

And this UI schema:

Pass both to the generator. Decode the schema to objects and the UI schema to arrays:

$form is this render array. The root container also carries #json_schema (the decoded schema) and #element_validate, left out here:

The input schema must be a valid draft-04 JSON Schema whose root type is object. Anything else makes transform() throw a TypeError.

Context keys

The Context accepts three keys, all optional:

• ui_hints: the UI schema, as an array keyed by property name.
• form_state: the form's FormStateInterface. Array properties keep their item list in the form state storage, so pass the real form state when the schema has arrays. Without it the generator uses a fresh FormState, and appended items are lost on rebuild.
• current_input: previously saved values, keyed like the schema. A value here becomes the element's #default_value and wins over the schema's default.

How schema types become elements

A type with no element in this list, such as null, renders as a disabled item that says the property cannot be edited. It does not disappear from the form.

When type is a list such as ["string", "null"], the generator uses the first entry. Put null last: ["null", "string"] renders as the "cannot be edited" item.

The element title comes from ui:title, then the schema title, then the property name with _ and - turned into spaces and each word capitalized. Enum option labels come from ui:enum mappings, or the enum value formatted the same way.

UI schema data

The same data shape can be collected with different form controls. The UI schema picks them. Its keys are property names. For an object property, nest the sub-property hints under the property's key. An array property passes its hints on to every item.

Supported controls:

• ui:title: the element label. Defaults to the property's title.
• ui:help: the element description. Defaults to the property's description.
• ui:placeholder: placeholder text for the input.
• ui:widget: a Drupal Form API element type, such as select, textarea, password or hidden. The generator uses the value as #type unchanged and does not check it. A name Drupal does not know, such as the react-jsonschema-form widget updown, renders nothing.
• ui:enabled: 0 sets #disabled on the element.
• ui:visible: 0 sets #visible to FALSE. Drupal core does not read #visible, so the element still renders unless your code acts on that key.
• ui:enum: controls the labels for select, radio and checkbox options. ui:enum.labels.mappings maps each enum value to a label, e.g. {"uuid1": "Super duper product"}.

Other keys are ignored.

Validating submissions

The root container has an #element_validate callback. When Drupal validates the form, it:

1. Removes the add and remove button values that array properties leave in the submission.
2. Casts the submitted strings to the schema types. Numeric strings become int or float, "0" and "1" become booleans on a boolean property, and an empty string becomes NULL on a nullable property that cannot hold it.
3. Validates the result against the schema with justinrainbow/json-schema. Each error is set on the element it belongs to. Errors that match no element are joined into one error on the container.

Limitations

• $ref is not resolved. A property that is only a $ref throws a TypeError.
• Only the root required list sets #required. A required list inside a nested object does not mark its sub-properties.

Development

composer test runs GrumPHP. It runs PHPUnit, PHP_CodeSniffer with the Drupal and DrupalPractice standards, PHP lint, phpmnd, composer normalize, and YAML and JSON lint.

GrumPHP also installs git hooks that check commit messages and branch names. Commits follow Conventional Commits (fix(drupal): ..., with a subject of 50 characters or fewer). Branches are named <type>/<kebab-case>, for example fix/enum-options. semantic-release tags a release from the commit messages on every push to master.