PHPackages salesrender/plugin-component-form - 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. salesrender/plugin-component-form ActiveLibrary salesrender/plugin-component-form ================================= SalesRender plugins form component 0.11.6(1y ago)01.2k↓100%4proprietaryPHPPHP >=7.4.0 Since Jul 8Pushed 2mo ago2 watchersCompare [ Source](https://github.com/SalesRender/plugin-component-form)[ Packagist](https://packagist.org/packages/salesrender/plugin-component-form)[ RSS](/packages/salesrender-plugin-component-form/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (2)Versions (46)Used By (4) salesrender/plugin-component-form ================================= [](#salesrenderplugin-component-form) Form definition component for the SalesRender plugin ecosystem. Provides a hierarchical form system (`Form` -> `FieldGroup` -> `FieldDefinition`) with typed fields, validation, dependencies between fields, autocomplete, and preview capabilities. Used by every SalesRender plugin to declare its settings and batch configuration forms. Installation ------------ [](#installation) ``` composer require salesrender/plugin-component-form ``` Requirements ------------ [](#requirements) RequirementVersionPHP>= 7.4.0ext-json\*adbario/php-dot-notation^2.2Overview -------- [](#overview) Every SalesRender plugin exposes one or more forms (settings, waybill, batch) that the platform renders in the admin UI. This component provides the PHP-side form definition -- it does not render HTML. Instead, all classes implement `JsonSerializable` so they can be serialized to JSON and consumed by the frontend. ### Architecture [](#architecture) ``` Form |-- title, description, button |-- FieldGroup[] (keyed by group name) |-- title, description |-- FieldDefinition[] (keyed by field name) | |-- BooleanDefinition | |-- IntegerDefinition | |-- FloatDefinition | |-- StringDefinition | |-- MultilineStringDefinition | |-- PasswordDefinition | |-- MarkdownDefinition | |-- FileDefinition | |-- IFrameDefinition | |-- ListOfEnumDefinition | |-- TablePreviewField | |-- MarkdownPreviewField |-- dependencies[] (field -> [depends-on fields]) FormData (extends Adbar\Dot) |-- dot-notation access to submitted values Autocomplete system |-- AutocompleteInterface |-- AutocompleteRegistry (singleton) Preview system |-- TablePreviewInterface / TablePreviewRegistry |-- MarkdownPreviewInterface / MarkdownPreviewRegistry ``` Key Classes ----------- [](#key-classes) ### Form [](#form) Top-level form container. Implements `JsonSerializable`. MethodSignatureDescription`__construct``__construct(string $title, ?string $description, array $fieldGroups, string $button, array $context = [])`Creates a form; `$fieldGroups` is an associative array of `FieldGroup` instances`getTitle``getTitle(): string`Form title displayed in the UI`getDescription``getDescription(): ?string`Optional description (supports markdown in some plugins)`getGroups``getGroups(): FieldGroup[]`Returns all field groups, keyed by group name`getButton``getButton(): string`Label for the submit button`getDefaultData``getDefaultData(): FormData`Collects default values from all field definitions`clearRedundant``clearRedundant(FormData $formData): FormData`Removes data keys that do not exist in the form definition`validateData``validateData(FormData $formData): bool`Validates all field values; returns `true` if all pass`getErrors``getErrors(FormData $formData): array`Returns a nested array of errors `[groupName][fieldName] => [errors]``getContext``getContext(): array`Returns the form context`setContext``setContext(array $context): void`Sets the form context### FieldGroup [](#fieldgroup) Groups related fields together. Implements `JsonSerializable`. MethodSignatureDescription`__construct``__construct(string $title, ?string $description, array $fields, array $dependencies = [], array $context = [])`Creates a group; `$fields` is `FieldDefinition[]`, `$dependencies` maps field names to arrays of field names they depend on`getTitle``getTitle(): string`Group title`getDescription``getDescription(): ?string`Optional group description`getFields``getFields(): FieldDefinition[]`Returns all fields, keyed by field name`getDependencies``getDependencies(): array`Returns the dependency map`getContext``getContext(): array`Returns the group context`setContext``setContext(array $context): void`Sets the group context### FieldDefinition (abstract) [](#fielddefinition-abstract) Base class for all field types. Implements `JsonSerializable`. MethodSignatureDescription`__construct``__construct(string $title, ?string $description, callable $validator, $default = null, $context = null)`Creates a field definition with a validator callback`getTitle``getTitle(): string`Field label`getDescription``getDescription(): ?string`Help text for the field`validate``validate($value, FormData $data): bool`Returns `true` if validation passes`getErrors``getErrors($value, FormData $data): array`Invokes the validator; returns an array of error messages (empty = valid)`getDefault``getDefault()`Returns the default value`getContext``getContext()`Returns field-level context`getDefinition``getDefinition(): string`*(abstract)* Returns the type identifier string### Field Type Definitions [](#field-type-definitions) ClassDefinition StringInherits FromDescription`BooleanDefinition``'boolean'``FieldDefinition`Checkbox / toggle`IntegerDefinition``'integer'``FieldDefinition`Integer number input`FloatDefinition``'float'``FieldDefinition`Floating-point number input`StringDefinition``'string'``FieldDefinition`Single-line text input (serializes `multiline: false`)`MultilineStringDefinition``'string'``StringDefinition`Multi-line text area (serializes `multiline: true`)`PasswordDefinition``'password'``FieldDefinition`Password input (masked)`MarkdownDefinition``'markdown'``StringDefinition`Markdown editor`FileDefinition``'file'``FieldDefinition`File upload field`IFrameDefinition``'iframe'``FieldDefinition`Embeds an iframe; adds `$iframe` URL parameter`ListOfEnumDefinition``'listOfEnum'``FieldDefinition`Multi-select from a list of options; supports `Limit` and various value sources`TablePreviewField``'tablePreview'``FieldDefinition`Read-only table preview; references a named previewer`MarkdownPreviewField``'markdownPreview'``FieldDefinition`Read-only markdown preview; references a named previewer### IFrameDefinition [](#iframedefinition) Extends `FieldDefinition` with an embedded iframe URL. MethodSignatureDescription`__construct``__construct(string $title, ?string $description, callable $validator, string $iframe, $default = null, $context = null)`Adds an `$iframe` path parameter`getIframe``getIframe(): string`Returns the iframe URL### ListOfEnumDefinition [](#listofenumdefinition) Multi-select field with configurable value sources and selection limits. MethodSignatureDescription`__construct``__construct(string $title, ?string $description, callable $validator, ValuesListInterface $valuesList, ?Limit $limit, $default = null, $context = null)`Creates a list-of-enum field`getValues``getValues(): ValuesListInterface`Returns the values source`getLimit``getLimit(): ?Limit`Returns min/max selection limits, or `null`### TablePreviewField / MarkdownPreviewField [](#tablepreviewfield--markdownpreviewfield) Read-only preview fields. The validator is always `fn() => []` (no validation needed). MethodSignatureDescription`__construct``__construct(string $title, ?string $description, string $previewer, $default = null, $context = null)``$previewer` is a registered name resolved via the corresponding registry`getPreviewer``getPreviewer(): string`Returns the previewer name### FormData [](#formdata) Extends `Adbar\Dot` (dot-notation array wrapper). Provides dot-path access to submitted form values, e.g. `$formData->get('auth.token')`. ### ListOfEnum Value Sources [](#listofenum-value-sources) ClassDescription`StaticValues`Hardcoded array of options. Each item must have `'title'` and `'group'` keys.`DynamicValues`References a named autocomplete endpoint (resolved by `AutocompleteRegistry`).`CallableValues`Lazily evaluates a callable that returns a `StaticValues`-compatible array. Caches the result.### Limit [](#limit) Controls min/max selection count for `ListOfEnumDefinition`. MethodSignatureDescription`__construct``__construct(?int $min, ?int $max)`Both are nullable; `null` means no constraint`getMin``getMin(): ?int`Minimum number of required selections`getMax``getMax(): ?int`Maximum number of allowed selections### AutocompleteInterface [](#autocompleteinterface) Implement this to provide server-side autocomplete for `DynamicValues` fields. MethodSignatureDescription`query``query(string $query, array $dependencies, array $context): array`Search by text query; return options array`values``values(array $values, array $dependencies, array $context): array`Resolve specific values to display labels`validate``validate(array $values, array $dependencies, array $context): bool`Validate that selected values are legitimate### AutocompleteRegistry [](#autocompleteregistry) Singleton registry that maps autocomplete names to implementations. MethodSignatureDescription`config``static config(callable $resolver): void`Register a resolver `function(string $name): ?AutocompleteInterface``getAutocomplete``static getAutocomplete(string $name): ?AutocompleteInterface`Resolve an autocomplete by name### TablePreviewInterface / MarkdownPreviewInterface [](#tablepreviewinterface--markdownpreviewinterface) MethodSignatureDescription`render``render(array $dependencies, array $context): array`Render preview data given current field dependencies and context### TablePreviewRegistry / MarkdownPreviewRegistry [](#tablepreviewregistry--markdownpreviewregistry) Singleton registries, identical pattern to `AutocompleteRegistry`. MethodSignatureDescription`config``static config(callable $resolver): void`Register a resolver `function(string $name): ?Interface``getTablePreview` / `getMarkdownPreview``static get*(string $name): ?Interface`Resolve a preview implementation by name### ValidatorInterface [](#validatorinterface) Optional interface for validator callables (validators can be plain closures or objects implementing this interface). MethodSignatureDescription`__invoke``__invoke($value, FieldDefinition $definition, FormData $data): array`Returns an array of error strings; empty array means valid### Exceptions [](#exceptions) ClassDescription`AutocompleteRegistryException`Thrown when `AutocompleteRegistry::getAutocomplete()` is called before `config()``TablePreviewRegistryException`Thrown when `TablePreviewRegistry::getTablePreview()` is called before `config()``MarkdownPreviewRegistryException`Thrown when `MarkdownPreviewRegistry::getMarkdownPreview()` is called before `config()``InvalidDependencyException`Thrown when a `FieldGroup` dependency references a non-existent field nameUsage Examples -------------- [](#usage-examples) All examples below are taken from real production plugins. ### Basic settings form with string and password fields [](#basic-settings-form-with-string-and-password-fields) From `plugin-pbx-sipsim/src/Forms/SettingsForm.php`: ``` use SalesRender\Plugin\Components\Form\FieldDefinitions\FieldDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\PasswordDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\StringDefinition; use SalesRender\Plugin\Components\Form\FieldGroup; use SalesRender\Plugin\Components\Form\Form; use SalesRender\Plugin\Components\Form\FormData; $nonEmpty = function ($value, FieldDefinition $definition, FormData $data) { $errors = []; if (empty($value)) { $errors[] = 'Field cannot be empty'; } return $errors; }; $form = new Form( 'Settings', 'Configure your API connection', [ 'main' => new FieldGroup( 'Main', null, [ 'url' => new StringDefinition('API URL', 'Provided by support', $nonEmpty), 'token' => new PasswordDefinition('Token', 'Generated in your dashboard', $nonEmpty), ] ), ], 'Save' ); ``` ### Form with multiple field types, ListOfEnum, and dependencies [](#form-with-multiple-field-types-listofenum-and-dependencies) From `plugin-logistic-bluedart/src/Form/SettingsForm.php`: ``` use SalesRender\Plugin\Components\Form\FieldDefinitions\BooleanDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\FloatDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\IntegerDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnum\Limit; use SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnum\Values\StaticValues; use SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnumDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\PasswordDefinition; use SalesRender\Plugin\Components\Form\FieldDefinitions\StringDefinition; use SalesRender\Plugin\Components\Form\FieldGroup; use SalesRender\Plugin\Components\Form\Form; $form = new Form( 'Settings', 'Blue Dart Configuration', [ 'auth' => new FieldGroup( 'Authorization', null, [ 'client_id' => new StringDefinition('Client ID', null, $nonEmpty), 'client_secret' => new PasswordDefinition('Client Secret', null, $nonEmpty), ] ), 'shipment' => new FieldGroup( 'Shipment Defaults', null, [ 'productType' => new ListOfEnumDefinition( 'Product Type', null, $nonEmptyEnum, new StaticValues([ '0' => ['title' => 'Documents', 'group' => 'Type'], '1' => ['title' => 'Non-Documents / Cargo', 'group' => 'Type'], ]), new Limit(1, 1), ['1'] ), 'codFixed' => new BooleanDefinition( 'Use fixed COD amount', 'If disabled, uses order total', $noValidation, false ), 'codFixedValue' => new FloatDefinition( 'Fixed COD value', 'Used for all shipments when fixed amount is enabled', $dependedCod, 0.0 ), ], [ // 'codFixedValue' is only visible when 'codFixed' changes 'codFixedValue' => ['codFixed'], ] ), 'package' => new FieldGroup( 'Default Package', null, [ 'length' => new IntegerDefinition('Length', null, $noValidation, 10), 'width' => new IntegerDefinition('Width', null, $noValidation, 10), 'height' => new IntegerDefinition('Height', null, $noValidation, 10), 'weight' => new FloatDefinition('Weight, kg', null, $noValidation, 0.5), ] ), ], 'Save' ); ``` ### DynamicValues with autocomplete [](#dynamicvalues-with-autocomplete) From `plugin-logistic-cdek/src/Waybill/WaybillForm.php`: ``` use SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnum\Limit; use SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnum\Values\DynamicValues; use SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnumDefinition; $cityField = new ListOfEnumDefinition( 'Sender city', null, $nonEmpty, new DynamicValues('citiesFrom'), // resolved via AutocompleteRegistry new Limit(1, 1), $defaultSenderCity ); ``` ### Registering autocomplete in bootstrap [](#registering-autocomplete-in-bootstrap) From `plugin-logistic-bluedart/bootstrap.php`: ``` use SalesRender\Plugin\Components\Form\Autocomplete\AutocompleteRegistry; AutocompleteRegistry::config(function (string $name) { switch ($name) { case 'rates': return new RatesAutocomplete(); default: return null; } }); ``` ### Implementing AutocompleteInterface [](#implementing-autocompleteinterface) From `plugin-logistic-shipox/src/Autocomplete/CityAutocomplete.php`: ``` use SalesRender\Plugin\Components\Form\Autocomplete\AutocompleteInterface; final class CityAutocomplete implements AutocompleteInterface { public const NAME = 'city'; public function query(string $query, array $dependencies, array $context): array { if (empty(trim($query))) { return []; } // call external API, return ['value_key' => ['title' => '...', 'group' => '...']] return $this->getCitiesByCondition($query); } public function values(array $values, array $dependencies, array $context): array { return $this->getCitiesByCondition(json_decode($values[0], true)[1]); } public function validate(array $values, array $dependencies, array $context): bool { $cities = $this->getCitiesByCondition(json_decode($values[0], true)[1]); return array_key_exists(array_shift($values), $cities); } } ``` ### MarkdownPreviewField with dependencies [](#markdownpreviewfield-with-dependencies) From `plugin-logistic-cdek/src/Waybill/WaybillForm.php`: ``` use SalesRender\Plugin\Components\Form\FieldDefinitions\MarkdownPreviewField; $group = new FieldGroup( 'Delivery', null, [ 'tariff' => new ListOfEnumDefinition(/* ... */), 'citySender' => new ListOfEnumDefinition(/* ... */), 'weight' => new FloatDefinition(/* ... */), 'deliveryData' => new MarkdownPreviewField( 'Delivery data', null, 'delivery_data_preview', // resolved via MarkdownPreviewRegistry null, $context ), ], [ 'deliveryData' => ['tariff', 'citySender', 'weight'], ] ); ``` ### Registering MarkdownPreviewRegistry in bootstrap [](#registering-markdownpreviewregistry-in-bootstrap) From `plugin-logistic-bluedart/bootstrap.php`: ``` use SalesRender\Plugin\Components\Form\MarkdownPreview\MarkdownPreviewRegistry; MarkdownPreviewRegistry::config(function () { return new DeliveryInfoMarkdownPreview(); }); ``` ### TablePreviewField [](#tablepreviewfield) From `plugin-macros-example/src/Forms/SettingsForm.php`: ``` use SalesRender\Plugin\Components\Form\FieldDefinitions\TablePreviewField; $field = new TablePreviewField( 'Table preview', 'Preview description', 'example', // previewer name, resolved via TablePreviewRegistry ['default' => 'text'], $context ); ``` ### IFrameDefinition [](#iframedefinition-1) From `plugin-macros-example/src/Forms/SettingsForm.php`: ``` use SalesRender\Plugin\Components\Form\FieldDefinitions\IFrameDefinition; $field = new IFrameDefinition( 'IFrame field', 'Description', function ($value) { if ($value < 0 || $value > 10) { return ['Value must be between 0 and 10']; } return []; }, 'iframe/example.html', '5' // default value ); ``` ### Validating and reading form data [](#validating-and-reading-form-data) ``` $form = new Form(/* ... */); $formData = new FormData($submittedArray); if ($form->validateData($formData)) { $token = $formData->get('auth.token'); // dot-notation access $length = $formData->get('package.length'); } else { $errors = $form->getErrors($formData); // $errors['auth']['token'] => ['Field cannot be empty'] } ``` ### Getting default data [](#getting-default-data) ``` $form = new Form(/* ... */); $defaults = $form->getDefaultData(); // $defaults->get('package.length') => 10 ``` Configuration ------------- [](#configuration) ### Autocomplete [](#autocomplete) If any form uses `DynamicValues`, the `AutocompleteRegistry` must be configured in `bootstrap.php`: ``` AutocompleteRegistry::config(function (string $name): ?AutocompleteInterface { // return the appropriate implementation or null }); ``` ### Table Preview [](#table-preview) If any form uses `TablePreviewField`, configure `TablePreviewRegistry`: ``` TablePreviewRegistry::config(function (string $name): ?TablePreviewInterface { // return the appropriate implementation or null }); ``` ### Markdown Preview [](#markdown-preview) If any form uses `MarkdownPreviewField`, configure `MarkdownPreviewRegistry`: ``` MarkdownPreviewRegistry::config(function (string $name): ?MarkdownPreviewInterface { // return the appropriate implementation or null }); ``` API Reference ------------- [](#api-reference) ### Namespace [](#namespace) ``` SalesRender\Plugin\Components\Form SalesRender\Plugin\Components\Form\FieldDefinitions SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnum SalesRender\Plugin\Components\Form\FieldDefinitions\ListOfEnum\Values SalesRender\Plugin\Components\Form\Autocomplete SalesRender\Plugin\Components\Form\Components SalesRender\Plugin\Components\Form\TableView SalesRender\Plugin\Components\Form\MarkdownPreview SalesRender\Plugin\Components\Form\Exceptions ``` ### Field Definition Types [](#field-definition-types) Definition StringClassJSON `multiline``'boolean'``BooleanDefinition`--`'integer'``IntegerDefinition`--`'float'``FloatDefinition`--`'string'``StringDefinition``false``'string'``MultilineStringDefinition``true``'password'``PasswordDefinition`--`'markdown'``MarkdownDefinition`--`'file'``FileDefinition`--`'iframe'``IFrameDefinition`--`'listOfEnum'``ListOfEnumDefinition`--`'tablePreview'``TablePreviewField`--`'markdownPreview'``MarkdownPreviewField`--### JSON Serialization [](#json-serialization) Every class implements `JsonSerializable`. A form serializes to: ``` { "title": "Settings", "description": "Configure plugin", "groups": { "auth": { "title": "Authorization", "description": null, "fields": { "token": { "title": "API Token", "description": "Your API token", "definition": "password", "default": null, "context": null } }, "dependencies": {} } }, "button": "Save" } ``` Dependencies ------------ [](#dependencies) PackageVersionPurpose`adbario/php-dot-notation`^2.2Dot-notation array access for `FormData` (extends `Adbar\Dot`)See Also -------- [](#see-also) - [salesrender/plugin-component-settings](https://github.com/SalesRender/plugin-component-settings) -- persists `FormData` submitted via forms; uses `Settings::setForm()` to bind a form - [salesrender/plugin-component-purpose](https://github.com/SalesRender/plugin-component-purpose) -- plugin purpose classification (class + entity) - [salesrender/plugin-component-info](https://github.com/SalesRender/plugin-component-info) -- plugin metadata; combined with form and purpose during bootstrap ### Health Score 42 — FairBetter than 89% of packages Maintenance66 Regular maintenance activity Popularity17 Limited adoption so far Community15 Small or concentrated contributor base Maturity61 Established project with proven stability Bus Factor1 Top contributor holds 50% 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 ~42 days Total 45 Last Release 644d ago PHP version history (3 changes)0.0.1PHP >=7.1.0 0.7.3PHP >=7.2.0 0.10.0PHP >=7.4.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/6140af7bf37913fbad3d596efa1376ede23a55ac226a15b61857f4e58fc26c22?d=identicon)[SalesRender](/maintainers/SalesRender) --- Top Contributors [![IvanKalashnikov](https://avatars.githubusercontent.com/u/6877306?v=4)](https://github.com/IvanKalashnikov "IvanKalashnikov (4 commits)")[![XAKEPEHOK](https://avatars.githubusercontent.com/u/3051649?v=4)](https://github.com/XAKEPEHOK "XAKEPEHOK (4 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/salesrender-plugin-component-form/health.svg) ``` [![Health](https://phpackages.com/badges/salesrender-plugin-component-form/health.svg)](https://phpackages.com/packages/salesrender-plugin-component-form) ``` ### Alternatives [alibabacloud/client Alibaba Cloud Client for PHP - Use Alibaba Cloud in your PHP project 2223.5M366](/packages/alibabacloud-client)[cognesy/instructor-php The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control 310107.9k1](/packages/cognesy-instructor-php)[crwlr/crawler Web crawling and scraping library. 37214.8k2](/packages/crwlr-crawler)[brandembassy/slim-nette-extension 19190.2k](/packages/brandembassy-slim-nette-extension)[janiskelemen/laravel-setting Laravel Settings Manager 5115.6k](/packages/janiskelemen-laravel-setting)[adbario/slim-secure-session-middleware Secure session middleware for Slim 3 framework 2932.3k2](/packages/adbario-slim-secure-session-middleware) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)