107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
|
# `form`(FormInterface $form, ? FormContext $formContext = null) : FormHandler
|
||
|
|
|
||
|
|
The `form()` method will process a form in three steps :
|
||
|
|
|
||
|
|
1. `initialize(FormContextInterface $context)` is first called on form processing.
|
||
|
|
2. `validate(FormContextInterface $context) : bool` will execute on POST. If you define a name to the form, it will match the one found in the POST (`picea-ui-form[$context->name]`) ; if the form is not the target, it will be skipped. Also, if an error si found within the message list, the method will return `false`.
|
||
|
|
3. `execute(FormContextInterface $context)` is the last method to run, which is usually where you save your entity and finilize your messages. The return value is accessible from the `formHandler` which `form()` returns.
|
||
|
|
|
||
|
|
**[PHP]** So, using this code:
|
||
|
|
|
||
|
|
in */app/controller/user.php*
|
||
|
|
```php
|
||
|
|
form(new \MyApp\Form\User\Create());
|
||
|
|
```
|
||
|
|
|
||
|
|
*/app/form/create.php*
|
||
|
|
```php
|
||
|
|
<?php
|
||
|
|
|
||
|
|
namespace MyProject\Form;
|
||
|
|
|
||
|
|
use MyProject\{ Lib, Entity };
|
||
|
|
use Picea\Ui\Method\{ FormContextInterface, Message\ErrorMessage };
|
||
|
|
|
||
|
|
use Psr\Http\Message\ServerRequestInterface;
|
||
|
|
|
||
|
|
use function MyProject\View\{ lang };
|
||
|
|
|
||
|
|
class Create implements \Picea\Ui\Method\FormInterface {
|
||
|
|
|
||
|
|
public function initialize(FormContextInterface $context) : void
|
||
|
|
{
|
||
|
|
$this->user = new Entity\User();
|
||
|
|
|
||
|
|
# $context->{varname} will be populated by $_POST data.
|
||
|
|
$this->user = (string) $context->fullname;
|
||
|
|
}
|
||
|
|
|
||
|
|
public function validate(FormContextInterface $context) : bool
|
||
|
|
{
|
||
|
|
if ( strlen($this->user) < 3 ) {
|
||
|
|
# This won't allow `execute` to run because of the error message.
|
||
|
|
$context->pushMessage(Lib\Message::generateError(
|
||
|
|
lang("form.error.provide_fullName")
|
||
|
|
));
|
||
|
|
}
|
||
|
|
|
||
|
|
return $context->valid();
|
||
|
|
}
|
||
|
|
|
||
|
|
public function execute(FormContextInterface $context) : void
|
||
|
|
{
|
||
|
|
# Saving a new user here
|
||
|
|
Entity\User::repository()->save($this->user);
|
||
|
|
|
||
|
|
$context->pushMessage(Lib\Message::generateSuccess(
|
||
|
|
lang("form.save")
|
||
|
|
));
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
which implements this interface :
|
||
|
|
|
||
|
|
```php
|
||
|
|
interface FormInterface
|
||
|
|
{
|
||
|
|
public function initialize(FormContextInterface $context) : void;
|
||
|
|
|
||
|
|
public function validate(FormContextInterface $context) : bool;
|
||
|
|
|
||
|
|
public function execute(FormContextInterface $context);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Would yield the same result such as:
|
||
|
|
```php
|
||
|
|
true
|
||
|
|
true
|
||
|
|
```
|
||
|
|
|
||
|
|
Trying to access either variable before `execute` is called will return `null`.
|
||
|
|
|
||
|
|
## `FormContext` object
|
||
|
|
|
||
|
|
`__construct(ServerRequestInterface $request, ? string $formName = null)`
|
||
|
|
|
||
|
|
Creating a form context manually allows to define the formName, which is essential if you want to use the
|
||
|
|
Cross-Scripting Request Forgery (CSRF).
|
||
|
|
|
||
|
|
It is populated with either $_POST or request's body which is json_decode. A property called `files` is also populated from PSR's `$request->getUploadedFiles()`.
|
||
|
|
|
||
|
|
It's `valid() : bool` method called into a form `validate()` function is first checking every message which were pushed into, using `pushMessage(FormMessage $message)`, and returns false if an error message is found in the list.
|
||
|
|
|
||
|
|
### Retrieve a form execution status / value
|
||
|
|
|
||
|
|
There is two ways to get the execution status (from the `execute` return value):
|
||
|
|
|
||
|
|
```php
|
||
|
|
$formContext = new \Picea\Ui\Method\FormContext($request, 'form.user_create');
|
||
|
|
$form = form(new \MyProject\Form\User\Create(), $formContext);
|
||
|
|
|
||
|
|
if ($formContext->formExecuted) {
|
||
|
|
echo $form->executionStatus;
|
||
|
|
echo $formContext->formExecutionStatus;
|
||
|
|
}
|
||
|
|
```
|