---
title: "Users"
description: "Learn how to configure the Sentry PHP SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry."
url: https://docs.sentry.io/platforms/php/enriching-events/identify-user/
---

# Users for PHP

To attach the user to your events, you can set the user's details on the scope:

```php
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setUser(['email' => 'jane.doe@example.com']);
});
```

You can also clear the currently set user:

```php
\Sentry\configureScope(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:

### [`id`](https://docs.sentry.io/platforms/php/enriching-events/identify-user.md#id)

Your internal identifier for the user.

### [`username`](https://docs.sentry.io/platforms/php/enriching-events/identify-user.md#username)

The username. Typically used as a better label than the internal id.

### [`email`](https://docs.sentry.io/platforms/php/enriching-events/identify-user.md#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`](https://docs.sentry.io/platforms/php/enriching-events/identify-user.md#ip_address)

The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. The SDK will attempt to pull the IP address from the HTTP request data on incoming requests (`request.env.REMOTE_ADDR` field in JSON), if available. That requires `send_default_pii` 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, users with project admin permissions (Org Owner, Org Manager, Team Admin, or Org Admin) can go to your project settings, click on ["Security & Privacy"](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/security-and-privacy/), and enable "Prevent Storing of IP Addresses". Alternatively, use Sentry's [server-side data](https://docs.sentry.io/security-legal-pii/scrubbing.md) scrubbing to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic.

Additionally, you can provide arbitrary key/value pairs beyond the reserved names, and the Sentry SDK will store those with the user.

## [Resolve the User Lazily](https://docs.sentry.io/platforms/php/enriching-events/identify-user.md#resolve-the-user-lazily)

Available in SDK versions newer than 4.37.1.

If getting the user eagerly has side effects, for example because it starts a session, you can set a user resolver instead of setting the user up front. A user resolver is a callback that returns a `\Sentry\UserDataBag`, or `null` when no user is available yet:

```php
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setUserResolver(function (): ?\Sentry\UserDataBag {
        $user = getAuthenticatedUser(); // Your application's user lookup

        if ($user === null) {
            return null;
        }

        return \Sentry\UserDataBag::createFromArray([
            'id' => $user->id,
            'email' => $user->email,
        ]);
    });
});
```

The SDK calls the resolver every time it reads the user from the scope, which happens for every event, log, and metric, so keep it fast. Data set with `setUser()` takes precedence over the data the resolver returns, and the resolver only fills in the fields that aren't set. If the resolver throws an exception, the SDK ignores it and uses only the data set with `setUser()`. Calling `removeUser()` also removes the resolver.
