Class Marshaller

Contains logic to convert array data into entities.

Useful when converting request data into entities.

Namespace: Cake\ORM
See: \Cake\ORM\Table::newEntity()
See: \Cake\ORM\Table::newEntities()
See: \Cake\ORM\Table::patchEntity()
See: \Cake\ORM\Table::patchEntities()

Property Summary

$_table protected

Cake\ORM\Table

The table instance this marshaller is for.

Method Summary

__construct() public

Constructor.
_belongsToMany() protected

Marshals data for belongsToMany associations.
_buildPropertyMap() protected

Build the map of property => marshalling callable.
_loadAssociatedByIds() protected

Loads a list of belongs to many from ids.
_loadBelongsToMany() protected deprecated

Loads a list of belongs to many from ids.
_marshalAssociation() protected

Create a new sub-marshaller and marshal the associated data.
_mergeAssociation() protected

Creates a new sub-marshaller and merges the associated data.
_mergeBelongsToMany() protected

Creates a new sub-marshaller and merges the associated data for a BelongstoMany association.
_mergeJoinData() protected

Merge the special _joinData property into the entity set.
_normalizeAssociations() protected

Returns an array out of the original passed associations list where dot notation is transformed into nested arrays so that they can be parsed by other routines
_prepareDataAndOptions() protected

Returns data and options prepared to validate and marshall.
_validate() protected

Returns the validation errors for a data set based on the passed options
dispatchAfterMarshal() protected

dispatch Model.afterMarshal event.
many() public

Hydrate many entities and their associated data.
merge() public

Merges $data into $entity and recursively does the same for each one of the association names passed in $options. When merging associations, if an entity is not present in the parent entity for a given association, a new one will be created.
mergeMany() public

Merges each of the elements from $data into each of the entities in $entities and recursively does the same for each of the association names passed in $options. When merging associations, if an entity is not present in the parent entity for a given association, a new one will be created.
one() public

Hydrate one entity and its associated data.

Method Detail

__construct() ¶ public

__construct(Cake\ORM\Table $table)

Constructor.

Parameters

Cake\ORM\Table $table: The table this marshaller is for.

_belongsToMany() ¶ protected

_belongsToMany(Cake\ORM\Association\BelongsToMany $assoc, array $data, array $options = []): Cake\Datasource\EntityInterface[]

Marshals data for belongsToMany associations.

Builds the related entities and handles the special casing for junction table entities.

Parameters

Cake\ORM\Association\BelongsToMany $assoc: The association to marshal.
array $data: The data to convert into entities.
array $options optional: List of options.

Returns

Cake\Datasource\EntityInterface[]

Throws

BadMethodCallException

InvalidArgumentException

RuntimeException

_buildPropertyMap() ¶ protected

_buildPropertyMap(array $data, array $options): array

Build the map of property => marshalling callable.

Parameters

array $data: The data being marshalled.
array $options: List of options containing the 'associated' key.

Returns

array

Throws

InvalidArgumentException
When associations do not exist.

_loadAssociatedByIds() ¶ protected

_loadAssociatedByIds(Cake\ORM\Association $assoc, array $ids): Cake\Datasource\EntityInterface[]

Loads a list of belongs to many from ids.

Parameters

Cake\ORM\Association $assoc: The association class for the belongsToMany association.
array $ids: The list of ids to load.

Returns

Cake\Datasource\EntityInterface[]

_loadBelongsToMany() ¶ protected

_loadBelongsToMany(Cake\ORM\Association $assoc, array $ids): Cake\Datasource\EntityInterface[]

Loads a list of belongs to many from ids.

Parameters

Cake\ORM\Association $assoc: The association class for the belongsToMany association.
array $ids: The list of ids to load.

Returns

Cake\Datasource\EntityInterface[]

_marshalAssociation() ¶ protected

_marshalAssociation(Cake\ORM\Association $assoc, array $value, array $options): Cake\Datasource\EntityInterface|Cake\Datasource\EntityInterface[]|null

Create a new sub-marshaller and marshal the associated data.

Parameters

Cake\ORM\Association $assoc: The association to marshall
array $value: The data to hydrate
array $options: List of options.

Returns

Cake\Datasource\EntityInterface|Cake\Datasource\EntityInterface[]|null

_mergeAssociation() ¶ protected

_mergeAssociation(Cake\Datasource\EntityInterface|Cake\Datasource\EntityInterface[] $original, Cake\ORM\Association $assoc, array $value, array $options): Cake\Datasource\EntityInterface|Cake\Datasource\EntityInterface[]|null

Creates a new sub-marshaller and merges the associated data.

Parameters

Cake\Datasource\EntityInterface|Cake\Datasource\EntityInterface[] $original: The original entity
Cake\ORM\Association $assoc: The association to merge
array $value: The data to hydrate
array $options: List of options.

Returns

Cake\Datasource\EntityInterface|Cake\Datasource\EntityInterface[]|null

_mergeBelongsToMany() ¶ protected

_mergeBelongsToMany(Cake\Datasource\EntityInterface $original, Cake\ORM\Association $assoc, array $value, array $options): Cake\Datasource\EntityInterface[]

Creates a new sub-marshaller and merges the associated data for a BelongstoMany association.

Parameters

Cake\Datasource\EntityInterface $original: The original entity
Cake\ORM\Association $assoc: The association to marshall
array $value: The data to hydrate
array $options: List of options.

Returns

Cake\Datasource\EntityInterface[]

_mergeJoinData() ¶ protected

_mergeJoinData(Cake\Datasource\EntityInterface $original, Cake\ORM\Association\BelongsToMany $assoc, array $value, array $options): Cake\Datasource\EntityInterface[]

Merge the special _joinData property into the entity set.

Parameters

Cake\Datasource\EntityInterface $original: The original entity
Cake\ORM\Association\BelongsToMany $assoc: The association to marshall
array $value: The data to hydrate
array $options: List of options.

Returns

Cake\Datasource\EntityInterface[]

_normalizeAssociations() ¶ protected

_normalizeAssociations(array|string $associations): array

Returns an array out of the original passed associations list where dot notation is transformed into nested arrays so that they can be parsed by other routines

Parameters

array|string $associations: The array of included associations.

Returns

array

_prepareDataAndOptions() ¶ protected

_prepareDataAndOptions(array $data, array $options): array

Returns data and options prepared to validate and marshall.

Parameters

array $data: The data to prepare.
array $options: The options passed to this marshaller.

Returns

array

_validate() ¶ protected

_validate(array $data, array $options, bool $isNew): array

Returns the validation errors for a data set based on the passed options

Parameters

array $data: The data to validate.
array $options: The options passed to this marshaller.
bool $isNew: Whether it is a new entity or one to be updated.

Returns

array

Throws

RuntimeException
If no validator can be created.

dispatchAfterMarshal() ¶ protected

dispatchAfterMarshal(Cake\Datasource\EntityInterface $entity, array $data, array $options): void

dispatch Model.afterMarshal event.

Parameters

Cake\Datasource\EntityInterface $entity: The entity that was marshaled.
array $data: readOnly $data to use.
array $options: List of options that are readOnly.

Returns

void

many() ¶ public

many(array $data, array $options = []): Cake\Datasource\EntityInterface[]

Hydrate many entities and their associated data.

Options:

validate: Set to false to disable validation. Can also be a string of the validator ruleset to be applied. Defaults to true/default.
associated: Associations listed here will be marshalled as well. Defaults to null.
fieldList: (deprecated) Since 3.4.0. Use fields instead
fields: A whitelist of fields to be assigned to the entity. If not present, the accessible fields list in the entity will be used. Defaults to null.
accessibleFields: A list of fields to allow or deny in entity accessible fields. Defaults to null
forceNew: When enabled, belongsToMany associations will have 'new' entities created when primary key values are set, and a record does not already exist. Normally primary key on missing entities would be ignored. Defaults to false.

Parameters

array $data: The data to hydrate.
array $options optional: List of options

Returns

Cake\Datasource\EntityInterface[]

merge() ¶ public

merge(Cake\Datasource\EntityInterface $entity, array $data, array $options = []): Cake\Datasource\EntityInterface

Merges $data into $entity and recursively does the same for each one of the association names passed in $options. When merging associations, if an entity is not present in the parent entity for a given association, a new one will be created.

When merging HasMany or BelongsToMany associations, all the entities in the $data array will appear, those that can be matched by primary key will get the data merged, but those that cannot, will be discarded. ids option can be used to determine whether the association must use the _ids format.

Options:

associated: Associations listed here will be marshalled as well.
validate: Whether or not to validate data before hydrating the entities. Can also be set to a string to use a specific validator. Defaults to true/default.
fieldList: (deprecated) Since 3.4.0. Use fields instead
fields: A whitelist of fields to be assigned to the entity. If not present the accessible fields list in the entity will be used.
accessibleFields: A list of fields to allow or deny in entity accessible fields.

The above options can be used in each nested associated array. In addition to the above options you can also use the onlyIds option for HasMany and BelongsToMany associations. When true this option restricts the request data to only be read from _ids.

$result = $marshaller->merge($entity, $data, [
  'associated' => ['Tags' => ['onlyIds' => true]]
]);

Parameters

Cake\Datasource\EntityInterface $entity: the entity that will get the data merged in
array $data: key value list of fields to be merged into the entity
array $options optional: List of options.

Returns

Cake\Datasource\EntityInterface

mergeMany() ¶ public

mergeMany(Cake\Datasource\EntityInterface[]|Traversable $entities, array $data, array $options = []): Cake\Datasource\EntityInterface[]

Merges each of the elements from $data into each of the entities in $entities and recursively does the same for each of the association names passed in $options. When merging associations, if an entity is not present in the parent entity for a given association, a new one will be created.

Records in $data are matched against the entities using the primary key column. Entries in $entities that cannot be matched to any record in $data will be discarded. Records in $data that could not be matched will be marshalled as a new entity.

Options:

validate: Whether or not to validate data before hydrating the entities. Can also be set to a string to use a specific validator. Defaults to true/default.
associated: Associations listed here will be marshalled as well.
fieldList: (deprecated) Since 3.4.0. Use fields instead
fields: A whitelist of fields to be assigned to the entity. If not present, the accessible fields list in the entity will be used.
accessibleFields: A list of fields to allow or deny in entity accessible fields.

Parameters

Cake\Datasource\EntityInterface[]|Traversable $entities: the entities that will get the data merged in
array $data: list of arrays to be merged into the entities
array $options optional: List of options.

Returns

Cake\Datasource\EntityInterface[]

one() ¶ public

one(array $data, array $options = []): Cake\Datasource\EntityInterface

Hydrate one entity and its associated data.

Options:

validate: Set to false to disable validation. Can also be a string of the validator ruleset to be applied. Defaults to true/default.
associated: Associations listed here will be marshalled as well. Defaults to null.
fieldList: (deprecated) Since 3.4.0. Use fields instead.
fields: A whitelist of fields to be assigned to the entity. If not present, the accessible fields list in the entity will be used. Defaults to null.
accessibleFields: A list of fields to allow or deny in entity accessible fields. Defaults to null
forceNew: When enabled, belongsToMany associations will have 'new' entities created when primary key values are set, and a record does not already exist. Normally primary key on missing entities would be ignored. Defaults to false.

$result = $marshaller->one($data, [
  'associated' => ['Tags' => ['onlyIds' => true]]
]);

$result = $marshaller->one($data, [
  'associated' => [
    'Tags' => ['accessibleFields' => ['*' => true]]
  ]
]);

Parameters

array $data: The data to hydrate.
array $options optional: List of options

Returns

Cake\Datasource\EntityInterface

Property Detail

`$_table` ¶ protected

The table instance this marshaller is for.

Type

Cake\ORM\Table

Namespaces

Class Marshaller

Property Summary

Method Summary

__construct() public

_belongsToMany() protected

_buildPropertyMap() protected

_loadAssociatedByIds() protected

_loadBelongsToMany() protected deprecated

_marshalAssociation() protected

_mergeAssociation() protected

_mergeBelongsToMany() protected

_mergeJoinData() protected

_normalizeAssociations() protected

_prepareDataAndOptions() protected

_validate() protected

dispatchAfterMarshal() protected

many() public

merge() public

mergeMany() public

one() public

Method Detail

__construct() ¶ public

Parameters

_belongsToMany() ¶ protected

Parameters

Returns

Throws

_buildPropertyMap() ¶ protected

Parameters

Returns

Throws

_loadAssociatedByIds() ¶ protected

Parameters

Returns

_loadBelongsToMany() ¶ protected

Parameters

Returns

_marshalAssociation() ¶ protected

Parameters

Returns

_mergeAssociation() ¶ protected

Parameters

Returns

_mergeBelongsToMany() ¶ protected

Parameters

Returns

_mergeJoinData() ¶ protected

Parameters

Returns

_normalizeAssociations() ¶ protected

Parameters

Returns

_prepareDataAndOptions() ¶ protected

Parameters

Returns

_validate() ¶ protected

Parameters

Returns

Throws

dispatchAfterMarshal() ¶ protected

Parameters

Returns

many() ¶ public

Options:

Parameters

Returns

See Also

merge() ¶ public

Options:

Parameters

Returns

See Also

mergeMany() ¶ public

Options:

Parameters

Returns

See Also

one() ¶ public

Options:

`$_table` ¶ protected