![Software License][ico-license]
![Coverage Status][ico-scrutinizer]
![Total Downloads][ico-downloads], (*1)
A reverse Form API that builds and processes forms automatically - from markup., (*2)
Install
Via Composer, (*3)
``` bash
$ composer require evista/perform, (*4)
## Usage
``` php
$formService = new Service($crawler);
// Get form markup from the request to $formMarkup
$form = $formService->transpileForm($formMarkup);
Perform is based on a simple concept: build your form in plain ol' html in any template or any frontend like React.js then send it to the server. The backend will take care of building a form object from your markup, populate it from the request, and run your validations., (*5)
This differentiates it from all the other PHP form APIs, because there's no need to build any form object on the server side before submission., (*6)
Here is an example of a server side form building process:, (*7)
use Evista\Perform\Service;
// (...)
// Initialize form transpilation service (dependency injection friendly interface)
$formService = new Service($crawler);
$router->addRoute('POST', '/loginform', function (Request $request, Response $response) use($formService) {
$formMarkup = $request->request->get('serform');
$form = $formService->transpileForm($formMarkup);
// Get fields:
$fields = $form->getFields();
// Get an input field named 'email'
$emailField = $form->getField('email');
// Get the field's submitted value
$emailField->getValue();
// Get attributes, eg. placeholder:
$placeholder = $emailField->getAttribute('placeholder');
// Get selected option:
$selectField = $form->getField('test-select');
$selected = $selectField->getValue();
// Get the default selected option (that is selected in markup)
$defaultSelected = $selectField->getDefaultSelectedOption();
// Get files and handle them (multiple/single file upload)
try {
$fileField = $form->getField('files');
} catch (FormFieldException $formFieldException) {
$response = new Response();
$response->setStatusCode(Response::HTTP_INTERNAL_SERVER_ERROR);
$response->setContent('Error: ' . $formFieldException->getMessage());
$response->send();
return $response;
}
$uploadedFiles = $fileField->getFiles();
foreach ($uploadedFiles as $uploadedFile) {
// Check real file type:
$realType = $uploadedFile->getRealType(); // eg. image/png
$userAddedName = $uploadedFile->getUserName;
// Move the file to its final destination
$uploadedFile->moveToDestination($destination = '/var/uploads/');
// Get safe file name
$safeBaseName = $uploadedFile->getSafeName(); // no extension
// Get the original extension from filename
$userExtension = $uploadedFile->getUserExtension();
}
// Check validity
if (!$form->isValid()) {
// All errors can be spotted in the fields
foreach ($form->getFields() as $field) {
if (!$field->isValid()) {
$validationErrors[] = $field->getErrors();
}
}
// Or a lot more conveniently:
// This returns an array of Evista\Perform\ValueObject\ValidationError objects
$allValidationErrors = $form->getValidationErrors();
}
// Then send some response
$response = new JsonResponse(['dump'=>(var_export($form, true))]);
return $response;
});
After initializing the form builder call transpileForm() to build a Form object from the markup. The there's some helpful class methods to do whatever you have to, for example getField($name) to get any field's value., (*8)
$formMarkup = $request->request->get('serform');
$form = $formService->transpileForm($formMarkup);
The markup arrives with the submitted datas in the 'serform' post parameter. For example, this markup:, (*9)
There's a javascript file in assets/bundle.js that sends the form's data via POST to the form's destination (action parameter) via a global object called Perform., (*16)
There is a usage example of the package in this repo., (*17)
Change log
Please see CHANGELOG for more information what has changed recently., (*18)
Testing
bash
$ composer test, (*19)
Contributing
Please see CONTRIBUTING and CONDUCT for details., (*20)
Security
If you discover any security related issues, please email balint.sera@gmail.com instead of using the issue tracker., (*21)
Credits
License
The MIT License (MIT). Please see License File for more information., (*22)
Wallogit.com
