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.
- Cake\Form\Form implements Cake\Event\EventListenerInterface, Cake\Event\EventDispatcherInterface, Cake\Validation\ValidatorAwareInterface uses Cake\Event\EventDispatcherTrait , Cake\Validation\ValidatorAwareTrait
Constants summary
-
string
BUILD_VALIDATOR_EVENT
'Form.buildValidator'
-
string
VALIDATOR_PROVIDER_NAME
'form'
Inherited Constants
Properties summary
-
$_data
protectedarray
-
$_errors
protectedarray
-
$_schema
protected -
$_schemaClass
protectedstring
-
$_validator
protected
Inherited Properties
Method Summary
-
__construct() publicConstructor
-
__debugInfo() publicGet the printable version of a Form instance.
-
_buildSchema() protectedA hook method intended to be implemented by subclasses.
- A hook method intended to be implemented by subclasses.
-
_execute() protectedHook method to be implemented in subclasses.
-
buildValidator() publicCallback method for Form.buildValidator event.
- Get the errors in the form
-
execute() publicExecute the form if it is valid.
-
getData() publicGet field data.
-
getErrors() publicGet the errors in the form
-
implementedEvents() publicGet the Form callbacks this form is interested in.
-
schema() publicGet/Set the schema for this form.
-
setData() publicSet form data.
-
setErrors() publicSet the errors in the form.
-
validate() publicUsed to check if $data passes this form's validation.
- Get/Set the validator for this form.
Method Detail
__construct()source public
__construct( Cake\Event\EventManager $eventManager = null )
Constructor
Parameters
-
Cake\Event\EventManager
$eventManager
optional null -
The event manager. Defaults to a new instance.
__debugInfo()source public
__debugInfo( )
Get the printable version of a Form instance.
Returns
array_buildSchema()source protected
_buildSchema( Cake\Form\Schema $schema )
A 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
The schema to use.
_buildValidator()source protected deprecated
_buildValidator( Cake\Validation\Validator $validator )
A 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.
Deprecated
3.6.0 Use Form::getValidator()/setValidator() and buildValidator() instead.Parameters
-
Cake\Validation\Validator
$validator
- The validator to customize.
Returns
Cake\Validation\Validator
The validator to use.
_execute()source protected
_execute( array $data )
Hook method to be implemented in subclasses.
Used by execute()
to execute the form's action.
Parameters
-
array
$data
- Form data.
Returns
booleanbuildValidator()source public
buildValidator( Cake\Event\Event $event , Cake\Validation\Validator $validator , string $name )
Callback 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
errors()source public deprecated
errors( )
Get the errors in the form
Will return the errors from the last call to validate()
or execute()
.
Deprecated
3.7.0 Use Form::getErrors() instead.Returns
arrayLast set validation errors.
execute()source public
execute( array $data )
Execute 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
booleanFalse on validation failure, otherwise returns the result of the _execute()
method.
getData()source public
getData( string|null $field = null )
Get field data.
Parameters
-
string|null
$field
optional null -
The field name or null to get data array with all fields.
Returns
mixedSince
3.7.0getErrors()source public
getErrors( )
Get the errors in the form
Will return the errors from the last call to validate()
or execute()
.
Returns
arrayLast set validation errors.
implementedEvents()source public
implementedEvents( )
Get the Form callbacks this form is interested in.
The conventional method map is:
- Form.buildValidator => buildValidator
Returns
arrayImplementation of
Cake\Event\EventListenerInterface::implementedEvents()
schema()source public
schema( Cake\Form\Schema $schema = null )
Get/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
$schema
optional null - The schema to set, or null.
Returns
Cake\Form\Schema
the schema instance.
setData()source public
setData( array $data )
Set form data.
Parameters
-
array
$data
- Data array.
Returns
$this
Since
3.7.0setErrors()source public
setErrors( array $errors )
Set the errors in the form.
$errors = [ 'field_name' => ['rule_name' => 'message'] ]; $form->setErrors($errors);
Parameters
-
array
$errors
- Errors list.
Returns
$this
Since
3.5.1validate()source public
validate( array $data )
Used to check if $data passes this form's validation.
Parameters
-
array
$data
- The data to check.
Returns
booleanWhether or not the data is valid.
validator()source public deprecated
validator( Cake\Validation\Validator $validator = null )
Get/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.
Deprecated
3.6.0 Use Form::getValidator()/setValidator() instead.Parameters
-
Cake\Validation\Validator
$validator
optional null - The validator to set, or null.
Returns
Cake\Validation\Validator
the validator instance.
Methods used from Cake\Event\EventDispatcherTrait
dispatchEvent()source public
dispatchEvent( string $name , array|null $data = null , object|null $subject = null )
Wrapper for creating and dispatching events.
Returns a dispatched event.
Parameters
-
string
$name
- Name of the event.
-
array|null
$data
optional null -
Any value you wish to be transported with this event to it can be read by listeners.
-
object|null
$subject
optional null -
The object that this event applies to ($this by default).
Returns
Cake\Event\Event
eventManager()source public deprecated
eventManager( Cake\Event\EventManager $eventManager = null )
Returns 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.
Deprecated
3.5.0 Use getEventManager()/setEventManager() instead.Parameters
-
Cake\Event\EventManager
$eventManager
optional null - the eventManager to set
Returns
Cake\Event\EventManager
getEventManager()source public
getEventManager( )
Returns 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\EventManager
setEventManager()source public
setEventManager( Cake\Event\EventManager $eventManager )
Returns 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
$this
Methods used from Cake\Validation\ValidatorAwareTrait
createValidator()source protected
createValidator( string $name )
Creates 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\Validator
Throws
RuntimeExceptiongetValidator()source public
getValidator( string|null $name = null )
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.
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 null - The name of the validation set to return.
Returns
Cake\Validation\Validator
hasValidator()source public
hasValidator( string $name )
Checks whether or not a validator has been set.
Parameters
-
string
$name
- The name of a validator.
Returns
booleansetValidator()source public
setValidator( string $name , Cake\Validation\Validator $validator )
This 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
$this
validationDefault()source public
validationDefault( Cake\Validation\Validator $validator )
Returns 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\Validator
validationMethodExists()source protected
validationMethodExists( string $name )
Checks if validation method exists.
Parameters
-
string
$name
- Validation method name.
Returns
booleanMagic methods inherited from Cake\Event\EventDispatcherInterface
getEventManager() |
Properties detail
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.7/class-Cake.Form.Form.html