Class Marshaller
Contains logic to convert array data into entities.
Useful when converting request data into entities.
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
-
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 $assoc, array $data, array $options = []): array
Marshals data for belongsToMany associations.
Builds the related entities and handles the special casing for junction table entities.
Parameters
-
Cake\ORM\Association
$assoc The association to marshal.
-
array
$data The data to convert into entities.
-
array
$options optional List of options.
Returns
array
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): array
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
_loadBelongsToMany() ¶ protected
_loadBelongsToMany(Cake\ORM\Association $assoc, array $ids): array
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
_marshalAssociation() ¶ protected
_marshalAssociation(Cake\ORM\Association $assoc, array $value, array $options): mixed
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
mixed
_mergeAssociation() ¶ protected
_mergeAssociation(Cake\Datasource\EntityInterface $original, Cake\ORM\Association $assoc, array $value, array $options): mixed
Creates a new sub-marshaller and merges the associated data.
Parameters
-
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
mixed
_mergeBelongsToMany() ¶ protected
_mergeBelongsToMany(Cake\Datasource\EntityInterface $original, Cake\ORM\Association $assoc, array $value, array $options): array
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
_mergeJoinData() ¶ protected
_mergeJoinData(Cake\Datasource\EntityInterface $original, Cake\ORM\Association $assoc, array $value, array $options): array
Merge the special _joinData property into the entity set.
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
_normalizeAssociations() ¶ protected
_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
_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.
many() ¶ public
many(array $data, array $options = []): array
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
array
See Also
\Cake\ORM\Entity::$_accessible
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
See Also
mergeMany() ¶ public
mergeMany(array|Traversable $entities, array $data, array $options = []): array
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|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
array
See Also
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.
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 Also
\Cake\ORM\Entity::$_accessible