PHPackages                             myparcelcom/json-schema-form-builder - 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. myparcelcom/json-schema-form-builder

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

myparcelcom/json-schema-form-builder
====================================

A library that provides an object-oriented API for constructing forms, which can then be converted into a JSON Schema.

v2.0.3(5mo ago)07313Apache-2.0PHPPHP >=8.4CI passing

Since Apr 2Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/MyParcelCOM/json-schema-form-builder)[ Packagist](https://packagist.org/packages/myparcelcom/json-schema-form-builder)[ RSS](/packages/myparcelcom-json-schema-form-builder/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (7)Versions (11)Used By (3)

Json Schema Form Builder
========================

[](#json-schema-form-builder)

This library provides an object-oriented API for constructing forms, which can be converted into a JSON Schema.

This package includes the following functionalities:

1. Constructing forms and rendering them as `JSON Schema`.
2. Creating simple fields such as `text`, `number` and `checkbox`.
3. Creating choice fields such as `select`, `radio` and `multi-select`.
4. Grouping form fields (`group` element).
5. Adding translations to form elements using the `LabelTranslationCollection` class. This includes:
    - Field label translations (for all fields and groups).
    - Option labels (for fields with a finite set of options such as `Select` and `Radio`).
6. Defining values for form fields.

PHP 8
-----

[](#php-8)

The minimum PHP version is `8.4`. To update dependencies on a system without PHP 8 use:

```
docker run --rm --mount type=bind,source="$(pwd)",target=/app composer:2 composer update
```

Run tests
---------

[](#run-tests)

You can run the test through docker:

```
docker run -v $(pwd):/app --rm -w /app php:8.4-cli vendor/bin/phpunit
```

Usage
-----

[](#usage)

The following section provides examples of how to use the library to create forms and convert them into JSON Schema.

### Meta Fields

[](#meta-fields)

While `JSON Schema` is effective for laying out form structures, it has limitations in the information it allows to specify. To address this, properties that fall outside the scope of the `JSON Schema` specification will be stored as meta-fields. Setting these fields is handled using the `Meta.php` which currently supports the following:

- `help`: A string that describes the purpose of the field.
- `label_translations`: Translations for the label of the field. (the non-translated label is stored as the `description` property)
- `field_type`: Used to differentiate between fields that have the same JSON Schema format. **Only used for choice fields at the moment**
- `enum_labels`: Used to define labels for field options. (The keys are stored in the `enum` property) **Only for choice fields**
- `enum_label_translations`: Used to define translations for labels of field options. **Only for choice fields**

### Example: Constructing a Form and Converting it to a JSON Schema

[](#example-constructing-a-form-and-converting-it-to-a-json-schema)

```
use MyParcelCom\JsonSchema\FormBuilder\Form\Text;
use MyParcelCom\JsonSchema\FormBuilder\Form\Checkbox;
use MyParcelCom\JsonSchema\FormBuilder\Form\Select;
use MyParcelCom\JsonSchema\FormBuilder\Form\Option;
use MyParcelCom\JsonSchema\FormBuilder\Form\OptionCollection;
use MyParcelCom\JsonSchema\FormBuilder\Form\Form;

$textField = new Text(
    name: 'example_text',
    label: 'Example Text Field',
    isRequired: true,
    help: 'Please enter some text.',
);

$checkboxField = new Checkbox(
    name: 'example_checkbox',
    label: 'Example Checkbox Field',
    help: 'Check this box if applicable.'
);

$selectField = new Select(
    name: 'example_select',
    label: 'Example Select Field',
    options: new OptionCollection(
        new Option('option_1_key', 'Option 1 Label'),
        new Option('option_2_key', 'Option 2 Label')
    ),
    isRequired: true,
    help: 'Please select an option.',
);

$form = new Form($textField, $checkboxField, $selectField);
$form->toJsonSchema();
```

The resulting JSON Schema will look as follows:

```
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "additionalProperties": false,
  "required": [
    "example_text",
    "example_select"
  ],
  "properties": {
    "example_text": {
      "type": "string",
      "description": "Example Text Field",
      "meta": {
        "help": "Please enter some text."
      }
    },
    "example_checkbox": {
      "type": "boolean",
      "description": "Example Checkbox Field",
      "meta": {
        "help": "Check this box if applicable."
      }
    },
    "example_select": {
      "type": "string",
      "description": "Example Select Field",
      "enum": [
        "option_1_key",
        "option_2_key"
      ],
      "meta": {
        "help": "Please select an option.",
        "enum_labels": {
          "option_1_key": "Option 1 Label",
          "option_2_key": "Option 2 Label"
        }
      }
    }
  }
}
```

### Example: Setting values

[](#example-setting-values)

In some cases, you may require setting a value on a form element during its construction. This includes:

1. Populating the field with values previously set by the user
2. Default values

To support this, form elements allow setting a `value` property. These values can be obtained in a form by calling the `getValues()` method on the `Form.php` class. This method returns an associative array with the field names as keys and their respective values. This means that when serialized to JSON, it will be rendered as a JSON object (see example below).

```
use MyParcelCom\JsonSchema\FormBuilder\Form\Text;
use MyParcelCom\JsonSchema\FormBuilder\Form\Checkbox;
use MyParcelCom\JsonSchema\FormBuilder\Form\Select;
use MyParcelCom\JsonSchema\FormBuilder\Form\Option;
use MyParcelCom\JsonSchema\FormBuilder\Form\OptionCollection;
use MyParcelCom\JsonSchema\FormBuilder\Form\Form;

$textField = new Text(
    name: 'example_text',
    label: 'Example Text Field',
    value: 'previously-set-value'
);

$checkboxField = new Checkbox(
    name: 'example_checkbox',
    label: 'Example Checkbox Field',
);

$selectField = new Select(
    name: 'example_select',
    label: 'Example Select Field',
    options: new OptionCollection(
        new Option('option_1_key', 'Option 1 Label'),
        new Option('option_2_key', 'Option 2 Label')
    ),
    value: 'option_2_key'
);

$form = new Form($textField, $checkboxField, $selectField);
$form->getValues();
```

When serialized to JSON, the resulting array will look as follows:

```
{
  "example_text": "previously-set-value",
  "example_select": "option_2_key"
}
```

### Example: Grouping elements

[](#example-grouping-elements)

```
use MyParcelCom\JsonSchema\FormBuilder\Form\Form;
use MyParcelCom\JsonSchema\FormBuilder\Form\Group;
use MyParcelCom\JsonSchema\FormBuilder\Form\FormElementCollection;
use MyParcelCom\JsonSchema\FormBuilder\Form\Text;
use MyParcelCom\JsonSchema\FormBuilder\Form\Checkbox;
use MyParcelCom\JsonSchema\FormBuilder\Form\Number;
use MyParcelCom\JsonSchema\FormBuilder\Translations\LabelTranslationCollection;

$group = new Group(
    name: 'my_group',
    label: 'My Group',
    children: new FormElementCollection(
        new Text(name: 'my_text', label: 'My Text Field', isRequired: true),
        new Checkbox(name: 'my_checkbox', label: 'My Checkbox Field'),
        new Number(name: 'my_number', label: 'My Number Field')
    ),
    help: 'This following fields are related to...',
);

$someOtherTextField = new Text(
    name: 'some_other_text',
    label: 'Some Other Text Field',
    help: 'Please enter some other text.',
);

$form = new Form($group, $someOtherTextField);
```

The resulting JSON Schema property for the group will look as follows:

```
{
  "my_group": {
    "type": "object",
    "description": "My Group",
    "required": ["my_text"],
    "properties": {
      "my_text": {
        "type": "string",
        "description": "My Text Field"
      },
      "my_checkbox": {
        "type": "boolean",
        "description": "My Checkbox Field"
      },
      "my_number": {
        "type": "number",
        "description": "My Number Field"
      }
    },
    "meta": {
      "help": "This following fields are related to..."
    }
  }
}
```

NOTE: When defining groups, required properties that are its direct children will be added to its `required` property rather than the `required` property of the parent form.

#### Values in Groups

[](#values-in-groups)

If children of a group have a value set, their values will be rendered as a nested structure. For example:

```
use MyParcelCom\JsonSchema\FormBuilder\Form\Text;
use MyParcelCom\JsonSchema\FormBuilder\Form\Group;
use MyParcelCom\JsonSchema\FormBuilder\Form\Form;

$group = new Group(
    name: 'group',
    label: 'Group',
    children: new FormElementCollection(
        new Text(name: 'group_child', label: 'Group Child', value: 'some_value')
    ),
);

$someOtherField = new Text(
    name: 'some_other_field',
    label: 'Some Other Field',
    value: 'some_other_value'
);

$form = new Form($group, $someOtherField);
$form->getValues();
```

When serialized, `getValues()` will result in the following JSON object:

```
{
  "group": {
    "group_child": "some_value"
  },
  "some_other_field": "some_other_value"
}
```

### Example: Adding translations to a form element's label

[](#example-adding-translations-to-a-form-elements-label)

```
use MyParcelCom\JsonSchema\FormBuilder\Form\Text;
use MyParcelCom\JsonSchema\FormBuilder\Form\Checkbox;
use MyParcelCom\JsonSchema\FormBuilder\Translations\LabelTranslationCollection;
use MyParcelCom\JsonSchema\FormBuilder\Translations\LabelTranslation;
use MyParcelCom\JsonSchema\FormBuilder\Translations\Locale

$textField = new Text(
    name: 'example_text',
    label: 'Example Text Field',
    help: 'Please enter some text.',
    labelTranslations: new LabelTranslationCollection(
        new LabelTranslation(Locale::DE_DE, 'Beispiel Textfeld'),
        new LabelTranslation(Locale::EL_GR, 'Παράδειγμα πεδίου κειμένου'),
        new LabelTranslation(Locale::EN_GB, 'Example Text Field'),
        new LabelTranslation(Locale::ES_ES, 'Campo de texto de ejemplo'),
        new LabelTranslation(Locale::FR_FR, 'Champ de texte exemple')
        new LabelTranslation(Locale::IT_IT, 'Campo di testo di esempio'),
        new LabelTranslation(Locale::NL_NL, 'Voorbeeld tekstveld'),
        new LabelTranslation(Locale::PL_PL, 'Przykładowe pole tekstowe'),
        new LabelTranslation(Locale::PT_PT, 'Campo de texto de exemplo'),
    )
);
```

The resulting JSON Schema property will look as follows:

```
{
  "example_text": {
    "type": "string",
    "description": "Example Text Field",
    "meta": {
      "help": "Please enter some text.",
      "label_translations": {
        "de-DE": "Beispiel Textfeld",
        "el-GR": "Παράδειγμα πεδίου κειμένου",
        "en-GB": "Example Text Field",
        "es-ES": "Campo de texto de ejemplo",
        "fr-FR": "Champ de texte exemple",
        "it-IT": "Campo di testo di esempio",
        "nl-NL": "Voorbeeld tekstveld",
        "pl-PL": "Przykładowe pole tekstowe",
        "pt-PT": "Campo de texto de exemplo"
      }
    }
  }
}
```

### Example: Adding translations to a Form element's labels and option labels

[](#example-adding-translations-to-a-form-elements-labels-and-option-labels)

```
use MyParcelCom\JsonSchema\FormBuilder\Form\RadioButtons;
use MyParcelCom\JsonSchema\FormBuilder\Form\OptionCollection;
use MyParcelCom\JsonSchema\FormBuilder\Form\Option;
use MyParcelCom\JsonSchema\FormBuilder\Translations\LabelTranslationCollection;
use MyParcelCom\JsonSchema\FormBuilder\Translations\LabelTranslation;

$radioField = new RadioButtons(
    name: 'example_radio',
    label: 'Example Radio Field',
    labelTranslations: new LabelTranslationCollection(
        new LabelTranslation(
            locale: Locale::DE_DE,
            label: 'Beispiel Radiofeld'
        ),
        new LabelTranslation(
            locale: Locale::EL_GR,
            label: 'Παράδειγμα πεδίου ραδιοφώνου'
        ),
        new LabelTranslation(
            locale: Locale::EN_GB,
            label: 'Example Radio Field'
        ),
        // ...
    )
    options: new OptionCollection(
        new Option(
            key: 'option_1_key',
            label: 'Option 1 Label',
            labelTranslations: new LabelTranslationCollection(
                new LabelTranslation(
                    locale: Locale::DE_DE,
                    label: 'Option 1 Beschriftung'
                ),
                new LabelTranslation(
                    locale: Locale::EL_GR,
                    label: 'Επιλογή 1 Ετικέτα'
                )
                new LabelTranslation(
                    locale: Locale::EN_GB,
                    label: 'Option 1 Label'
                ),
                // ...
            )
        ),
        new Option(
            key: 'option_2_key',
            label: 'Option 2 Label',
            labelTranslations: new LabelTranslationCollection(
                new LabelTranslation(
                    locale: Locale::DE_DE,
                    label: 'Option 2 Beschriftung'
                ),
                new LabelTranslation(
                    locale: Locale::EL_GR,
                    label: 'Επιλογή 2 Ετικέτα'
                )
                new LabelTranslation(
                    locale: Locale::EN_GB,
                    label: 'Option 2 Label'
                ),
                // ...
            )
        )
    ),
    help: 'Please select an option.',
```

The resulting JSON Schema property will look as follows:

```
{
  "example_radio": {
    "type": "string",
    "description": "Example Radio Field",
    "enum": [
      "option_1_key",
      "option_2_key"
    ],
    "meta": {
      "help": "Please select an option.",
      "enum_labels": {
        "option_1_key": "Option 1 Label",
        "option_2_key": "Option 2 Label"
      },
      "label_translations": {
        "de-DE": "Beispiel Radiofeld",
        "el-GR": "Παράδειγμα πεδίου ραδιοφώνου",
        "en-GB": "Example Radio Field"
      },
      "enum_label_translations": {
        "option_1_key": {
          "de-DE": "Option 1 Beschriftung",
          "el-GR": "Επιλογή 2 Ετικέτα",
          "en-GB": "Option 1 Label"
        },
        "option_2_key": {
          "de-DE": "Option 2 Beschriftung",
          "el-GR": "Επιλογή 2 Ετικέτα",
          "en-GB": "Option 2 Label"
        }
      }
    }
  }
}
```

### Example: Multi-Select

[](#example-multi-select)

```
use MyParcelCom\JsonSchema\FormBuilder\Form\MultiSelect;

$multiSelectField = new MultiSelect(
    name: 'example_multi_select',
    label: 'Example Multi-Select Field',
    options: new OptionCollection(
        new Option('option_1_key', 'Option 1 Label'),
        new Option('option_2_key', 'Option 2 Label')
    ),
    help: 'Please select one or more options.',
);
```

The resulting JSON Schema property will be of type `array` and look as follows:

```
{
  "example_multi_select": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": [
        "option_1_key",
        "option_2_key"
      ]
    },
    "meta": {
      "help": "Please select one or more options.",
      "enum_labels": {
        "option_1_key": "Option 1 Label",
        "option_2_key": "Option 2 Label"
      }
    }
  }
}
```

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance70

Regular maintenance activity

Popularity17

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 92.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~48 days

Total

6

Last Release

166d ago

Major Versions

v1.1.0 → v2.0.02025-05-19

### Community

Maintainers

![](https://www.gravatar.com/avatar/3841efa190ba5131014f8855131e3d38ef5ccd57c51000966348108e63c83612?d=identicon)[myparcelcom](/maintainers/myparcelcom)

---

Top Contributors

[![daniel-myparcel](https://avatars.githubusercontent.com/u/193501397?v=4)](https://github.com/daniel-myparcel "daniel-myparcel (121 commits)")[![yoan-myparcel](https://avatars.githubusercontent.com/u/46448148?v=4)](https://github.com/yoan-myparcel "yoan-myparcel (8 commits)")[![M4tini](https://avatars.githubusercontent.com/u/4649537?v=4)](https://github.com/M4tini "M4tini (1 commits)")[![NickVries](https://avatars.githubusercontent.com/u/32866117?v=4)](https://github.com/NickVries "NickVries (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/myparcelcom-json-schema-form-builder/health.svg)

```
[![Health](https://phpackages.com/badges/myparcelcom-json-schema-form-builder/health.svg)](https://phpackages.com/packages/myparcelcom-json-schema-form-builder)
```

###  Alternatives

[grumpydictator/firefly-iii

Firefly III: a personal finances manager.

22.8k69.3k](/packages/grumpydictator-firefly-iii)[wireui/wireui

TallStack components

1.8k1.3M16](/packages/wireui-wireui)[pocketmine/pocketmine-mp

A server software for Minecraft: Bedrock Edition written in PHP

3.5k74.6k86](/packages/pocketmine-pocketmine-mp)[firefly-iii/data-importer

Firefly III Data Import Tool.

7545.8k](/packages/firefly-iii-data-importer)[ramonrietdijk/livewire-tables

Dynamic tables for models with Laravel Livewire

21147.4k](/packages/ramonrietdijk-livewire-tables)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)