Fr3nch13/CakePHP Utilities

Marshaller
in package
uses AssociationsNormalizerTrait

Contains logic to convert array data into entities.

Useful when converting request data into entities.

Tags
see
Table::newEntity()
see
Table::newEntities()
see
Table::patchEntity()
see
Table::patchEntities()

Table of Contents

Properties

$_table  : Table
The table instance this marshaller is for.

Methods

__construct()  : mixed
Constructor.
many()  : array<string|int, EntityInterface>
Hydrate many entities and their associated data.
merge()  : 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.
mergeMany()  : array<string|int, 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.
one()  : EntityInterface
Hydrate one entity and its associated data.
_belongsToMany()  : array<string|int, EntityInterface>
Marshals data for belongsToMany associations.
_buildPropertyMap()  : array<string|int, mixed>
Build the map of property => marshalling callable.
_loadAssociatedByIds()  : array<string|int, EntityInterface>
Loads a list of belongs to many from ids.
_marshalAssociation()  : EntityInterface|array<string|int, EntityInterface>|null
Create a new sub-marshaller and marshal the associated data.
_mergeAssociation()  : EntityInterface|array<string|int, EntityInterface>|null
Creates a new sub-marshaller and merges the associated data.
_mergeBelongsToMany()  : array<string|int, EntityInterface>
Creates a new sub-marshaller and merges the associated data for a BelongstoMany association.
_mergeJoinData()  : array<string|int, EntityInterface>
Merge the special _joinData property into the entity set.
_normalizeAssociations()  : array<string|int, mixed>
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()  : array<string|int, mixed>
Returns data and options prepared to validate and marshall.
_validate()  : array<string|int, mixed>
Returns the validation errors for a data set based on the passed options
dispatchAfterMarshal()  : void
dispatch Model.afterMarshal event.

Properties

$_table

The table instance this marshaller is for.

protected Table $_table

Methods

__construct()

Constructor.

public __construct(Table $table) : mixed
Parameters
$table : Table

The table this marshaller is for.

many()

Hydrate many entities and their associated data.

public many(array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : array<string|int, EntityInterface>

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.
  • fields: An allowed list 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
$data : array<string|int, mixed>

The data to hydrate.

$options : array<string, mixed> = []

List of options

Tags
see
Table::newEntities()
see
Entity::$_accessible
Return values
array<string|int, EntityInterface> —

An array of hydrated records.

merge()

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.

public merge(EntityInterface $entity, array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : EntityInterface

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 to validate data before hydrating the entities. Can also be set to a string to use a specific validator. Defaults to true/default.
  • fields: An allowed list 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
$entity : EntityInterface

the entity that will get the data merged in

$data : array<string|int, mixed>

key value list of fields to be merged into the entity

$options : array<string, mixed> = []

List of options.

Tags
see
Entity::$_accessible
Return values
EntityInterface

mergeMany()

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.

public mergeMany(iterable<string|int, EntityInterface> $entities, array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : array<string|int, EntityInterface>

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 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.
  • fields: An allowed list 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
$entities : iterable<string|int, EntityInterface>

the entities that will get the data merged in

$data : array<string|int, mixed>

list of arrays to be merged into the entities

$options : array<string, mixed> = []

List of options.

Tags
see
Entity::$_accessible
psalm-suppress

NullArrayOffset

Return values
array<string|int, EntityInterface>

one()

Hydrate one entity and its associated data.

public one(array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : EntityInterface

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.
  • fields: An allowed list 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]]
]);

$result = $marshaller->one($data, [
  'associated' => [
    'Tags' => ['accessibleFields' => ['*' => true]]
  ]
]);
Parameters
$data : array<string|int, mixed>

The data to hydrate.

$options : array<string, mixed> = []

List of options

Tags
see
Table::newEntity()
see
Entity::$_accessible
Return values
EntityInterface

_belongsToMany()

Marshals data for belongsToMany associations.

protected _belongsToMany(BelongsToMany $assoc, array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : array<string|int, EntityInterface>

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

Parameters
$assoc : BelongsToMany

The association to marshal.

$data : array<string|int, mixed>

The data to convert into entities.

$options : array<string, mixed> = []

List of options.

Tags
throws
BadMethodCallException
throws
InvalidArgumentException
throws
RuntimeException
Return values
array<string|int, EntityInterface> —

An array of built entities.

_buildPropertyMap()

Build the map of property => marshalling callable.

protected _buildPropertyMap(array<string|int, mixed> $data, array<string, mixed> $options) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

The data being marshalled.

$options : array<string, mixed>

List of options containing the 'associated' key.

Tags
throws
InvalidArgumentException

When associations do not exist.

Return values
array<string|int, mixed>

_loadAssociatedByIds()

Loads a list of belongs to many from ids.

protected _loadAssociatedByIds(Association $assoc, array<string|int, mixed> $ids) : array<string|int, EntityInterface>
Parameters
$assoc : Association

The association class for the belongsToMany association.

$ids : array<string|int, mixed>

The list of ids to load.

Return values
array<string|int, EntityInterface> —

An array of entities.

_marshalAssociation()

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

protected _marshalAssociation(Association $assoc, mixed $value, array<string, mixed> $options) : EntityInterface|array<string|int, EntityInterface>|null
Parameters
$assoc : Association

The association to marshall

$value : mixed

The data to hydrate. If not an array, this method will return null.

$options : array<string, mixed>

List of options.

Return values
EntityInterface|array<string|int, EntityInterface>|null

_mergeAssociation()

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

protected _mergeAssociation(EntityInterface|array<string|int, EntityInterface> $original, Association $assoc, mixed $value, array<string, mixed> $options) : EntityInterface|array<string|int, EntityInterface>|null
Parameters
$original : EntityInterface|array<string|int, EntityInterface>

The original entity

$assoc : Association

The association to merge

$value : mixed

The array of data to hydrate. If not an array, this method will return null.

$options : array<string, mixed>

List of options.

Return values
EntityInterface|array<string|int, EntityInterface>|null

_mergeBelongsToMany()

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

protected _mergeBelongsToMany(array<string|int, EntityInterface> $original, BelongsToMany $assoc, array<string|int, mixed> $value, array<string, mixed> $options) : array<string|int, EntityInterface>
Parameters
$original : array<string|int, EntityInterface>

The original entities list.

$assoc : BelongsToMany

The association to marshall

$value : array<string|int, mixed>

The data to hydrate

$options : array<string, mixed>

List of options.

Return values
array<string|int, EntityInterface>

_mergeJoinData()

Merge the special _joinData property into the entity set.

protected _mergeJoinData(array<string|int, EntityInterface> $original, BelongsToMany $assoc, array<string|int, mixed> $value, array<string, mixed> $options) : array<string|int, EntityInterface>
Parameters
$original : array<string|int, EntityInterface>

The original entities list.

$assoc : BelongsToMany

The association to marshall

$value : array<string|int, mixed>

The data to hydrate

$options : array<string, mixed>

List of options.

Return values
array<string|int, EntityInterface> —

An array of entities

_normalizeAssociations()

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

protected _normalizeAssociations(array<string|int, mixed>|string $associations) : array<string|int, mixed>
Parameters
$associations : array<string|int, mixed>|string

The array of included associations.

Return values
array<string|int, mixed> —

An array having dot notation transformed into nested arrays

_prepareDataAndOptions()

Returns data and options prepared to validate and marshall.

protected _prepareDataAndOptions(array<string|int, mixed> $data, array<string, mixed> $options) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

The data to prepare.

$options : array<string, mixed>

The options passed to this marshaller.

Return values
array<string|int, mixed> —

An array containing prepared data and options.

_validate()

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

protected _validate(array<string|int, mixed> $data, array<string, mixed> $options, bool $isNew) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

The data to validate.

$options : array<string, mixed>

The options passed to this marshaller.

$isNew : bool

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

Tags
throws
RuntimeException

If no validator can be created.

Return values
array<string|int, mixed> —

The list of validation errors.

dispatchAfterMarshal()

dispatch Model.afterMarshal event.

protected dispatchAfterMarshal(EntityInterface $entity, array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : void
Parameters
$entity : EntityInterface

The entity that was marshaled.

$data : array<string|int, mixed>

readOnly $data to use.

$options : array<string, mixed> = []

List of options that are readOnly.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results