Class Form
Form abstraction used to create forms not tied to ORM backed models, or to other permanent datastores. Ideal for implementing forms on top of API services, or contact forms.
Building a form
This class is most useful when subclassed. In a subclass you
should define the _buildSchema, _buildValidator and optionally,
the _execute methods. These allow you to declare your form's
fields, validation and primary action respectively.
You can also define the validation and schema by chaining method
calls off of $form->schema() and $form->validator().
Forms are conventionally placed in the App\Form namespace.
Constants
Property Summary
-
$_errors protected
arrayThe errors if any
-
$_eventClass protected
stringDefault class name for new event objects.
-
$_eventManager protected
Cake\Event\EventManagerInterfaceCake\Event\EventManagerInstance of the Cake\Event\EventManager this object is using to dispatch inner events.
-
$_schema protected
Cake\Form\SchemaThe schema used by this form.
-
$_schemaClass protected
stringSchema class.
-
$_validator protected
Cake\Validation\ValidatorThe validator used by this form.
-
$_validatorClass protected
stringValidator class.
-
$_validators protected
Cake\Validation\Validator[]A list of validation objects indexed by name
Method Summary
-
__construct() public
Constructor
-
__debugInfo() public
Get the printable version of a Form instance.
-
_buildSchema() protected
A hook method intended to be implemented by subclasses.
-
_buildValidator() protected deprecated
A hook method intended to be implemented by subclasses.
-
_execute() protected
Hook method to be implemented in subclasses.
-
buildValidator() public
Callback method for Form.buildValidator event.
-
createValidator() protected
Creates a validator using a custom method inside your class.
-
dispatchEvent() public
Wrapper for creating and dispatching events.
-
errors() public
Get the errors in the form
-
eventManager() public deprecated
Returns the Cake\Event\EventManager manager instance for this object.
-
execute() public
Execute the form if it is valid.
-
getEventManager() public
Returns the Cake\Event\EventManager manager instance for this object.
-
getValidator() public
Returns the validation rules tagged with $name. It is possible to have multiple different named validation sets, this is useful when you need to use varying rules when saving from different routines in your system.
-
hasValidator() public
Checks whether or not a validator has been set.
-
implementedEvents() public
Get the Form callbacks this form is interested in.
-
schema() public
Get/Set the schema for this form.
-
setErrors() public
Set the errors in the form.
-
setEventManager() public
Returns the Cake\Event\EventManager manager instance for this object.
-
setValidator() public
This method stores a custom validator under the given name.
-
validate() public
Used to check if $data passes this form's validation.
-
validationDefault() public
Returns the default validator object. Subclasses can override this function to add a default validation set to the validator object.
-
validationMethodExists() protected
Checks if validation method exists.
-
validator() public deprecated
Get/Set the validator for this form.
Method Detail
__construct() ¶ public
__construct(Cake\Event\EventManager|null $eventManager = null)Constructor
Parameters
-
Cake\Event\EventManager|null$eventManager optional The event manager. Defaults to a new instance.
__debugInfo() ¶ public
__debugInfo(): arrayGet the printable version of a Form instance.
Returns
array_buildSchema() ¶ protected
_buildSchema(Cake\Form\Schema $schema): Cake\Form\SchemaA hook method intended to be implemented by subclasses.
You can use this method to define the schema using the methods on Cake\Form\Schema, or loads a pre-defined schema from a concrete class.
Parameters
-
Cake\Form\Schema$schema The schema to customize.
Returns
Cake\Form\Schema_buildValidator() ¶ protected
_buildValidator(Cake\Validation\Validator $validator): Cake\Validation\ValidatorA hook method intended to be implemented by subclasses.
You can use this method to define the validator using the methods on Cake\Validation\Validator or loads a pre-defined validator from a concrete class.
Parameters
-
Cake\Validation\Validator$validator The validator to customize.
Returns
Cake\Validation\Validator_execute() ¶ protected
_execute(array $data): boolHook method to be implemented in subclasses.
Used by execute() to execute the form's action.
Parameters
-
array$data Form data.
Returns
boolbuildValidator() ¶ public
buildValidator(Cake\Event\Event $event, Cake\Validation\Validator $validator, string $name): voidCallback method for Form.buildValidator event.
Parameters
-
Cake\Event\Event$event The Form.buildValidator event instance.
-
Cake\Validation\Validator$validator The validator to customize.
-
string$name Validator name
Returns
voidcreateValidator() ¶ protected
createValidator(string $name): Cake\Validation\ValidatorCreates a validator using a custom method inside your class.
This method is used only to build a new validator and it does not store it in your object. If you want to build and reuse validators, use getValidator() method instead.
Parameters
-
string$name The name of the validation set to create.
Returns
Cake\Validation\ValidatorThrows
RuntimeExceptiondispatchEvent() ¶ public
dispatchEvent(string $name, array|null $data = null, object|null $subject = null): Cake\Event\EventWrapper for creating and dispatching events.
Returns a dispatched event.
Parameters
-
string$name Name of the event.
-
array|null$data optional Any value you wish to be transported with this event to it can be read by listeners.
-
object|null$subject optional The object that this event applies to ($this by default).
Returns
Cake\Event\Eventerrors() ¶ public
errors(): arrayGet the errors in the form
Will return the errors from the last call
to validate() or execute().
Returns
arrayeventManager() ¶ public
eventManager(Cake\Event\EventManager|null $eventManager = null): Cake\Event\EventManagerReturns the Cake\Event\EventManager manager instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
Parameters
-
Cake\Event\EventManager|null$eventManager optional the eventManager to set
Returns
Cake\Event\EventManagerexecute() ¶ public
execute(array $data): boolExecute the form if it is valid.
First validates the form, then calls the _execute() hook method.
This hook method can be implemented in subclasses to perform
the action of the form. This may be sending email, interacting
with a remote API, or anything else you may need.
Parameters
-
array$data Form data.
Returns
boolgetEventManager() ¶ public
getEventManager(): Cake\Event\EventManagerReturns the Cake\Event\EventManager manager instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
Returns
Cake\Event\EventManagergetValidator() ¶ public
getValidator(string|null $name = null): Cake\Validation\ValidatorReturns the validation rules tagged with $name. It is possible to have multiple different named validation sets, this is useful when you need to use varying rules when saving from different routines in your system.
If a validator has not been set earlier, this method will build a valiator using a method inside your class.
For example, if you wish to create a validation set called 'forSubscription', you will need to create a method in your Table subclass as follows:
public function validationForSubscription($validator)
{
return $validator
->add('email', 'valid-email', ['rule' => 'email'])
->add('password', 'valid', ['rule' => 'notBlank'])
->requirePresence('username');
}
$validator = $this->getValidator('forSubscription');You can implement the method in validationDefault in your Table subclass
should you wish to have a validation set that applies in cases where no other
set is specified.
If a $name argument has not been provided, the default validator will be returned.
You can configure your default validator name in a DEFAULT_VALIDATOR
class constant.
Parameters
-
string|null$name optional The name of the validation set to return.
Returns
Cake\Validation\ValidatorhasValidator() ¶ public
hasValidator(string $name): boolChecks whether or not a validator has been set.
Parameters
-
string$name The name of a validator.
Returns
boolimplementedEvents() ¶ public
implementedEvents(): arrayGet the Form callbacks this form is interested in.
The conventional method map is:
- Form.buildValidator => buildValidator
Returns
arrayschema() ¶ public
schema(Cake\Form\Schema|null $schema = null): Cake\Form\SchemaGet/Set the schema for this form.
This method will call _buildSchema() when the schema
is first built. This hook method lets you configure the
schema or load a pre-defined one.
Parameters
-
Cake\Form\Schema|null$schema optional The schema to set, or null.
Returns
Cake\Form\SchemasetErrors() ¶ public
setErrors(array $errors): $thisSet the errors in the form.
$errors = [
'field_name' => ['rule_name' => 'message']
];
$form->setErrors($errors);Parameters
-
array$errors Errors list.
Returns
$thissetEventManager() ¶ public
setEventManager(Cake\Event\EventManager $eventManager): $thisReturns the Cake\Event\EventManager manager instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
Parameters
-
Cake\Event\EventManager$eventManager the eventManager to set
Returns
$thissetValidator() ¶ public
setValidator(string $name, Cake\Validation\Validator $validator): $thisThis method stores a custom validator under the given name.
You can build the object by yourself and store it in your object:
$validator = new \Cake\Validation\Validator($table);
$validator
->add('email', 'valid-email', ['rule' => 'email'])
->add('password', 'valid', ['rule' => 'notBlank'])
->allowEmpty('bio');
$this->setValidator('forSubscription', $validator);Parameters
-
string$name The name of a validator to be set.
-
Cake\Validation\Validator$validator Validator object to be set.
Returns
$thisvalidate() ¶ public
validate(array $data): boolUsed to check if $data passes this form's validation.
Parameters
-
array$data The data to check.
Returns
boolvalidationDefault() ¶ public
validationDefault(Cake\Validation\Validator $validator): Cake\Validation\ValidatorReturns the default validator object. Subclasses can override this function to add a default validation set to the validator object.
Parameters
-
Cake\Validation\Validator$validator The validator that can be modified to add some rules to it.
Returns
Cake\Validation\ValidatorvalidationMethodExists() ¶ protected
validationMethodExists(string $name): boolChecks if validation method exists.
Parameters
-
string$name Validation method name.
Returns
boolvalidator() ¶ public
validator(Cake\Validation\Validator|null $validator = null): Cake\Validation\ValidatorGet/Set the validator for this form.
This method will call _buildValidator() when the validator
is first built. This hook method lets you configure the
validator or load a pre-defined one.
Parameters
-
Cake\Validation\Validator|null$validator optional The validator to set, or null.
Returns
Cake\Validation\Validator