Class Marshaller
Contains logic to convert array data into entities.
Useful when converting request data into entities.
- Cake\ORM\Marshaller uses Cake\ORM\AssociationsNormalizerTrait
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
-
$_tableprotectedThe 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. -
_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 -
many() public
Hydrate many entities and their associated data. -
merge() public
Merges
$datainto$entityand 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
$datainto each of the entities in$entitiesand 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
_belongsToMany() 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
Throws
InvalidArgumentException
RuntimeException
_buildPropertyMap() 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
Throws
When associations do not exist.
_loadAssociatedByIds() 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
_loadBelongsToMany() protected deprecated ¶
_loadBelongsToMany( Cake\ORM\Association $assoc , array $ids )
Loads a list of belongs to many from ids.
Deprecated
Parameters
-
Cake\ORM\Association$assoc - The association class for the belongsToMany association.
- array $ids
- The list of ids to load.
Returns
_marshalAssociation() 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
_mergeAssociation() 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
_mergeBelongsToMany() 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
_mergeJoinData() 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
_prepareDataAndOptions() 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
An array containing prepared data and options.
_validate() 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
The list of validation errors.
Throws
If no validator can be created.
many() 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
See
\Cake\ORM\Entity::$_accessible
merge() 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
See
mergeMany() 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
See
one() 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
See
\Cake\ORM\Entity::$_accessible
Methods used from Cake\ORM\AssociationsNormalizerTrait
_normalizeAssociations() 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
An array having dot notation transformed into nested arrays