From f75419402ddbbdeaafc69c1fbd6adf383103704f Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 26 Jun 2025 12:37:15 +0200 Subject: [PATCH 1/2] Documentation for the `matchOn` method --- resources/js/Pages/merging-props.jsx | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index e0a69084..a5047d4a 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -1,4 +1,4 @@ -import { A, Code, H1, H2, P, Strong, TabbedCode } from '@/Components' +import { A, Code, CodeBlock, H1, H2, Notice, P, TabbedCode } from '@/Components' import dedent from 'dedent-js' export const meta = { @@ -6,6 +6,8 @@ export const meta = { links: [ { url: '#top', name: 'Introduction' }, { url: '#server-side', name: 'Server side' }, + { url: '#client-side', name: 'Client side' }, + { url: '#combining-with-deferred-props', name: 'Deferred props' }, { url: '#resetting-props', name: 'Resetting props' }, ], } @@ -71,15 +73,30 @@ export default function () { ]} /> +

+ You may chain the matchOn method to control how data is merged. This allows you to specify one or more keys to determine how existing items should be matched and updated. +

+ Inertia::deepMerge($users)->matchOn('data.id'), + ]); + `} + /> +

+ In this example, Inertia will iterate over the users.data array and attempt to match each item based on its id field. If an item with a matching id already exists, it will be replaced. Otherwise, the new item will be added to the array. +

+ + You may also pass an array of keys to matchOn to specify multiple keys for matching. + +

Client side

On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will append the response to the current prop value. If it's an object, it will merge the response with the current prop value. If you have opted to deepMerge, Inertia ensures a deep merge of the entire structure.

-

- Of note: During the merging process, if the value is an array, the incoming items will be{' '} - appended to the existing array, not merged by index. -

+

Combining with deferred props

You can also combine deferred props with mergeable props to defer the loading of the prop and ultimately mark it as mergeable once it's loaded. From e68971cb588e1ee9f38f6eca9aa83f3f54cd4958 Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 26 Jun 2025 12:46:00 +0200 Subject: [PATCH 2/2] Bring back default behaviour notice --- resources/js/Pages/merging-props.jsx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index a5047d4a..1b429cf1 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -74,7 +74,9 @@ export default function () { />

- You may chain the matchOn method to control how data is merged. This allows you to specify one or more keys to determine how existing items should be matched and updated. + During the merging process, if the value is an array, the incoming items will be{' '} + appended to the existing array, not merged by index. However, you may chain the{' '} + matchOn method to determine how existing items should be matched and updated.

- In this example, Inertia will iterate over the users.data array and attempt to match each item based on its id field. If an item with a matching id already exists, it will be replaced. Otherwise, the new item will be added to the array. + In this example, Inertia will iterate over the users.data array and attempt to{' '} + match each item by its id field. If a match is found, the existing item will be replaced. + If no match is found, the new item will be appended.

You may also pass an array of keys to matchOn to specify multiple keys for matching.