Class Marshaller

Contains logic to convert array data into entities.

Useful when converting request data into entities.

Cake\ORM\Marshaller uses Cake\ORM\AssociationsNormalizerTrait
Namespace: Cake\ORM
See: \Cake\ORM\Table::newEntity()
See: \Cake\ORM\Table::newEntities()
See: \Cake\ORM\Table::patchEntity()
See: \Cake\ORM\Table::patchEntities()
Location: ORM/Marshaller.php

Properties summary

Method Summary

  • __construct() public
    Constructor.
  • _belongsToMany() protected
    Marshals data for belongsToMany associations.
  • Build the map of property => marshalling callable.
  • Loads a list of belongs to many from ids.
  • _loadBelongsToMany() protected deprecated
    Loads a list of belongs to many from ids.
  • Create a new sub-marshaller and marshal the associated data.
  • Creates a new sub-marshaller and merges the associated data.

  • 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.
  • Returns data and options prepared to validate and marshall.
  • _validate() protected
    Returns the validation errors for a data set based on the passed options
  • 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()source public 

__construct( Cake\ORM\Table $table )

Constructor.

Parameters

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

_belongsToMany()source protected 

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

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[]
An array of built entities.

Throws

BadMethodCallException
InvalidArgumentException
RuntimeException

_buildPropertyMap()source protected 

_buildPropertyMap( array $data , array $options )

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()source protected 

_loadAssociatedByIds( Cake\ORM\Association $assoc , array $ids )

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[]
An array of entities.

_loadBelongsToMany()source protected deprecated 

_loadBelongsToMany( Cake\ORM\Association $assoc , array $ids )

Loads a list of belongs to many from ids.

Deprecated

Use _loadAssociatedByIds()

Parameters

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

Returns

Cake\Datasource\EntityInterface[]
An array of entities.

_marshalAssociation()source protected 

_marshalAssociation( Cake\ORM\Association $assoc , array $value , array $options )

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()source protected 

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

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()source protected 

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

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()source protected 

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

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[]
An array of entities

_prepareDataAndOptions()source protected 

_prepareDataAndOptions( array $data , array $options )

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.

_validate()source protected 

_validate( array $data , array $options , boolean $isNew )

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.

Returns

array
The list of validation errors.

Throws

RuntimeException
If no validator can be created.

many()source public 

many( array $data , array $options = [] )

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[]
An array of hydrated records.

See

\Cake\ORM\Table::newEntities()
\Cake\ORM\Entity::$_accessible

merge()source public 

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

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

See

\Cake\ORM\Entity::$_accessible

mergeMany()source public 

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

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

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[]

See

\Cake\ORM\Entity::$_accessible

one()source public 

one( array $data , array $options = [] )

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 optional []
List of options

Returns

Cake\Datasource\EntityInterface

See

\Cake\ORM\Table::newEntity()
\Cake\ORM\Entity::$_accessible

Methods used from Cake\ORM\AssociationsNormalizerTrait

_normalizeAssociations()source protected 

_normalizeAssociations( array $associations )

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

Properties detail

$_tablesource

protected Cake\ORM\Table

The table instance this marshaller is for.

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.6/class-Cake.ORM.Marshaller.html