PHANTOM
🇮🇳 IN
Skip to content

Add nested array format support for marshalling associations#19122

Open
dereuromark wants to merge 1 commit into5.nextfrom
5.next-association-conventions
Open

Add nested array format support for marshalling associations#19122
dereuromark wants to merge 1 commit into5.nextfrom
5.next-association-conventions

Conversation

@dereuromark
Copy link
Member

@dereuromark dereuromark commented Dec 13, 2025

Summary

  • Allow the same nested array format as contain() for marshalling associations
  • Uses CakePHP naming conventions to distinguish associations from options (no hardcoded list to maintain)

This enables writing:

$table->newEntity($data, [
    'associated' => [
        'Articles' => ['Comments', 'Tags', 'onlyIds' => true],
    ],
]);

Instead of requiring the explicit associated key at every level:

$table->newEntity($data, [
    'associated' => [
        'Articles' => [
            'associated' => ['Comments', 'Tags'],
            'onlyIds' => true,
        ],
    ],
]);

How it works

Uses CakePHP naming conventions to detect associations vs options:

  • Association names start with uppercase (CamelCase): Users, Articles
  • Option keys start with lowercase (camelCase): onlyIds, conditions
  • Special data keys start with underscore: _joinData, _ids

This avoids maintaining a hardcoded list of known option keys that would need updating whenever new options are added.

Related to #18988 (6.x version).

If we wanted to harden this, we could go with the alternative option(s) in that 6.x PR (e.g. _options key for any custom options that are not assoc aliases), but then it couldnt be used in 5.next yet.

Allow the same nested array format as contain() for marshalling:
- Dot notation: ['First.Second']
- Nested arrays: ['First' => ['Second', 'Third']]
- Mixed with options: ['First' => ['Second', 'onlyIds' => true]]

Uses CakePHP naming conventions to distinguish associations from options:
- Association names start with uppercase (CamelCase): Users, Articles
- Option keys start with lowercase (camelCase): onlyIds, conditions
- Special data keys start with underscore: _joinData, _ids

This approach avoids maintaining a hardcoded list of known option keys.
@dereuromark dereuromark added this to the 5.3.0 milestone Dec 13, 2025
@ADmad
Copy link
Member

ADmad commented Dec 30, 2025

While this syncs the array format used for contain() and as (new|patch)Entity(), I personally prefer the use of associated to specify the association names, instead of mixing association names with numeric keys and options with string keys at the same level.

@dereuromark
Copy link
Member Author

dereuromark commented Dec 31, 2025

Isnt "associated" a bit too verbose for a bunch of nested ones?
Fo me this seems super hard to work with.

@jamisonbryant
Copy link
Contributor

Isnt "associated" a bit too verbose for a bunch of nested ones?

How about load? We already use this nomenclature a bit, e.g. loadInto().

@dereuromark
Copy link
Member Author

I dont quite follow.
The topic was about the keys inside the arrays. To make it more user friendly in general to have nesting available.

@othercorey othercorey modified the milestones: 5.3.0, 5.3.1, 5.4.0 Jan 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants