Search documentation of phoenix_kit

# PhoenixKit.Users.Auth.Scope (phoenix_kit v1.6.19)

View Source

Scope module for encapsulating PhoenixKit authentication state.

This module provides a structured way to handle user authentication context throughout your Phoenix application, similar to Phoenix's built-in authentication patterns but with PhoenixKit prefixing to avoid conflicts.

## Usage

    # Create scope for authenticated user
    scope = Scope.for_user(user)

    # Create scope for anonymous user
    scope = Scope.for_user(nil)

    # Check authentication status
    Scope.authenticated?(scope)  # true or false

    # Get user information
    Scope.user(scope)        # %User{} or nil
    Scope.user_id(scope)     # user.id or nil
    Scope.user_email(scope)  # user.email or nil

## Struct Fields

- `:user` - The current user struct or nil
- `:authenticated?` - Boolean indicating if user is authenticated

# Summary

## Types

t()

## Functions

admin?(scope)

Checks if the user is an admin or owner.

anonymous?(scope)

Checks if the scope represents an anonymous (non-authenticated) user.

authenticated?(scope)

Checks if the scope represents an authenticated user.

for_user(user)

Creates a new scope for the given user.

has_role?(scope, role_name)

Checks if the user has a specific role.

owner?(scope)

Checks if the user is an owner.

to_map(scope)

Converts scope to a map for debugging or logging purposes.

user(scope)

Gets the user from the scope.

user_active?(scope)

Checks if the user is active.

user_email(scope)

Gets the user email from the scope.

user_full_name(scope)

Gets the user's full name.

user_id(scope)

Gets the user ID from the scope.

user_roles(scope)

Gets all roles for the user.

# Types

# t()

    @type t() :: %PhoenixKit.Users.Auth.Scope{
      authenticated?: boolean(),
      cached_roles: [String.t()] | nil,
      user: PhoenixKit.Users.Auth.User.t() | nil
    }

# Functions

# admin?(scope)

    @spec admin?(t()) :: boolean()

Checks if the user is an admin or owner.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.admin?(scope)
    true

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.admin?(scope)
    false

# anonymous?(scope)

    @spec anonymous?(t()) :: boolean()

Checks if the scope represents an anonymous (non-authenticated) user.

## Examples

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.anonymous?(scope)
    true

    iex> user = %PhoenixKit.Users.Auth.User{id: 1}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.anonymous?(scope)
    false

# authenticated?(scope)

    @spec authenticated?(t()) :: boolean()

Checks if the scope represents an authenticated user.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.authenticated?(scope)
    true

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.authenticated?(scope)
    false

# for_user(user)

    @spec for_user(PhoenixKit.Users.Auth.User.t() | nil) :: t()

Creates a new scope for the given user.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1, email: "user@example.com"}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> scope.authenticated?
    true
    iex> scope.user.email
    "user@example.com"

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> scope.authenticated?
    false
    iex> scope.user
    nil

# has_role?(scope, role_name)

    @spec has_role?(t(), String.t()) :: boolean()

Checks if the user has a specific role.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.has_role?(scope, "Admin")
    true

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.has_role?(scope, "Admin")
    false

# owner?(scope)

    @spec owner?(t()) :: boolean()

Checks if the user is an owner.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.owner?(scope)
    true

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.owner?(scope)
    false

# to_map(scope)

    @spec to_map(t()) :: map()

Converts scope to a map for debugging or logging purposes.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1, email: "user@example.com"}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.to_map(scope)
    %{
      authenticated?: true,
      user_id: 1,
      user_email: "user@example.com",
      user_roles: ["Admin", "User"],
      owner?: false,
      admin?: true
    }

# user(scope)

    @spec user(t()) :: PhoenixKit.Users.Auth.User.t() | nil

Gets the user from the scope.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1, email: "user@example.com"}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.user(scope)
    %PhoenixKit.Users.Auth.User{id: 1, email: "user@example.com"}

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.user(scope)
    nil

# user_active?(scope)

    @spec user_active?(t()) :: boolean()

Checks if the user is active.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{is_active: true}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.user_active?(scope)
    true

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.user_active?(scope)
    false

# user_email(scope)

    @spec user_email(t()) :: String.t() | nil

Gets the user email from the scope.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1, email: "user@example.com"}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.user_email(scope)
    "user@example.com"

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.user_email(scope)
    nil

# user_full_name(scope)

    @spec user_full_name(t()) :: String.t() | nil

Gets the user's full name.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{first_name: "John", last_name: "Doe"}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.user_full_name(scope)
    "John Doe"

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.user_full_name(scope)
    nil

# user_id(scope)

    @spec user_id(t()) :: integer() | nil

Gets the user ID from the scope.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 123}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.user_id(scope)
    123

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.user_id(scope)
    nil

# user_roles(scope)

    @spec user_roles(t()) :: [String.t()]

Gets all roles for the user.

## Examples

    iex> user = %PhoenixKit.Users.Auth.User{id: 1}
    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(user)
    iex> PhoenixKit.Users.Auth.Scope.user_roles(scope)
    ["Admin", "User"]

    iex> scope = PhoenixKit.Users.Auth.Scope.for_user(nil)
    iex> PhoenixKit.Users.Auth.Scope.user_roles(scope)
    []