\Cake\ORMMarshaller

Contains logic to convert array data into entities.

Useful when converting request data into entities.

Summary

Methods
Properties
Constants
__construct()
one()
many()
merge()
mergeMany()
No public properties found
No constants found
_normalizeAssociations()
_buildPropertyMap()
_validate()
_prepareDataAndOptions()
_marshalAssociation()
_belongsToMany()
_loadAssociatedByIds()
_loadBelongsToMany()
_mergeAssociation()
_mergeBelongsToMany()
_mergeJoinData()
$_table
N/A
No private methods found
No private properties found
N/A

Properties

$_table

$_table : \Cake\ORM\Table

The table instance this marshaller is for.

Type

\Cake\ORM\Table

Methods

__construct()

__construct(\Cake\ORM\Table  $table) 

Constructor.

Parameters

\Cake\ORM\Table $table

The table this marshaller is for.

one()

one(array  $data, array  $options = array()) : \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.

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->one($data, [
  'associated' => ['Tags' => ['onlyIds' => true]]
]);

Parameters

array $data

The data to hydrate.

array $options

List of options

Returns

\Cake\Datasource\EntityInterface

many()

many(array  $data, array  $options = array()) : array<mixed,\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

List of options

Returns

array<mixed,\Cake\Datasource\EntityInterface> —

An array of hydrated records.

merge()

merge(\Cake\Datasource\EntityInterface  $entity, array  $data, array  $options = array()) : \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

List of options.

Returns

\Cake\Datasource\EntityInterface

mergeMany()

mergeMany(array<mixed,\Cake\Datasource\EntityInterface>|\Traversable  $entities, array  $data, array  $options = array()) : array<mixed,\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.

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.

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

array<mixed,\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

List of options.

Returns

array<mixed,\Cake\Datasource\EntityInterface>

_normalizeAssociations()

_normalizeAssociations(array  $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 $associations

The array of included associations.

Returns

array —

An array having dot notation transformed into nested arrays

_buildPropertyMap()

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

Throws

\InvalidArgumentException

When associations do not exist.

Returns

array

_validate()

_validate(array  $data, array  $options, boolean  $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.

boolean $isNew

Whether it is a new entity or one to be updated.

Throws

\RuntimeException

If no validator can be created.

Returns

array —

The list of validation errors.

_prepareDataAndOptions()

_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 —

An array containing prepared data and options.

_marshalAssociation()

_marshalAssociation(\Cake\ORM\Association  $assoc, array  $value, array  $options) : \Cake\Datasource\EntityInterface|array<mixed,\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|array<mixed,\Cake\Datasource\EntityInterface>|null

_belongsToMany()

_belongsToMany(\Cake\ORM\Association\BelongsToMany  $assoc, array  $data, array  $options = array()) : array<mixed,\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

List of options.

Throws

\BadMethodCallException
\InvalidArgumentException
\RuntimeException

Returns

array<mixed,\Cake\Datasource\EntityInterface> —

An array of built entities.

_loadAssociatedByIds()

_loadAssociatedByIds(\Cake\ORM\Association  $assoc, array  $ids) : array<mixed,\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

array<mixed,\Cake\Datasource\EntityInterface> —

An array of entities.

_loadBelongsToMany()

_loadBelongsToMany(\Cake\ORM\Association  $assoc, array  $ids) : array<mixed,\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

array<mixed,\Cake\Datasource\EntityInterface> —

An array of entities.

_mergeAssociation()

_mergeAssociation(\Cake\Datasource\EntityInterface|array<mixed,\Cake\Datasource\EntityInterface>  $original, \Cake\ORM\Association  $assoc, array  $value, array  $options) : \Cake\Datasource\EntityInterface|array<mixed,\Cake\Datasource\EntityInterface>|null

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

Parameters

\Cake\Datasource\EntityInterface|array<mixed,\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|array<mixed,\Cake\Datasource\EntityInterface>|null

_mergeBelongsToMany()

_mergeBelongsToMany(\Cake\Datasource\EntityInterface  $original, \Cake\ORM\Association  $assoc, array  $value, array  $options) : array<mixed,\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

array<mixed,\Cake\Datasource\EntityInterface>

_mergeJoinData()

_mergeJoinData(\Cake\Datasource\EntityInterface  $original, \Cake\ORM\Association\BelongsToMany  $assoc, array  $value, array  $options) : array<mixed,\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

array<mixed,\Cake\Datasource\EntityInterface> —

An array of entities