Skip to content

docs: beforeChange and beforeValidate updates #13826

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: beforeChange and beforeValidate updates #13826

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 37 additions & 3 deletions docs/hooks/collections.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,17 +114,40 @@ The following arguments are provided to the `beforeValidate` hook:
| **`context`** | Custom context passed between Hooks. [More details](./context). |
| **`data`** | The incoming data passed through the operation. |
| **`operation`** | The name of the operation that this hook is running within. |
| **`originalDoc`** | The Document before changes are applied. |
| **`originalDoc`** | The full document before changes are applied. Present on updates; undefined on creates. Use this to read the document id and any unchanged fields. |
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |

**Why isn’t id in data?**

`data` only represents the delta you’re saving. Read `originalDoc.id` during updates, and prefer `afterChange` if you need the `id` during creates

<Banner type="warning">
On update operations, data contains only the fields being changed. It may omit
id and any unchanged fields. Use originalDoc to read existing values. On
create, data is the new submission and the document id is not yet available at
this stage.
</Banner>

### beforeChange

Immediately before validation, beforeChange hooks will run during create and update operations. At this stage, the data should be treated as unvalidated user input. There is no guarantee that required fields exist or that fields are in the correct format. As such, using this data for side effects requires manual validation. You can optionally modify the shape of the data to be saved.

```ts
import type { CollectionBeforeChangeHook } from 'payload'

const beforeChangeHook: CollectionBeforeChangeHook = async ({ data }) => {
export const requireTitleOnUpdate: CollectionBeforeChangeHook = async ({
data, // Partial<T> — changed fields only
originalDoc, // Full doc before changes (defined on update)
operation, // 'create' | 'update'
}) => {
// Need the id? Don't expect it in `data`.
const id = operation === 'update' ? originalDoc.id : undefined

// Example: enforce that title cannot be cleared on update
if (operation === 'update' && 'title' in (data ?? {}) && !data.title) {
throw new Error(`Document ${id} must have a title`)
}

return data
}
```
Expand All @@ -137,9 +160,20 @@ The following arguments are provided to the `beforeChange` hook:
| **`context`** | Custom context passed between hooks. [More details](./context). |
| **`data`** | The incoming data passed through the operation. |
| **`operation`** | The name of the operation that this hook is running within. |
| **`originalDoc`** | The Document before changes are applied. |
| **`originalDoc`** | The full document before changes are applied. Present on updates; undefined on creates. Use this to read the document id and any unchanged fields. |
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |

**Why isn’t id in data?**

`data` only represents the delta you’re saving. Read `originalDoc.id` during updates, and prefer `afterChange` if you need the `id` during creates

<Banner type="warning">
On update operations, data contains only the fields being changed. It may omit
id and any unchanged fields. Use originalDoc to read existing values. On
create, data is the new submission and the document id is not yet available at
this stage.
</Banner>

### afterChange

After a document is created or updated, the `afterChange` hook runs. This hook is helpful to recalculate statistics such as total sales within a global, syncing user profile changes to a CRM, and more.
Expand Down
18 changes: 16 additions & 2 deletions docs/hooks/globals.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,9 +103,16 @@ The following arguments are provided to the `beforeValidate` hook:
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
| **`context`** | Custom context passed between Hooks. [More details](./context). |
| **`data`** | The incoming data passed through the operation. |
| **`originalDoc`** | The Document before changes are applied. |
| **`originalDoc`** | The full document before changes are applied. Present on updates; undefined on creates. Use this to read the document id and any unchanged fields. |
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |

<Banner type="warning">
On update operations, data contains only the fields being changed. It may omit
id and any unchanged fields. Use originalDoc to read existing values. On
create, data is the new submission and the document id is not yet available at
this stage.
</Banner>

### beforeChange

Immediately following validation, `beforeChange` hooks will run within the `update` operation. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.
Expand All @@ -129,9 +136,16 @@ The following arguments are provided to the `beforeChange` hook:
| **`global`** | The [Global](../configuration/globals) in which this Hook is running against. |
| **`context`** | Custom context passed between hooks. [More details](./context). |
| **`data`** | The incoming data passed through the operation. |
| **`originalDoc`** | The Document before changes are applied. |
| **`originalDoc`** | The full document before changes are applied. Present on updates; undefined on creates. Use this to read the document id and any unchanged fields. |
| **`req`** | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |

<Banner type="warning">
On update operations, data contains only the fields being changed. It may omit
id and any unchanged fields. Use originalDoc to read existing values. On
create, data is the new submission and the document id is not yet available at
this stage.
</Banner>

### afterChange

After a global is updated, the `afterChange` hook runs. Use this hook to purge caches of your applications, sync site data to CRMs, and more.
Expand Down