[laravel] Clarify attaching a user to an event (#12830)

Author: cleptric

docs/platforms/php/common/data-management/data-collected.mdx

@@ -12,19 +12,19 @@ The category types and amount of data collected vary, depending on the integrati
 
 By default, the Sentry SDK doesn't send any HTTP headers.
 
-To start sending HTTP headers, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To start sending HTTP headers, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Cookies
 
 By default, the Sentry SDK doesn't send cookies.
 
-If you want to send cookies, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+If you want to send cookies, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Users' IP Address
 
 By default, the Sentry SDK doesn't send the user's IP address.
 
-To enable sending the user's IP address, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To enable sending the user's IP address, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Request URL
 
@@ -42,15 +42,15 @@ The request body of incoming HTTP requests can be sent to Sentry. Whether it's s
   -JSON and form bodies are sent
   -Raw request bodies are always removed
   -Uploaded files in the request bodies are never sent to Sentry
-- **The size of the request body:** There's a [`max_request_body_size` option](../configuration/options/#max-request-body-size) that's set to `medium` by default. This means that larger request bodies aren't sent to Sentry.
+- **The size of the request body:** There's a <PlatformLink to="/configuration/options/#max_request_body_size">max_request_body_size option</PlatformLink> that's set to `medium` by default. This means that larger request bodies aren't sent to Sentry.
 
 If you want to prevent bodies from being sent to Sentry altogether, set `max_request_body_size` to `'never'`.
 
 ## Source Context
 
 When an unhandled exception is sent to Sentry, a snapshot of the source code surrounding the line where the error originates is sent with it.
 
-To opt out of sending this source context to Sentry, set the [`context_lines` option](../configuration/options/#context-lines) to `0`.
+To opt out of sending this source context to Sentry, set the <PlatformLink to="/configuration/options/#context-lines">`context_lines` option</PlatformLink> to `0`.
 
 ## Local Variables In Stack Trace
 

docs/platforms/php/common/enriching-events/identify-user/index.mdx

@@ -3,6 +3,14 @@ title: Users
 description: "Learn how to configure the SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry."
 ---
 
+To attach the user to your events, we recommend to listen to Laravel's `\Illuminate\Auth\Events\Authenticated` event:
+
+<PlatformContent includePath="enriching-events/set-user" />
+
+You can also clear the currently set user:
+
+<PlatformContent includePath="enriching-events/unset-user" />
+
 Users consist of a few critical pieces of information that construct a unique identity in Sentry. Each of these is optional, but one **must** be present for the Sentry SDK to capture the user:
 
 <DefinitionList>
@@ -24,20 +32,10 @@ An alternative, or addition, to the username. Sentry is aware of email addresses
 The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user.
 Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. That might require <PlatformIdentifier name="send-default-pii" /> set to `true` in the SDK options.
 
-If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server.
-
-If the field is omitted, the default value is `null`. However, due to backwards compatibility concerns, certain platforms (in particular JavaScript) have a different default value for `"{{auto}}"`. SDKs and other clients should not rely on this behavior and should set IP addresses or `"{{auto}}"` explicitly.
+If the field is omitted, the default value is `null`.
 
 To opt out of storing users' IP addresses in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data](/security-legal-pii/scrubbing/) scrubbing to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic.
 
 </DefinitionList>
 
 Additionally, you can provide arbitrary key/value pairs beyond the reserved names, and the Sentry SDK will store those with the user.
-
-To identify the user:
-
-<PlatformContent includePath="enriching-events/set-user" />
-
-You can also clear the currently set user:
-
-<PlatformContent includePath="enriching-events/unset-user" />

docs/platforms/php/guides/laravel/data-management/data-collected.mdx

@@ -12,25 +12,25 @@ The category types and amount of data collected vary, depending on the integrati
 
 By default, the Sentry SDK doesn't send any HTTP headers.
 
-To start sending HTTP headers, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To start sending HTTP headers, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Cookies
 
 By default, the Sentry SDK doesn't send cookies. Sentry tries to remove any cookies that contain sensitive information, (such as the Laravel Session, Remember Token and CSRF Token cookies).
 
-If you want to send cookies, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+If you want to send cookies, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Information About Logged-in User
 
 By default, the Sentry SDK doesn't send any information about the logged-in user, (such as email address, user id, or username).
 
-To start sending logged-in user information, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To start sending logged-in user information, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Users' IP Address
 
 By default, the Sentry SDK doesn't send the user's IP address.
 
-To enable sending the user's IP address, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To enable sending the user's IP address, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Request URL
 
@@ -48,15 +48,15 @@ The request body of incoming HTTP requests can be sent to Sentry. Whether it's s
   -JSON and form bodies are sent
   -Raw request bodies are always removed
   -Uploaded files in the request bodies are never sent to Sentry
-- **The size of the request body:** There's a [`max_request_body_size` option](../configuration/options/#max-request-body-size) that's set to `medium` by default. This means that larger request bodies aren't sent to Sentry.
+- **The size of the request body:** There's an <PlatformLink to="/configuration/options/#max_request_body_size">max_request_body_size option</PlatformLink> that's set to `medium` by default. This means that larger request bodies aren't sent to Sentry.
 
 If you want to prevent bodies from being sent to Sentry altogether, set `max_request_body_size` to `'never'`.
 
 ## Source Context
 
 When an unhandled exception is sent to Sentry, a snapshot of the source code surrounding the line where the error originates is sent with it.
 
-To opt out of sending this source context to Sentry, set the [`context_lines` option](../configuration/options/#context-lines) to `0`.
+To opt out of sending this source context to Sentry, set the <PlatformLink to="/configuration/options/#context_lines">context_lines option</PlatformLink> to `0`.
 
 ## Local Variables In Stack Trace
 

docs/platforms/php/guides/laravel/enriching-events/identify-user/index.mdx

@@ -0,0 +1,65 @@
+---
+title: Users
+description: "Learn how to configure the SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry."
+---
+
+If the SDK is configured with <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii</PlatformLink> set to `true`, we automatically attach the authenticated user to all your events sent to Sentry. 
+
+If you instead want to manually attach the user to your events, we recommend to listen to Laravel's `\Illuminate\Auth\Events\Authenticated` event:
+
+```php {filename:app/Providers/AppServiceProvider.php}
+/**
+* Bootstrap any application services.
+*/
+public function boot(): void
+{
+    \Illuminate\Support\Facades\Event::listen(function (\Illuminate\Auth\Events\Authenticated $event) {
+        $user = $event->user;
+
+        \Sentry\Laravel\Integration::configureScope(static function (Scope $scope) use ($user): void {
+            $scope->setUser([
+                'id' => $user->id,
+                'name' => $user->name,
+                'email' => $user->email,
+            ]);
+        });
+    });
+}
+```
+
+You can also clear the currently set user:
+
+```php
+\Sentry\Laravel\Integration::configureScope(static function (\Sentry\State\Scope $scope): void {
+    $scope->removeUser();
+});
+```
+
+Users consist of a few critical pieces of information that construct a unique identity in Sentry. Each of these is optional, but one **must** be present for the Sentry SDK to capture the user:
+
+<DefinitionList>
+
+### `id`
+
+Your internal identifier for the user.
+
+### `username`
+
+The username. Typically used as a better label than the internal id.
+
+### `email`
+
+An alternative, or addition, to the username. Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities.
+
+### `ip_address`
+
+The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user.
+Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. That might require <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii</PlatformLink> set to `true` in the SDK options.
+
+If the field is omitted, the default value is `null`.
+
+To opt out of storing users' IP addresses in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data](/security-legal-pii/scrubbing/) scrubbing to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic.
+
+</DefinitionList>
+
+Additionally, you can provide arbitrary key/value pairs beyond the reserved names, and the Sentry SDK will store those with the user.

docs/platforms/php/guides/symfony/data-management/data-collected.mdx

@@ -12,25 +12,25 @@ The category types and amount of data collected vary, depending on the integrati
 
 By default, the Sentry SDK doesn't send any HTTP headers.
 
-To start sending HTTP headers, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To start sending HTTP headers, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Cookies
 
 By default, the Sentry SDK doesn't send cookies.
 
-If you want to send cookies, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+If you want to send cookies, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Information About Logged-in User
 
 By default, the Sentry SDK doesn't send any information about the logged-in user, (such as user id, or impersonator username).
 
-To start sending logged-in user information, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To start sending logged-in user information, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Users' IP Address
 
 By default, the Sentry SDK doesn't send the user's IP address.
 
-To enable sending the user's IP address, set the [`send_default_pii` option](../configuration/options/#send-default-pii) to `true`.
+To enable sending the user's IP address, set the <PlatformLink to="/configuration/options/#send_default_pii">send_default_pii option</PlatformLink> to `true`.
 
 ## Request URL
 
@@ -48,15 +48,15 @@ The request body of incoming HTTP requests can be sent to Sentry. Whether it's s
   -JSON and form bodies are sent
   -Raw request bodies are always removed
   -Uploaded files in the request bodies are never sent to Sentry
-- **The size of the request body:** There's a [`max_request_body_size` option](../configuration/options/#max-request-body-size) that's set to `medium` by default. This means that larger request bodies aren't sent to Sentry.
+- **The size of the request body:** There's an <PlatformLink to="/configuration/options/#max_request_body_size">max_request_body_size option</PlatformLink> that's set to `medium` by default. This means that larger request bodies aren't sent to Sentry.
 
 If you want to prevent bodies from being sent to Sentry altogether, set `max_request_body_size` to `'never'`.
 
 ## Source Context
 
 When an unhandled exception is sent to Sentry, a snapshot of the source code surrounding the line where the error originates is sent with it.
 
-To opt out of sending this source context to Sentry, set the [`context_lines` option](../configuration/options/#context-lines) to `0`.
+To opt out of sending this source context to Sentry, set the <PlatformLink to="/configuration/options/#context_lines">context_lines option</PlatformLink> to `0`.
 
 ## Local Variables In Stack Trace