CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.10 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.10
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

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.

Namespace: Cake\Form

Constants

  • string
    BUILD_VALIDATOR_EVENT ¶
    'Form.buildValidator'

    The name of the event dispatched when a validator has been built.

  • string
    DEFAULT_VALIDATOR ¶
    'default'

    Name of default validation set.

  • string
    VALIDATOR_PROVIDER_NAME ¶
    'form'

    The alias this object is assigned to validators as.

Property Summary

  • $_data protected
    array

    Form's data.

  • $_errors protected
    array

    The errors if any

  • $_eventClass protected
    string

    Default class name for new event objects.

  • $_eventManager protected
    Cake\Event\EventManagerInterface|Cake\Event\EventManager

    Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

  • $_schema protected
    Cake\Form\Schema

    The schema used by this form.

  • $_schemaClass protected
    string

    Schema class.

  • $_validator protected
    Cake\Validation\Validator

    The validator used by this form.

  • $_validatorClass protected
    string

    Validator 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 deprecated

    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.

  • getData() public

    Get field data.

  • getErrors() public

    Get the errors in the form

  • 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.

  • setData() public

    Set form data.

  • 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(): array

Get the printable version of a Form instance.

Returns
array

_buildSchema() ¶ protected

_buildSchema(Cake\Form\Schema $schema): Cake\Form\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

_buildValidator() ¶ protected

_buildValidator(Cake\Validation\Validator $validator): Cake\Validation\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.

Parameters
Cake\Validation\Validator $validator

The validator to customize.

Returns
Cake\Validation\Validator

_execute() ¶ protected

_execute(array $data): bool

Hook method to be implemented in subclasses.

Used by execute() to execute the form's action.

Parameters
array $data

Form data.

Returns
bool

buildValidator() ¶ public

buildValidator(Cake\Event\Event $event, Cake\Validation\Validator $validator, string $name): void

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

Returns
void

createValidator() ¶ protected

createValidator(string $name): Cake\Validation\Validator

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
RuntimeException

dispatchEvent() ¶ public

dispatchEvent(string $name, array|null $data = null, object|null $subject = null): Cake\Event\Event

Wrapper 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\Event

errors() ¶ public

errors(): array

Get the errors in the form

Will return the errors from the last call to validate() or execute().

Returns
array

eventManager() ¶ public

eventManager(Cake\Event\EventManager|null $eventManager = null): Cake\Event\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|null $eventManager optional

the eventManager to set

Returns
Cake\Event\EventManager

execute() ¶ public

execute(array $data): bool

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
bool

getData() ¶ public

getData(string|null $field = null): mixed

Get field data.

Parameters
string|null $field optional

The field name or null to get data array with all fields.

Returns
mixed

getErrors() ¶ public

getErrors(): array

Get the errors in the form

Will return the errors from the last call to validate() or execute().

Returns
array

getEventManager() ¶ public

getEventManager(): Cake\Event\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.

Returns
Cake\Event\EventManager

getValidator() ¶ public

getValidator(string|null $name = null): Cake\Validation\Validator

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

The name of the validation set to return.

Returns
Cake\Validation\Validator

hasValidator() ¶ public

hasValidator(string $name): bool

Checks whether or not a validator has been set.

Parameters
string $name

The name of a validator.

Returns
bool

implementedEvents() ¶ public

implementedEvents(): array

Get the Form callbacks this form is interested in.

The conventional method map is:

  • Form.buildValidator => buildValidator
Returns
array

schema() ¶ public

schema(Cake\Form\Schema|null $schema = null): Cake\Form\Schema

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|null $schema optional

The schema to set, or null.

Returns
Cake\Form\Schema

setData() ¶ public

setData(array $data): $this

Set form data.

Parameters
array $data

Data array.

Returns
$this

setErrors() ¶ public

setErrors(array $errors): $this

Set the errors in the form.

$errors = [
     'field_name' => ['rule_name' => 'message']
];

$form->setErrors($errors);
Parameters
array $errors

Errors list.

Returns
$this

setEventManager() ¶ public

setEventManager(Cake\Event\EventManager $eventManager): $this

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

setValidator() ¶ public

setValidator(string $name, Cake\Validation\Validator $validator): $this

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

validate() ¶ public

validate(array $data): bool

Used to check if $data passes this form's validation.

Parameters
array $data

The data to check.

Returns
bool

validationDefault() ¶ public

validationDefault(Cake\Validation\Validator $validator): Cake\Validation\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() ¶ protected

validationMethodExists(string $name): bool

Checks if validation method exists.

Parameters
string $name

Validation method name.

Returns
bool

validator() ¶ public

validator(Cake\Validation\Validator|null $validator = null): Cake\Validation\Validator

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.

Parameters
Cake\Validation\Validator|null $validator optional

The validator to set, or null.

Returns
Cake\Validation\Validator

Property Detail

$_data ¶ protected

Form's data.

Type
array

$_errors ¶ protected

The errors if any

Type
array

$_eventClass ¶ protected

Default class name for new event objects.

Type
string

$_eventManager ¶ protected

Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

Type
Cake\Event\EventManagerInterface|Cake\Event\EventManager

$_schema ¶ protected

The schema used by this form.

Type
Cake\Form\Schema

$_schemaClass ¶ protected

Schema class.

Type
string

$_validator ¶ protected

The validator used by this form.

Type
Cake\Validation\Validator

$_validatorClass ¶ protected

Validator class.

Type
string

$_validators ¶ protected

A list of validation objects indexed by name

Type
Cake\Validation\Validator[]
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs