Modelless Forms

• class Cake\Form\Form

Most of the time you will have forms backed by ORM entitiesand ORM tables or other persistent stores,but there are times when you’ll need to validate user input and then perform anaction if the data is valid. The most common example of this is a contact form.

Creating a Form

Generally when using the Form class you’ll want to use a subclass to define yourform. This makes testing easier, and lets you re-use your form. Forms are putinto src/Form and usually have Form as a class suffix. For example,a simple contact form would look like:

// in src/Form/ContactForm.php
namespace App\Form;
 
use Cake\Form\Form;
use Cake\Form\Schema;
use Cake\Validation\Validator;
 
class ContactForm extends Form
{
    protected function _buildSchema(Schema $schema)
    {
        return $schema->addField('name', 'string')
            ->addField('email', ['type' => 'string'])
            ->addField('body', ['type' => 'text']);
    }
 
    protected function validationDefault(Validator $validator)
    {
        $validator->add('name', 'length', [
                'rule' => ['minLength', 10],
                'message' => 'A name is required'
            ])->add('email', 'format', [
                'rule' => 'email',
                'message' => 'A valid email address is required',
            ]);
 
        return $validator;
    }
 
    protected function _execute(array $data)
    {
        // Send an email.
        return true;
    }
}

In the above example we see the 3 hook methods that forms provide:

• _buildSchema is used to define the schema data that is used by FormHelperto create an HTML form. You can define field type, length, and precision.
• validationDefault Gets a Cake\Validation\Validator instancethat you can attach validators to.
• _execute lets you define the behavior you want to happen whenexecute() is called and the data is valid.

You can always define additional public methods as you need as well.

Processing Request Data

Once you’ve defined your form, you can use it in your controller to processand validate request data:

// In a controller
namespace App\Controller;
 
use App\Controller\AppController;
use App\Form\ContactForm;
 
class ContactController extends AppController
{
    public function index()
    {
        $contact = new ContactForm();
        if ($this->request->is('post')) {
            if ($contact->execute($this->request->getData())) {
                $this->Flash->success('We will get back to you soon.');
            } else {
                $this->Flash->error('There was a problem submitting your form.');
            }
        }
        $this->set('contact', $contact);
    }
}

In the above example, we use the execute() method to run our form’s_execute() method only when the data is valid, and set flash messagesaccordingly. We could have also used the validate() method to only validatethe request data:

$isValid = $form->validate($this->request->getData());

Setting Form Values

You can set default values for modelless forms using the setData() method.Values set with this method will overwrite existing data in the form object:

// In a controller
namespace App\Controller;
 
use App\Controller\AppController;
use App\Form\ContactForm;
 
class ContactController extends AppController
{
    public function index()
    {
        $contact = new ContactForm();
        if ($this->request->is('post')) {
            if ($contact->execute($this->request->getData())) {
                $this->Flash->success('We will get back to you soon.');
            } else {
                $this->Flash->error('There was a problem submitting your form.');
            }
        }
 
        if ($this->request->is('get')) {
            $contact->setData([
                'name' => 'John Doe',
                'email' => 'john.doe@example.com'
            ]);
        }
 
        $this->set('contact', $contact);
    }
}

Values should only be defined if the request method is GET, otherwiseyou will overwrite your previous POST Data which might have validation errorsthat need corrections.

Getting Form Errors

Once a form has been validated you can retrieve the errors from it:

$errors = $form->getErrors();
/* $errors contains
[
    'email' => ['A valid email address is required']
]
*/

Invalidating Individual Form Fields from Controller

It is possible to invalidate individual fields from the controller without theuse of the Validator class. The most common use case for this is when thevalidation is done on a remote server. In such case, you must manuallyinvalidate the fields accordingly to the feedback from the remote server:

// in src/Form/ContactForm.php
public function setErrors($errors)
{
    $this->_errors = $errors;
}

According to how the validator class would have returned the errors, $errorsmust be in this format:

["fieldName" => ["validatorName" => "The error message to display"]]

Now you will be able to invalidate form fields by setting the fieldName, thenset the error messages:

// In a controller
$contact = new ContactForm();
$contact->setErrors(["email" => ["_required" => "Your email is required"]]);

Proceed to Creating HTML with FormHelper to see the results.

Creating HTML with FormHelper

Once you’ve created a Form class, you’ll likely want to create an HTML form forit. FormHelper understands Form objects just like ORM entities:

echo $this->Form->create($contact);
echo $this->Form->control('name');
echo $this->Form->control('email');
echo $this->Form->control('body');
echo $this->Form->button('Submit');
echo $this->Form->end();

The above would create an HTML form for the ContactForm we defined earlier.HTML forms created with FormHelper will use the defined schema and validator todetermine field types, maxlengths, and validation errors.