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 4.6 Strawberry API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 4.6
      • 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, validationDefault and optionally, the _execute methods. These allow you to declare your form's fields, validation and primary action respectively.

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|null

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

  • $_schema protected
    Cake\Form\Schema|null

    The schema used by this form.

  • $_schemaClass protected
    string

    Schema class.

  • $_validatorClass protected
    string

    Validator class.

  • $_validators protected
    array<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.

  • _execute() protected

    Hook method to be implemented in subclasses.

  • createValidator() protected

    Creates a validator using a custom method inside your class.

  • dispatchEvent() public

    Wrapper for creating and dispatching events.

  • execute() public

    Execute the form if it is valid.

  • getData() public

    Get field data.

  • getError() public

    Returns validation errors for the given field

  • getErrors() public

    Get the errors in the form

  • getEventManager() public

    Returns the Cake\Event\EventManager manager instance for this object.

  • getSchema() public

    Get the schema for this form.

  • 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 a validator has been set.

  • implementedEvents() public

    Get the Form callbacks this form is interested in.

  • schema() public deprecated

    Get/Set the schema for this form.

  • set() public

    Saves a variable or an associative array of variables for use inside form data.

  • setData() public

    Set form data.

  • setErrors() public

    Set the errors in the form.

  • setEventManager() public

    Returns the Cake\Event\EventManagerInterface instance for this object.

  • setSchema() public

    Set the schema for this form.

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

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<string, mixed>

Get the printable version of a Form instance.

Returns
array<string, mixed>

_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 {@link \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

_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

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\EventInterface

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\EventInterface

execute() ¶ public

execute(array $data, array<string, mixed> $options = []): 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.

Options:

  • validate: Set to false to disable validation. Can also be a string of the validator ruleset to be applied. Defaults to true/'default'.
Parameters
array $data

Form data.

array<string, mixed> $options optional

List of options.

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

getError() ¶ public

getError(string $field): array

Returns validation errors for the given field

Parameters
string $field

Field name to get the errors from.

Returns
array

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\EventManagerInterface

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\EventManagerInterface

getSchema() ¶ public

getSchema(): Cake\Form\Schema

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

Returns
Cake\Form\Schema

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 a validator has been set.

Parameters
string $name

The name of a validator.

Returns
bool

implementedEvents() ¶ public

implementedEvents(): array<string, mixed>

Get the Form callbacks this form is interested in.

The conventional method map is:

  • Form.buildValidator => buildValidator
Returns
array<string, mixed>

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

set() ¶ public

set(array|string $name, mixed $value = null): $this

Saves a variable or an associative array of variables for use inside form data.

Parameters
array|string $name

The key to write, can be a dot notation value. Alternatively can be an array containing key(s) and value(s).

mixed $value optional

Value to set for var

Returns
$this

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\EventManagerInterface $eventManager): $this

Returns the Cake\Event\EventManagerInterface 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\EventManagerInterface $eventManager

the eventManager to set

Returns
$this

setSchema() ¶ public

setSchema(Cake\Form\Schema $schema): $this

Set the schema for this form.

Parameters
Cake\Form\Schema $schema

The schema 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();
$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, string|null $validator = null): bool

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

Parameters
array $data

The data to check.

string|null $validator optional

Validator name.

Returns
bool
Throws
RuntimeException
If validator is invalid.

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

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|null

$_schema ¶ protected

The schema used by this form.

Type
Cake\Form\Schema|null

$_schemaClass ¶ protected

Schema class.

Type
string

$_validatorClass ¶ protected

Validator class.

Type
string

$_validators ¶ protected

A list of validation objects indexed by name

Type
array<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