07f3f273cd
## Description Adds collection `refresh` hooks to override the default `refresh` operation behavior.
356 lines
11 KiB
Plaintext
356 lines
11 KiB
Plaintext
---
|
|
title: Collection Hooks
|
|
label: Collections
|
|
order: 20
|
|
desc: You can add hooks to any Collection, several hook types are available including beforeChange, afterRead, afterDelete and more.
|
|
keywords: hooks, collections, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Collections feature the ability to define the following hooks:
|
|
|
|
- [beforeOperation](#beforeoperation)
|
|
- [beforeValidate](#beforevalidate)
|
|
- [beforeChange](#beforechange)
|
|
- [afterChange](#afterchange)
|
|
- [beforeRead](#beforeread)
|
|
- [afterRead](#afterread)
|
|
- [beforeDelete](#beforedelete)
|
|
- [afterDelete](#afterdelete)
|
|
- [afterOperation](#afteroperation)
|
|
|
|
Additionally, `auth`-enabled collections feature the following hooks:
|
|
|
|
- [beforeLogin](#beforelogin)
|
|
- [afterLogin](#afterlogin)
|
|
- [afterLogout](#afterlogout)
|
|
- [afterRefresh](#afterrefresh)
|
|
- [afterMe](#afterme)
|
|
- [afterForgotPassword](#afterforgotpassword)
|
|
- [refresh](#refresh)
|
|
- [me](#me)
|
|
|
|
## Config
|
|
|
|
All collection Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.
|
|
|
|
`collections/exampleHooks.js`
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload';
|
|
|
|
export const ExampleHooks: CollectionConfig = {
|
|
slug: 'example-hooks',
|
|
fields: [
|
|
{ name: 'name', type: 'text'},
|
|
],
|
|
hooks: {
|
|
beforeOperation: [(args) => {...}],
|
|
beforeValidate: [(args) => {...}],
|
|
beforeDelete: [(args) => {...}],
|
|
beforeChange: [(args) => {...}],
|
|
beforeRead: [(args) => {...}],
|
|
afterChange: [(args) => {...}],
|
|
afterRead: [(args) => {...}],
|
|
afterDelete: [(args) => {...}],
|
|
afterOperation: [(args) => {...}],
|
|
|
|
// Auth-enabled hooks
|
|
beforeLogin: [(args) => {...}],
|
|
afterLogin: [(args) => {...}],
|
|
afterLogout: [(args) => {...}],
|
|
afterRefresh: [(args) => {...}],
|
|
afterMe: [(args) => {...}],
|
|
afterForgotPassword: [(args) => {...}],
|
|
refresh: [(args) => {...}],
|
|
me: [(args) => {...}],
|
|
},
|
|
}
|
|
```
|
|
|
|
### beforeOperation
|
|
|
|
The `beforeOperation` hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.
|
|
|
|
Available Collection operations include `create`, `read`, `update`, `delete`, `login`, `refresh`, and `forgotPassword`.
|
|
|
|
```ts
|
|
import type { CollectionBeforeOperationHook } from 'payload'
|
|
|
|
const beforeOperationHook: CollectionBeforeOperationHook = async ({
|
|
args, // original arguments passed into the operation
|
|
operation, // name of the operation
|
|
req, // full Request object
|
|
}) => {
|
|
return args // return modified operation arguments as necessary
|
|
}
|
|
```
|
|
|
|
### beforeValidate
|
|
|
|
Runs before the `create` and `update` operations. This hook allows you to add or format data before the incoming data is validated server-side.
|
|
|
|
Please do note that this does not run before the client-side validation. If you added a `validate` function, this would be the lifecycle:
|
|
|
|
1. `validate` runs on the client
|
|
2. if successful, `beforeValidate` runs on the server
|
|
3. `validate` runs on the server
|
|
|
|
```ts
|
|
import type { CollectionBeforeValidateHook } from 'payload'
|
|
|
|
const beforeValidateHook: CollectionBeforeValidateHook = async ({
|
|
data, // incoming data to update or create with
|
|
req, // full Request object
|
|
operation, // name of the operation ie. 'create', 'update'
|
|
originalDoc, // original document
|
|
}) => {
|
|
return data // Return data to either create or update a document with
|
|
}
|
|
```
|
|
|
|
### beforeChange
|
|
|
|
Immediately following validation, `beforeChange` hooks will run within `create` and `update` operations. 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.
|
|
|
|
```ts
|
|
import type { CollectionBeforeChangeHook } from 'payload'
|
|
|
|
const beforeChangeHook: CollectionBeforeChangeHook = async ({
|
|
data, // incoming data to update or create with
|
|
req, // full Request object
|
|
operation, // name of the operation ie. 'create', 'update'
|
|
originalDoc, // original document
|
|
}) => {
|
|
return data // Return data to either create or update a document with
|
|
}
|
|
```
|
|
|
|
### 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.
|
|
|
|
```ts
|
|
import type { CollectionAfterChangeHook } from 'payload'
|
|
|
|
const afterChangeHook: CollectionAfterChangeHook = async ({
|
|
doc, // full document data
|
|
req, // full Request object
|
|
previousDoc, // document data before updating the collection
|
|
operation, // name of the operation ie. 'create', 'update'
|
|
}) => {
|
|
return doc
|
|
}
|
|
```
|
|
|
|
### beforeRead
|
|
|
|
Runs before `find` and `findByID` operations are transformed for output by `afterRead`. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the `doc` argument.
|
|
|
|
```ts
|
|
import type { CollectionBeforeReadHook } from 'payload'
|
|
|
|
const beforeReadHook: CollectionBeforeReadHook = async ({
|
|
doc, // full document data
|
|
req, // full Request object
|
|
query, // JSON formatted query
|
|
}) => {
|
|
return doc
|
|
}
|
|
```
|
|
|
|
### afterRead
|
|
|
|
Runs as the last step before documents are returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
|
|
|
|
```ts
|
|
import type { CollectionAfterReadHook } from 'payload'
|
|
|
|
const afterReadHook: CollectionAfterReadHook = async ({
|
|
doc, // full document data
|
|
req, // full Request object
|
|
query, // JSON formatted query
|
|
findMany, // boolean to denote if this hook is running against finding one, or finding many
|
|
}) => {
|
|
return doc
|
|
}
|
|
```
|
|
|
|
### beforeDelete
|
|
|
|
Runs before the `delete` operation. Returned values are discarded.
|
|
|
|
```ts
|
|
import type { CollectionBeforeDeleteHook } from 'payload';
|
|
|
|
const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
|
|
req, // full Request object
|
|
id, // id of document to delete
|
|
}) => {...}
|
|
```
|
|
|
|
### afterDelete
|
|
|
|
Runs immediately after the `delete` operation removes records from the database. Returned values are discarded.
|
|
|
|
```ts
|
|
import type { CollectionAfterDeleteHook } from 'payload';
|
|
|
|
const afterDeleteHook: CollectionAfterDeleteHook = async ({
|
|
req, // full Request object
|
|
id, // id of document to delete
|
|
doc, // deleted document
|
|
}) => {...}
|
|
```
|
|
|
|
### afterOperation
|
|
|
|
The `afterOperation` hook can be used to modify the result of operations or execute side-effects that run after an operation has completed.
|
|
|
|
Available Collection operations include `create`, `find`, `findByID`, `update`, `updateByID`, `delete`, `deleteByID`, `login`, `refresh`, and `forgotPassword`.
|
|
|
|
```ts
|
|
import type { CollectionAfterOperationHook } from 'payload'
|
|
|
|
const afterOperationHook: CollectionAfterOperationHook = async ({
|
|
args, // arguments passed into the operation
|
|
operation, // name of the operation
|
|
req, // full Request object
|
|
result, // the result of the operation, before modifications
|
|
}) => {
|
|
return result // return modified result as necessary
|
|
}
|
|
```
|
|
|
|
### beforeLogin
|
|
|
|
For auth-enabled Collections, this hook runs during `login` operations where a user with the provided credentials exist, but before a token is generated and added to the response. You can optionally modify the user that is returned, or throw an error in order to deny the login operation.
|
|
|
|
```ts
|
|
import type { CollectionBeforeLoginHook } from 'payload'
|
|
|
|
const beforeLoginHook: CollectionBeforeLoginHook = async ({
|
|
req, // full Request object
|
|
user, // user being logged in
|
|
}) => {
|
|
return user
|
|
}
|
|
```
|
|
|
|
### afterLogin
|
|
|
|
For auth-enabled Collections, this hook runs after successful `login` operations. You can optionally modify the user that is returned.
|
|
|
|
```ts
|
|
import type { CollectionAfterLoginHook } from 'payload';
|
|
|
|
const afterLoginHook: CollectionAfterLoginHook = async ({
|
|
req, // full Request object
|
|
user, // user that was logged in
|
|
token, // user token
|
|
}) => {...}
|
|
```
|
|
|
|
### afterLogout
|
|
|
|
For auth-enabled Collections, this hook runs after `logout` operations.
|
|
|
|
```ts
|
|
import type { CollectionAfterLogoutHook } from 'payload';
|
|
|
|
const afterLogoutHook: CollectionAfterLogoutHook = async ({
|
|
req, // full Request object
|
|
}) => {...}
|
|
```
|
|
|
|
### afterRefresh
|
|
|
|
For auth-enabled Collections, this hook runs after `refresh` operations.
|
|
|
|
```ts
|
|
import type { CollectionAfterRefreshHook } from 'payload';
|
|
|
|
const afterRefreshHook: CollectionAfterRefreshHook = async ({
|
|
req, // full Request object
|
|
res, // full Response object
|
|
token, // newly refreshed user token
|
|
}) => {...}
|
|
```
|
|
|
|
### afterMe
|
|
|
|
For auth-enabled Collections, this hook runs after `me` operations.
|
|
|
|
```ts
|
|
import type { CollectionAfterMeHook } from 'payload';
|
|
|
|
const afterMeHook: CollectionAfterMeHook = async ({
|
|
req, // full Request object
|
|
response, // response to return
|
|
}) => {...}
|
|
```
|
|
|
|
### afterForgotPassword
|
|
|
|
For auth-enabled Collections, this hook runs after successful `forgotPassword` operations. Returned values are discarded.
|
|
|
|
```ts
|
|
import type { CollectionAfterForgotPasswordHook } from 'payload'
|
|
|
|
const afterForgotPasswordHook: CollectionAfterForgotPasswordHook = async ({
|
|
args, // arguments passed into the operation
|
|
context,
|
|
collection, // The collection which this hook is being run on
|
|
}) => {...}
|
|
```
|
|
|
|
### refresh
|
|
|
|
For auth-enabled Collections, this hook allows you to optionally replace the default behavior of the `refresh` operation with your own. If you optionally return a value from your hook, the operation will not perform its own logic and continue.
|
|
|
|
```ts
|
|
import type { CollectionRefreshHook } from 'payload'
|
|
|
|
const myRefreshHook: CollectionRefreshHook = async ({
|
|
args, // arguments passed into the `refresh` operation
|
|
user, // the user as queried from the database
|
|
}) => {...}
|
|
```
|
|
|
|
### me
|
|
|
|
For auth-enabled Collections, this hook allows you to optionally replace the default behavior of the `me` operation with your own. If you optionally return a value from your hook, the operation will not perform its own logic and continue.
|
|
|
|
```ts
|
|
import type { CollectionMeHook } from 'payload'
|
|
|
|
const meHook: CollectionMeHook = async ({
|
|
args, // arguments passed into the `me` operation
|
|
user, // the user as queried from the database
|
|
}) => {...}
|
|
```
|
|
|
|
## TypeScript
|
|
|
|
Payload exports a type for each Collection hook which can be accessed as follows:
|
|
|
|
```ts
|
|
import type {
|
|
CollectionBeforeOperationHook,
|
|
CollectionBeforeValidateHook,
|
|
CollectionBeforeChangeHook,
|
|
CollectionAfterChangeHook,
|
|
CollectionAfterReadHook,
|
|
CollectionBeforeReadHook,
|
|
CollectionBeforeDeleteHook,
|
|
CollectionAfterDeleteHook,
|
|
CollectionBeforeLoginHook,
|
|
CollectionAfterLoginHook,
|
|
CollectionAfterLogoutHook,
|
|
CollectionAfterRefreshHook,
|
|
CollectionAfterMeHook,
|
|
CollectionAfterForgotPasswordHook,
|
|
CollectionRefreshHook,
|
|
CollectionMeHook,
|
|
} from 'payload'
|
|
```
|