PHPackages sunnyflail/forms - 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. sunnyflail/forms ActiveLibrary[Utility & Helpers](/categories/utility) sunnyflail/forms ================ A simple Form abstraction API 1.6.4(4y ago)095MITPHP Since Jul 12Pushed 4y ago1 watchersCompare [ Source](https://github.com/SunnyFlail/Forms)[ Packagist](https://packagist.org/packages/sunnyflail/forms)[ RSS](/packages/sunnyflail-forms/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (5)Versions (55)Used By (0) Forms ===== [](#forms) A simple Form Abstraction layer 1 Creating forms ================ [](#1-creating-forms) First create a class extending [`SunnyFlail\Forms\Form\FormElement`](src/Form/FormElement.php) class. It must implement method [`IFormElement::build`](src/Interfaces/IFormElement.php). ``` use SunnyFlail\Forms\Form\FormElement; use SunnyFlail\Forms\Interfaces\IFormBuilder; class ConcreteForm extends FormElement { public function build(IFormBuilder $builder) { (...) } } ``` 1.1 Adding Fields ----------------- [](#11-adding-fields) Inside the `IFormElement::build` method invoke [`IFormBuilder::add`](src/Interfaces/IFormBuilder.php), providing the field you want to add as an argument. You can chain this method. ``` $builder->add(new InputField('text')); ``` 1.2 Configuring form -------------------- [](#12-configuring-form) Inside the `` method you can change properties *(Mandatory)* `string $formName` - Name of the form - prefix which will be provided to form's field names `string $formMethod` - HTTP method which this form will use (defaults to **GET**) `string $buttonText` - Text which will be shown inside the submit button `array $attributes` - Atttributes to be provided to the form Element `array buttonAttributes` - Attributes provided to submit button Element of the form `IElement\[\] $topElements`- Array of objects implementing `SunnyFlail\\HtmlAbstraction\\Interfaces\\IElement` interface - Elements to be printed before all fields `IElement\[\] $middleElements` - Array of objects implementing `SunnyFlail\\HtmlAbstraction\\Interfaces\\IElement` interface - Elements to be printed before after fields, before button `IElement\[\] $bottomElements` - Array of objects implementing `SunnyFlail\\HtmlAbstraction\\Interfaces\\IElement` interface - Elements to be printed after submit button `string|null $classFQCN` - FQCN of (Plain Old Php Object) class to which this form will resolve to, resolves to **array** if this is null `bool $useHtmlValidation` - Should this form use Html Validation (defaults to **true**) `bool $withFiles` If set to true sets the enctype (encoding type) to multipart/form-data 2 Using forms ============= [](#2-using-forms) 2.1 Creating builder ==================== [](#21-creating-builder) First you need to create a global copy of form builder ``` $objectCreator = new SunnyFlail\ObjectCreator\ObjectCreator(); $valueMapper = new SunnyFlail\Forms\Mappers\ValueMapper($objectCreator); $valueProviderFactory = new SunnyFlail\Forms\Providers\ProviderFactory(); $builder = new SunnyFlail\Forms\Form\FormBuilder($valueMapper, $valueProviderFactory); ``` 2.2 Building form ================= [](#22-building-form) Then invoke [`IFormBuilder::buildForm`](src/Interfaces/IFormBuilder.php)method providing form FQCN as first argument, and optionally object/array to scrape values from as second. This returns a copy of Builder so prepare another variable for it ``` $concreteFormBuilder = $builder->buildForm(ConcreteForm::class); ``` 2.3 Processing user input ========================= [](#23-processing-user-input) To process user provided data invoke [`IFormBuilder::processForm`](src/Interfaces/IFormBuilder.php)using a object implementing `Psr\Http\Message\ServerRequestInterface` interface as an argument This will return a bool indicating whether form got valid values ``` if ($concreteFormBuilder->processForm($request)) { (...) } ``` 2.4 Getting values ================== [](#24-getting-values) To get values scraped from form elements use [`IFormBuilder::getProcessedData`](src/Interfaces/IFormBuilder.php) ``` $values = $concreteFormBuilder->getProcessedData(); ``` 2.5 Adding errors ================= [](#25-adding-errors) To add en error to form use [`IFormBuilder::addError`](src/Interfaces/IFormBuilder.php) ``` $concreteFormBuilder->addError('An error occurred!'); ``` 2.6 Rendering form ================== [](#26-rendering-form) You can either just stringify (eg. `echo $concreteFormBuilder;`) the form OR manually render all of the fields. To render the form manually, first you need to get a copy of Form by calling [`IFormBuilder::accessForm`](src/Interfaces/IFormBuilder.php) To get HTML form tag attributes call [`IFormElement::getHTMLAttributes`](src/Interfaces/IFormElement.php) To get an associative array of fields call [`IFormElement::getFields`](src/Interfaces/IFormElement.php) To get Fields Input element call [`IField::getInputElement`](src/Interfaces/IField.php) To get Fields Label element call [`IField::getLabelElement`](src/Interfaces/IField.php) Those methods may return an IElement OR and array of them If an error occured you can get the error element with [`IField::getErrorElement`](src/Interfaces/IField.php) 3 Available fields ================== [](#3-available-fields) 3.1 InputField -------------- [](#31-inputfield) This is representation of [``](src/Fields/InputField.php) ``` $input = new SunnyFlail\Forms\Fields\InputField(); ``` Input field constructor takes parameters: `string $name` - Name of the field `string $type` - Field type `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `IConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `IElement[] $topElements`- Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before label `IElement[] $middleElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before input `IElement[] $bottomElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before error `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `?string $labelText` - Text to be shown inside label, if unset it shows the field name `array $labelAttributes` - Array of html attributes to be provided to label Element 3.2 EmailField -------------- [](#32-emailfield) This is representation of [``](src/Fields/EmailField.php) ``` $input = new SunnyFlail\Forms\Fields\EmailField(); ``` Email field constructor takes parameters `string $name` - Name of the field `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `IElement[] $topElements`- Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before label `IElement[] $middleElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before input `IElement[] $bottomElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before error `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `?string $labelText` - Text to be shown inside label, if unset it shows the field name `array $labelAttributes` - Array of html attributes to be provided to label Element 3.3 PasswordField ----------------- [](#33-passwordfield) This is representation of [``](src/Fields/PasswordField.php) ``` $input = new SunnyFlail\Forms\Fields\PasswordField(); ``` This field introduces `Peeper` - a button which, when coupled with appriopriate JS, shows the password provided to the field Password field constructor takes parameters: `string $name` - Name of the field `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `IConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `IElement[] $topElements`- Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before label `IElement[] $middleElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before input `IElement[] $bottomElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before error `bool $withPeeper` - Whether this field should be rendered with an peeper `array $inputAttributes` - Array of html attributes to be provided to input Element `array $peeperAttributes` - Array of html attributes to be provided to peeper Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `?string $labelText` - Text to be shown inside label, if unset it shows the field name `array $labelAttributes` - Array of html attributes to be provided to label Element 3.4 TextAreaField ----------------- [](#34-textareafield) This is representation of [``](src/Fields/TextAreField.php) ``` $input = new SunnyFlail\Forms\Fields\TextAreaField(); ``` TextArea field constructor takes parameters: `string $name` - Name of the field `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `IConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `IElement[] $topElements`- Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before label `IElement[] $middleElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before input `IElement[] $bottomElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before error `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `?string $labelText` - Text to be shown inside label, if unset it shows the field name `array $labelAttributes` - Array of html attributes to be provided to label Element 3.5 SelectField --------------- [](#35-selectfield) This is representation of [`(...)`](src/Fields/SelectField.php) ``` $input = new SunnyFlail\Forms\Fields\SelectField(); ``` Select field constructor takes parameters: `string $name` - Name of the field `array $options` - Options to render - `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `bool $multiple` - Should this field allow multiple values `bool $useIntristicValues` - Should this only check for values provided in $options parameter or should accept any value matching provided constraints `IConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `IElement[] $topElements`- Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before label `IElement[] $middleElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before input `IElement[] $bottomElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before error `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `?string $labelText` - Text to be shown inside label, if unset it shows the field name `array $optionAttributes` - Array of html attributes to be provided to option Element `array $labelAttributes` - Array of html attributes to be provided to label Element 3.6 CheckBoxGroupField ---------------------- [](#36-checkboxgroupfield) This is representation of a group of [``](src/Fields/CheckBoxGroupField.php) ``` $input = new SunnyFlail\Forms\Fields\CheckBoxGroupField(); ``` Checkbox field constructor takes parameters: `string $name` - Name of the field `array $options` - Options to render - `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `bool $multiple` - Should this field allow multiple values `bool $useIntristicValues` - Should this only check for values provided in $options parameter or should accept any value matching provided constraints `IConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `array $labelAttributes` - Array of html attributes to be provided to label Element 3.7 RadioGroupField ------------------- [](#37-radiogroupfield) This is representation of a group of [``](src/Fields/RadioGroupField.php) ``` $input = new SunnyFlail\Forms\Fields\RadioGroupField(); ``` Radio field constructor takes parameters: `string $name` - Name of the field `array $options` - Options to render - `bool $required`- Whether this field must be filled `bool $rememberValue` - Whether this field should retain provided value of error `bool $useIntristicValues` - Should this only check for values provided in $options parameter or should accept any value matching provided constraints `IConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `array $labelAttributes` - Array of html attributes to be provided to label Element 3.8 RepeatedInputField ---------------------- [](#38-repeatedinputfield) [A field containing two fields whose values must be the same](src/Fields/RepeatedInputField.php) ``` $input = new SunnyFlail\Forms\Fields\RepeatedInputField(); ``` Repeated field constructor takes parameters: `IInputField $field` - First field `IInputField $repeatedField` - Repeated field `string $missmatchError` - Message to be displayed on error 3.9 ClassMappedField -------------------- [](#39-classmappedfield) [A group of fields whose values will be mapped to an Plain Old Php Object](src/Fields/ClassMappedField.php) ``` $input = new SunnyFlail\Forms\Fields\ClassMappedField(); ``` Class mapping field constructor takes parameters: `string $fieldName` - Name of the field `string $classFQCN` - Class name `IField ...$fields` - Fields with names defaulting to Class property names 3.10 FileUploadField -------------------- [](#310-fileuploadfield) This is representation of [``](src/Fields/FileUploadField.php) File upload field constructor takes parameters: `string $name` - Name of the field `bool $required`- Whether this field must be filled `bool $multiple` - Should this field allow multiple values `IFileConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IFileConstraint` interface `IElement[] $topElements`- Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before label `IElement[] $middleElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before input `IElement[] $bottomElements` - Array of objects implementing `SunnyFlail\HtmlAbstraction\Interfaces\IElement` interface - Elements to be printed before error `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `?string $labelText` - Text to be shown inside label, if unset it shows the field name `array $labelAttributes` - Array of html attributes to be provided to label Element `bool $terminateOnError` - Whether http upload error of one of the files should make this field invalid 3.11 FileUploadGroupField \[from version ^1.3\] ----------------------------------------------- [](#311-fileuploadgroupfield-from-version-13) [A group of file upload fields](src/Fields/FileUploadGroupField.php) File upload field constructor takes parameters: `string $name` - Name of the field `int $inputCount` - How many inputs should this render - must be at least 1, if set to 1 this fields multiple property is set to false `int $required`- Minimal number of required files `IFileConstraint[] $constraints` - Array of objects implementing `SunnyFlail\Constraints\Interfaces\IFileConstraint` interface `array $errorMessages` - Array of strings, keys must be numeric strings, '-1' is for no value error, positive keys are for failed constraint errors `string[] $labelTexts` - Text to be shown inside label, If set must be an incremental array with same amout of keys as set in $inputCount, otherwise shows numbers `array $inputAttributes` - Array of html attributes to be provided to input Element `array $containerAttributes` - Array of html attributes to be provided to wrapper Element `array $errorAttributes` - Array of html attributes to be provided to error Element `array $labelAttributes` - Array of html attributes to be provided to label Element `bool $terminateOnError` - Whether http upload error of one of the files should make this field invalid 4 TODO ====== [](#4-todo) I need to add an `IFormBuilder::getRawValues` which would return an associative array of raw values provided to fields ### Health Score 28 — LowBetter than 54% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity9 Limited adoption so far Community7 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 100% 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 ~0 days Total 54 Last Release 1748d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/50b47ac5307f9f924ae62916c792bbfcabe962da1a0eaf68230b2199d4a6283f?d=identicon)[SunnyFlail](/maintainers/SunnyFlail) --- Top Contributors [![SunnyFlail](https://avatars.githubusercontent.com/u/82274752?v=4)](https://github.com/SunnyFlail "SunnyFlail (61 commits)") ### Code Quality Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/sunnyflail-forms/health.svg) ``` [![Health](https://phpackages.com/badges/sunnyflail-forms/health.svg)](https://phpackages.com/packages/sunnyflail-forms) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)