picea-ui/docs/20-method-form.md

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

form(new \MyApp\Form\User\Create());

/app/form/create.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 :

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:

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):

$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;
}