Fr3nch13/CakePHP Utilities

Form
in package

Application

implements EventListenerInterface, EventDispatcherInterface, ValidatorAwareInterface uses EventDispatcherTrait, ValidatorAwareTrait

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.

Interfaces

EventListenerInterface: Objects implementing this interface should declare the `implementedEvents()` method to notify the event manager what methods should be called when an event is triggered.
EventDispatcherInterface: Objects implementing this interface can emit events.
ValidatorAwareInterface: Provides methods for managing multiple validators.

Constants

BUILD_VALIDATOR_EVENT = 'Form.buildValidator': The name of the event dispatched when a validator has been built.
DEFAULT_VALIDATOR = 'default': Name of default validation set.
VALIDATOR_PROVIDER_NAME = 'form': The alias this object is assigned to validators as.

Properties

$_data : array<string|int, mixed>: Form's data.
$_errors : array<string|int, mixed>: The errors if any
$_eventClass : string: Default class name for new event objects.
$_eventManager : EventManagerInterface|null: Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
$_schema : Schema|null: The schema used by this form.
$_schemaClass : string: Schema class.
$_validatorClass : string: Validator class.
$_validators : array<string|int, Validator>: A list of validation objects indexed by name

Methods

__construct() : mixed: Constructor
__debugInfo() : array<string, mixed>: Get the printable version of a Form instance.
dispatchEvent() : EventInterface: Wrapper for creating and dispatching events.
execute() : bool: Execute the form if it is valid.
getData() : mixed: Get field data.
getErrors() : array<string|int, mixed>: Get the errors in the form
getEventManager() : EventManagerInterface: Returns the Cake\Event\EventManager manager instance for this object.
getSchema() : Schema: Get the schema for this form.
getValidator() : 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.
hasValidator() : bool: Checks whether a validator has been set.
implementedEvents() : array<string, mixed>: Get the Form callbacks this form is interested in.
schema() : Schema: Get/Set the schema for this form.
set() : $this: Saves a variable or an associative array of variables for use inside form data.
setData() : $this: Set form data.
setErrors() : $this: Set the errors in the form.
setEventManager() : $this: Returns the Cake\Event\EventManagerInterface instance for this object.
setSchema() : $this: Set the schema for this form.
setValidator() : $this: This method stores a custom validator under the given name.
validate() : bool: Used to check if $data passes this form's validation.
validationDefault() : Validator: Returns the default validator object. Subclasses can override this function to add a default validation set to the validator object.
_buildSchema() : Schema: A hook method intended to be implemented by subclasses.
_execute() : bool: Hook method to be implemented in subclasses.
createValidator() : Validator: Creates a validator using a custom method inside your class.
validationMethodExists() : bool: Checks if validation method exists.

BUILD_VALIDATOR_EVENT

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


    public
        string
    BUILD_VALIDATOR_EVENT
    = 'Form.buildValidator'

DEFAULT_VALIDATOR

Name of default validation set.


    public
        string
    DEFAULT_VALIDATOR
    = 'default'

VALIDATOR_PROVIDER_NAME

The alias this object is assigned to validators as.


    public
        string
    VALIDATOR_PROVIDER_NAME
    = 'form'

$_data

Form's data.


    protected
        array<string|int, mixed>
    $_data
     = []

$_errors

The errors if any


    protected
        array<string|int, mixed>
    $_errors
     = []

$_eventClass

Default class name for new event objects.


    protected
        string
    $_eventClass
     = \Cake\Event\Event::class

$_eventManager

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


    protected
        EventManagerInterface|null
    $_eventManager

$_schema

The schema used by this form.


    protected
        Schema|null
    $_schema

$_schemaClass

Schema class.


    protected
        string
    $_schemaClass
     = \Cake\Form\Schema::class

$_validatorClass

Validator class.


    protected
        string
    $_validatorClass
     = \Cake\Validation\Validator::class

$_validators

A list of validation objects indexed by name


    protected
        array<string|int, Validator>
    $_validators
     = []

__construct()

Constructor


    public
                    __construct([EventManager|null $eventManager = null ]) : mixed

Parameters

$eventManager : EventManager|null = null: The event manager. Defaults to a new instance.

__debugInfo()

Get the printable version of a Form instance.


    public
                    __debugInfo() : array<string, mixed>

Return values

array<string, mixed>

dispatchEvent()

Wrapper for creating and dispatching events.


    public
                    dispatchEvent(string $name[, array<string|int, mixed>|null $data = null ][, object|null $subject = null ]) : EventInterface

Returns a dispatched event.

Parameters

$name : string: Name of the event.
$data : array<string|int, mixed>|null = null: Any value you wish to be transported with this event to it can be read by listeners.
$subject : object|null = null: The object that this event applies to ($this by default).

Return values

EventInterface

execute()

Execute the form if it is valid.


    public
                    execute(array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : bool

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

$data : array<string|int, mixed>: Form data.
$options : array<string, mixed> = []: List of options.

Return values

bool —

False on validation failure, otherwise returns the result of the _execute() method.

getData()

Get field data.


    public
                    getData([string|null $field = null ]) : mixed

Parameters

$field : string|null = null: The field name or null to get data array with all fields.

getErrors()

Get the errors in the form


    public
                    getErrors() : array<string|int, mixed>

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

Return values

array<string|int, mixed> —

Last set validation errors.

getEventManager()

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


    public
                    getEventManager() : EventManagerInterface

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.

Return values

EventManagerInterface

getSchema()

Get the schema for this form.


    public
                    getSchema() : Schema

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.

Return values

Schema —

the schema instance.

getValidator()

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.


    public
                    getValidator([string|null $name = null ]) : Validator

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

$name : string|null = null: The name of the validation set to return.

Return values

Validator

hasValidator()

Checks whether a validator has been set.


    public
                    hasValidator(string $name) : bool

Parameters

$name : string: The name of a validator.

Return values

bool

implementedEvents()

Get the Form callbacks this form is interested in.


    public
                    implementedEvents() : array<string, mixed>

The conventional method map is:

Form.buildValidator => buildValidator

Return values

array<string, mixed>

schema()

Get/Set the schema for this form.


    public
                    schema([Schema|null $schema = null ]) : Schema

Use / instead.

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

$schema : Schema|null = null: The schema to set, or null.

Return values

Schema —

the schema instance.

set()

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


    public
                    set(array<string|int, mixed>|string $name[, mixed $value = null ]) : $this

Parameters

$name : array<string|int, mixed>|string: The key to write, can be a dot notation value. Alternatively can be an array containing key(s) and value(s).
$value : mixed = null: Value to set for var

Return values

$this

setData()

Set form data.


    public
                    setData(array<string|int, mixed> $data) : $this

Parameters

$data : array<string|int, mixed>: Data array.

Return values

$this

setErrors()

Set the errors in the form.


    public
                    setErrors(array<string|int, mixed> $errors) : $this

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

$form->setErrors($errors);

Parameters

$errors : array<string|int, mixed>: Errors list.

Return values

$this

setEventManager()

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


    public
                    setEventManager(EventManagerInterface $eventManager) : $this

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

$eventManager : EventManagerInterface: the eventManager to set

Return values

$this

setSchema()

Set the schema for this form.


    public
                    setSchema(Schema $schema) : $this

Parameters

$schema : Schema: The schema to set

Return values

$this

setValidator()

This method stores a custom validator under the given name.


    public
                    setValidator(string $name, Validator $validator) : $this

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

$name : string: The name of a validator to be set.
$validator : Validator: Validator object to be set.

Return values

$this

validate()

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


    public
                    validate(array<string|int, mixed> $data[, string|null $validator = null ]) : bool

Parameters

$data : array<string|int, mixed>: The data to check.
$validator : string|null = null: Validator name.

Return values

bool —

Whether the data is valid.

validationDefault()

Returns the default validator object. Subclasses can override this function to add a default validation set to the validator object.


    public
                    validationDefault(Validator $validator) : Validator

Parameters

$validator : Validator: The validator that can be modified to add some rules to it.

Return values

Validator

_buildSchema()

A hook method intended to be implemented by subclasses.


    protected
                    _buildSchema(Schema $schema) : Schema

You can use this method to define the schema using the methods on , or loads a pre-defined schema from a concrete class.

Parameters

$schema : Schema: The schema to customize.

Return values

Schema —

The schema to use.

_execute()

Hook method to be implemented in subclasses.


    protected
                    _execute(array<string|int, mixed> $data) : bool

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

Parameters

$data : array<string|int, mixed>: Form data.

Return values

bool

createValidator()

Creates a validator using a custom method inside your class.


    protected
                    createValidator(string $name) : Validator

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

$name : string: The name of the validation set to create.

Return values

Validator

validationMethodExists()

Checks if validation method exists.


    protected
                    validationMethodExists(string $name) : bool

Parameters

$name : string: Validation method name.

Return values

bool

Form in package Application implements EventListenerInterface, EventDispatcherInterface, ValidatorAwareInterface uses EventDispatcherTrait, ValidatorAwareTrait

Building a form

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

BUILD_VALIDATOR_EVENT

DEFAULT_VALIDATOR

VALIDATOR_PROVIDER_NAME

Properties

$_data

$_errors

$_eventClass

$_eventManager

$_schema

$_schemaClass

Tags

$_validatorClass

$_validators

Methods

__construct()

Parameters

__debugInfo()

Return values

dispatchEvent()

Parameters

Return values

execute()

Options:

Parameters

Return values

getData()

Parameters

getErrors()

Return values

getEventManager()

Return values

getSchema()

Tags

Return values

getValidator()

Parameters

Return values

hasValidator()

Parameters

Return values

implementedEvents()

Return values

schema()

Parameters

Return values

set()

Parameters

Return values

setData()

Parameters

Return values

setErrors()

Parameters

Return values

setEventManager()

Parameters

Return values

setSchema()

Parameters

Tags

Return values

setValidator()

Parameters

Return values

validate()

Parameters

Tags

Return values

validationDefault()

Parameters

Return values

_buildSchema()

Form
in package

Application

implements EventListenerInterface, EventDispatcherInterface, ValidatorAwareInterface uses EventDispatcherTrait, ValidatorAwareTrait