From 5a2b310c6393bcef9b97040d3c7b476f5bdf07b8 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Mon, 23 Feb 2026 19:10:44 -0300 Subject: [PATCH 1/2] docs: Add missing docs on how to use `UserProfile` callbacks --- .../03-working-with-users.md | 30 ++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/06-concepts/11-authentication/03-working-with-users.md b/docs/06-concepts/11-authentication/03-working-with-users.md index 7f3e935a..57df77a9 100644 --- a/docs/06-concepts/11-authentication/03-working-with-users.md +++ b/docs/06-concepts/11-authentication/03-working-with-users.md @@ -107,6 +107,34 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation. +### User profile callbacks + +You can react when a user profile is created or updated by using the `UserProfileConfig` callbacks. Configure them when initializing auth services on the `pod` object via the `userProfileConfig` parameter. + +:::warning +All callbacks receive a `transaction` parameter that should be used on all database operations performed inside the callback. Failing to pass the transaction might lead to entries not being found or changes not being rolled back together. +::: + +| Callback | When | Purpose | +| -------- | ---- | ------- | +| `onBeforeUserProfileCreated` | Before a profile is created | Receive and return `UserProfileData` to modify defaults (user name, full name, email). | +| `onAfterUserProfileCreated` | After a profile is created | Run logic that depends on the new profile (e.g. related data, default image). | +| `onBeforeUserProfileUpdated` | Before a profile is updated (name, full name, or picture) | Receive and return `UserProfileData` to enforce rules or transform values. | +| `onAfterUserProfileUpdated` | After a profile is updated | Sync related data or trigger side effects. | + +Example using `onAfterUserProfileCreated`: + +```dart +pod.initializeAuthServices( + ... + userProfileConfig: UserProfileConfig( + onAfterUserProfileCreated: (session, userProfile, {required transaction}) async { + // Do something with the new profile (e.g. create related data, set default image) + }, + ), +); +``` + ### Accessing user profiles from the app To access the user profile from your Flutter app, you can use the `userProfileInfo` endpoint that is included in the authentication module: @@ -175,7 +203,7 @@ class UserProfileEditEndpoint extends UserProfileEditBaseEndpoint { ### Setting a default user image -When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object. +When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, you can set a default user image using the `onAfterUserProfileCreated` callback in `UserProfileConfig` (see [User profile callbacks](#user-profile-callbacks) for the full set of callbacks). ```dart pod.initializeAuthServices( From c3dbdc2786ccb38bba4248ad0c485024e9a1521c Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Mon, 23 Feb 2026 19:10:58 -0300 Subject: [PATCH 2/2] chore: Copy changes to versioned docs --- .../03-working-with-users.md | 30 ++++++++++++++++++- .../03-working-with-users.md | 30 ++++++++++++++++++- .../03-working-with-users.md | 30 ++++++++++++++++++- .../03-working-with-users.md | 30 ++++++++++++++++++- 4 files changed, 116 insertions(+), 4 deletions(-) diff --git a/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md index 7f3e935a..57df77a9 100644 --- a/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.0.0/06-concepts/11-authentication/03-working-with-users.md @@ -107,6 +107,34 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation. +### User profile callbacks + +You can react when a user profile is created or updated by using the `UserProfileConfig` callbacks. Configure them when initializing auth services on the `pod` object via the `userProfileConfig` parameter. + +:::warning +All callbacks receive a `transaction` parameter that should be used on all database operations performed inside the callback. Failing to pass the transaction might lead to entries not being found or changes not being rolled back together. +::: + +| Callback | When | Purpose | +| -------- | ---- | ------- | +| `onBeforeUserProfileCreated` | Before a profile is created | Receive and return `UserProfileData` to modify defaults (user name, full name, email). | +| `onAfterUserProfileCreated` | After a profile is created | Run logic that depends on the new profile (e.g. related data, default image). | +| `onBeforeUserProfileUpdated` | Before a profile is updated (name, full name, or picture) | Receive and return `UserProfileData` to enforce rules or transform values. | +| `onAfterUserProfileUpdated` | After a profile is updated | Sync related data or trigger side effects. | + +Example using `onAfterUserProfileCreated`: + +```dart +pod.initializeAuthServices( + ... + userProfileConfig: UserProfileConfig( + onAfterUserProfileCreated: (session, userProfile, {required transaction}) async { + // Do something with the new profile (e.g. create related data, set default image) + }, + ), +); +``` + ### Accessing user profiles from the app To access the user profile from your Flutter app, you can use the `userProfileInfo` endpoint that is included in the authentication module: @@ -175,7 +203,7 @@ class UserProfileEditEndpoint extends UserProfileEditBaseEndpoint { ### Setting a default user image -When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object. +When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, you can set a default user image using the `onAfterUserProfileCreated` callback in `UserProfileConfig` (see [User profile callbacks](#user-profile-callbacks) for the full set of callbacks). ```dart pod.initializeAuthServices( diff --git a/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md index 7f3e935a..57df77a9 100644 --- a/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.1.0/06-concepts/11-authentication/03-working-with-users.md @@ -107,6 +107,34 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation. +### User profile callbacks + +You can react when a user profile is created or updated by using the `UserProfileConfig` callbacks. Configure them when initializing auth services on the `pod` object via the `userProfileConfig` parameter. + +:::warning +All callbacks receive a `transaction` parameter that should be used on all database operations performed inside the callback. Failing to pass the transaction might lead to entries not being found or changes not being rolled back together. +::: + +| Callback | When | Purpose | +| -------- | ---- | ------- | +| `onBeforeUserProfileCreated` | Before a profile is created | Receive and return `UserProfileData` to modify defaults (user name, full name, email). | +| `onAfterUserProfileCreated` | After a profile is created | Run logic that depends on the new profile (e.g. related data, default image). | +| `onBeforeUserProfileUpdated` | Before a profile is updated (name, full name, or picture) | Receive and return `UserProfileData` to enforce rules or transform values. | +| `onAfterUserProfileUpdated` | After a profile is updated | Sync related data or trigger side effects. | + +Example using `onAfterUserProfileCreated`: + +```dart +pod.initializeAuthServices( + ... + userProfileConfig: UserProfileConfig( + onAfterUserProfileCreated: (session, userProfile, {required transaction}) async { + // Do something with the new profile (e.g. create related data, set default image) + }, + ), +); +``` + ### Accessing user profiles from the app To access the user profile from your Flutter app, you can use the `userProfileInfo` endpoint that is included in the authentication module: @@ -175,7 +203,7 @@ class UserProfileEditEndpoint extends UserProfileEditBaseEndpoint { ### Setting a default user image -When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object. +When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, you can set a default user image using the `onAfterUserProfileCreated` callback in `UserProfileConfig` (see [User profile callbacks](#user-profile-callbacks) for the full set of callbacks). ```dart pod.initializeAuthServices( diff --git a/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md index 7f3e935a..57df77a9 100644 --- a/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.2.0/06-concepts/11-authentication/03-working-with-users.md @@ -107,6 +107,34 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation. +### User profile callbacks + +You can react when a user profile is created or updated by using the `UserProfileConfig` callbacks. Configure them when initializing auth services on the `pod` object via the `userProfileConfig` parameter. + +:::warning +All callbacks receive a `transaction` parameter that should be used on all database operations performed inside the callback. Failing to pass the transaction might lead to entries not being found or changes not being rolled back together. +::: + +| Callback | When | Purpose | +| -------- | ---- | ------- | +| `onBeforeUserProfileCreated` | Before a profile is created | Receive and return `UserProfileData` to modify defaults (user name, full name, email). | +| `onAfterUserProfileCreated` | After a profile is created | Run logic that depends on the new profile (e.g. related data, default image). | +| `onBeforeUserProfileUpdated` | Before a profile is updated (name, full name, or picture) | Receive and return `UserProfileData` to enforce rules or transform values. | +| `onAfterUserProfileUpdated` | After a profile is updated | Sync related data or trigger side effects. | + +Example using `onAfterUserProfileCreated`: + +```dart +pod.initializeAuthServices( + ... + userProfileConfig: UserProfileConfig( + onAfterUserProfileCreated: (session, userProfile, {required transaction}) async { + // Do something with the new profile (e.g. create related data, set default image) + }, + ), +); +``` + ### Accessing user profiles from the app To access the user profile from your Flutter app, you can use the `userProfileInfo` endpoint that is included in the authentication module: @@ -175,7 +203,7 @@ class UserProfileEditEndpoint extends UserProfileEditBaseEndpoint { ### Setting a default user image -When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object. +When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, you can set a default user image using the `onAfterUserProfileCreated` callback in `UserProfileConfig` (see [User profile callbacks](#user-profile-callbacks) for the full set of callbacks). ```dart pod.initializeAuthServices( diff --git a/versioned_docs/version-3.3.0/06-concepts/11-authentication/03-working-with-users.md b/versioned_docs/version-3.3.0/06-concepts/11-authentication/03-working-with-users.md index 7f3e935a..57df77a9 100644 --- a/versioned_docs/version-3.3.0/06-concepts/11-authentication/03-working-with-users.md +++ b/versioned_docs/version-3.3.0/06-concepts/11-authentication/03-working-with-users.md @@ -107,6 +107,34 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation. +### User profile callbacks + +You can react when a user profile is created or updated by using the `UserProfileConfig` callbacks. Configure them when initializing auth services on the `pod` object via the `userProfileConfig` parameter. + +:::warning +All callbacks receive a `transaction` parameter that should be used on all database operations performed inside the callback. Failing to pass the transaction might lead to entries not being found or changes not being rolled back together. +::: + +| Callback | When | Purpose | +| -------- | ---- | ------- | +| `onBeforeUserProfileCreated` | Before a profile is created | Receive and return `UserProfileData` to modify defaults (user name, full name, email). | +| `onAfterUserProfileCreated` | After a profile is created | Run logic that depends on the new profile (e.g. related data, default image). | +| `onBeforeUserProfileUpdated` | Before a profile is updated (name, full name, or picture) | Receive and return `UserProfileData` to enforce rules or transform values. | +| `onAfterUserProfileUpdated` | After a profile is updated | Sync related data or trigger side effects. | + +Example using `onAfterUserProfileCreated`: + +```dart +pod.initializeAuthServices( + ... + userProfileConfig: UserProfileConfig( + onAfterUserProfileCreated: (session, userProfile, {required transaction}) async { + // Do something with the new profile (e.g. create related data, set default image) + }, + ), +); +``` + ### Accessing user profiles from the app To access the user profile from your Flutter app, you can use the `userProfileInfo` endpoint that is included in the authentication module: @@ -175,7 +203,7 @@ class UserProfileEditEndpoint extends UserProfileEditBaseEndpoint { ### Setting a default user image -When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object. +When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, you can set a default user image using the `onAfterUserProfileCreated` callback in `UserProfileConfig` (see [User profile callbacks](#user-profile-callbacks) for the full set of callbacks). ```dart pod.initializeAuthServices(