Global Functions

Purpose and Scope

This document covers the global helper functions provided by the hypervel/auth package. These functions offer convenient, short-hand access to the authentication and authorization system from anywhere in your application code.

For information about the underlying AuthManager that these functions access, see AuthManager. For details about the Guard implementations returned by these functions, see Guards.

---

Overview

The hypervel/auth package provides a single global helper function for accessing the authentication system. This function serves as the primary entry point for developers to interact with guards, check authentication status, and perform authorization operations.

Function	Return Type	Purpose
auth()	AuthFactoryContract (AuthManager)	Returns the AuthManager factory
auth($guard)	Guard	Returns a specific guard instance

The function is defined in src/Functions.php14-24 and provides a convenient alternative to resolving the AuthManager from the dependency injection container manually.

Sources: src/Functions.php1-25

---

The auth() Function

Function Signature

The auth() function accepts an optional guard name parameter and returns either the AuthManager instance or a specific Guard implementation.

Sources: src/Functions.php14

Return Types

The function has two distinct behaviors based on whether a guard name is provided:

Parameter	Return Type	Description
null (default)	AuthFactoryContract	Returns the AuthManager instance, providing access to all factory methods
string (guard name)	Guard	Returns a specific guard instance (e.g., 'jwt', 'session')

Sources: src/Functions.php14-24

Internal Implementation

Diagram: auth() Function Resolution Flow

The implementation follows this sequence:

1. Container Resolution: Retrieves the container from ApplicationContext::getContainer() src/Functions.php16-17
2. AuthManager Retrieval: Resolves the AuthManager singleton from the container src/Functions.php17
3. Guard Parameter Check: Tests if a guard name was provided src/Functions.php19
4. Conditional Return: Returns either the manager or calls guard() method src/Functions.php20-23

Sources: src/Functions.php14-24

---

Usage Patterns

Pattern 1: Access AuthManager Factory

When called without parameters, auth() returns the AuthManager instance, providing access to all factory methods:

This pattern is useful when you need to:

• Switch between guards dynamically
• Access the user resolver
• Configure the default guard at runtime
• Register custom guards or providers

Sources: src/Functions.php19-21

Pattern 2: Access Specific Guard

When called with a guard name, auth() returns that guard instance directly:

This pattern provides direct access to guard methods without an intermediate call to guard().

Sources: src/Functions.php19-24

Pattern 3: Default Guard Access

Calling auth() and then immediately calling guard() on the result uses the default guard configured in the system:

The default guard is determined by the default configuration value in your auth configuration file.

Sources: src/Functions.php14-24

Pattern 4: Chaining Guard Methods

The most common pattern chains guard methods directly:

This pattern leverages method chaining for concise, readable authentication checks.

Sources: src/Functions.php14-24

---

Integration with Application Context

Diagram: Dependency Resolution Chain

The auth() function relies on Hyperf's ApplicationContext for container access:

1. Static Container Access: Uses ApplicationContext::getContainer() to obtain the global container instance src/Functions.php16-17
2. Singleton Resolution: Retrieves the AuthManager which is registered as a singleton in the container src/Functions.php17
3. Instance Caching: The container ensures the same AuthManager instance is returned across all calls
4. Guard Factory: The manager creates or retrieves guard instances as needed src/Functions.php23

This approach ensures consistent authentication state throughout the request lifecycle while maintaining separation from the HTTP request/response cycle.

Sources: src/Functions.php14-24

---

Relationship to Core Components

Diagram: auth() Function Component Relationships

The auth() function serves as the gateway to the authentication system:

• AuthManager Access: Returns the factory for guard management and configuration (see AuthManager)
• Guard Access: Returns specific guard implementations for authentication operations (see Guards)
• User Resolution: Provides indirect access to the user resolver through the manager (see User Resolver)

All authentication operations ultimately flow through this single entry point, ensuring consistent access patterns throughout the application.

Sources: src/Functions.php14-24

---

Contract and Interface Compliance

The return types of the auth() function are governed by contracts:

Return Type	Contract/Interface	Purpose
AuthFactoryContract	Hypervel\Auth\Contracts\Factory	Defines factory methods for guard management
Guard	Hypervel\Auth\Contracts\Guard	Defines authentication operations

When auth() returns the AuthManager, it implements the Factory contract (see Factory Contract). When it returns a guard, that guard implements the Guard contract (see Guard Contracts).

This contract-based design allows for type safety while maintaining flexibility for custom implementations.

Sources: src/Functions.php8-14

---

Alternative Access Methods

While auth() is the recommended approach, the authentication system can also be accessed through:

Dependency Injection

Direct Container Resolution

Context-Aware Access

Guard instances cache authenticated users in the request context. Once authenticated, subsequent calls to auth()->user() within the same request retrieve the cached user without additional database queries.

The auth() function is preferred for its brevity and consistency with Laravel-style applications, but these alternatives provide additional flexibility for specific use cases.

Sources: src/Functions.php16-17

---

Summary

The auth() global function provides the primary interface for accessing the hypervel/auth system:

• Dual-mode operation: Returns either AuthManager or a specific Guard based on parameters
• Container integration: Leverages Hyperf's ApplicationContext for dependency resolution
• Type-safe contracts: Return types implement well-defined interfaces
• Flexible access patterns: Supports factory access, direct guard access, and method chaining

This single function serves as the foundation for all authentication operations in Hypervel applications, providing a simple, consistent API that abstracts the underlying complexity of guard management and user resolution.

Sources: src/Functions.php1-25