Helper Functions and Utilities

Purpose and Scope

This document provides an overview of the helper functions and utility traits provided by the hypervel/auth package. These components simplify common authentication and authorization tasks by providing convenient APIs that reduce boilerplate code.

The package includes:

• Global helper functions for accessing authentication services (Section 6.1)
• Utility traits for authorization responses and request handling (Section 6.2)

For detailed information about the AuthManager, see AuthManager. For authorization system details, see Authorization System.

Overview

The hypervel/auth package provides utilities that serve as convenience layers over the core authentication and authorization systems. These utilities follow two design patterns:

Utility Type	Pattern	Primary Use Case	Example
Global Functions	Service Locator	Quick access to auth services without DI	auth()->user()
Utility Traits	Mixin	Add reusable methods to classes	Policy authorization responses

Sources: src/Functions.php1-24 src/Access/HandlesAuthorization.php1-40

Utility Architecture Overview

The utilities provide simplified access patterns that delegate to core components while reducing code verbosity.

Sources: src/Functions.php1-24 src/Access/HandlesAuthorization.php1-40 src/AuthManager.php1-255

Global Helper Functions

The package provides the auth() global function for convenient access to authentication services without dependency injection. The function is defined in src/Functions.php14-24

Function Signature and Return Types

Parameter	Return Type	Description
null (default)	AuthFactoryContract (AuthManager)	Returns the AuthManager for factory operations
Guard name string	Guard	Returns the specified guard instance

The function uses ApplicationContext::getContainer() to resolve the AuthManager from Hyperf's dependency injection container src/Functions.php16-17

Sources: src/Functions.php1-24

auth() Helper Resolution Flow

Sources: src/Functions.php14-24 src/AuthManager.php60-65

Common Usage Patterns

The AuthManager implements __call() src/AuthManager.php251-254 to forward method calls to the default guard, enabling shorthand syntax.

For detailed documentation of the auth() function, including integration patterns and context-aware behavior, see Global Functions.

Sources: src/Functions.php1-24 src/AuthManager.php251-254

Utility Traits

The package provides utility traits that add commonly-needed methods to application classes. These traits reduce boilerplate code in policies and controllers.

HandlesAuthorization Trait

The HandlesAuthorization trait src/Access/HandlesAuthorization.php7-40 provides helper methods for creating authorization responses in policy classes. It is typically used in policy classes to simplify response creation.

Method	Return Type	Description
allow(?string $message, int|string|null $code)	Response	Create an "allow" authorization response
deny(?string $message, int|string|null $code)	Response	Create a "deny" authorization response
denyWithStatus(int $status, ?string $message, int|string|null $code)	Response	Deny with specific HTTP status code
denyAsNotFound(?string $message, int|string|null $code)	Response	Deny with 404 status (resource hiding)

All methods delegate to static factory methods on the Response class src/Access/Response.php

Sources: src/Access/HandlesAuthorization.php1-40

HandlesAuthorization Usage in Policies

Sources: src/Access/HandlesAuthorization.php7-40

Trait Method Implementation Pattern

The trait methods are thin wrappers around the Response class factory methods:

This design pattern allows policy classes to use simple method calls while maintaining a single source of truth for response creation logic in the Response class.

Sources: src/Access/HandlesAuthorization.php12-23

Additional Utility Traits

Other utility traits documented in Section 6.2 include:

• AuthorizesRequests - For adding authorization methods to controllers
• Additional traits for common authentication/authorization patterns

Sources: src/Access/HandlesAuthorization.php1-40

Summary

The auth() helper function provides a simple, convenient interface to the authentication system:

• Zero configuration required - Works immediately after package installation
• Dual-purpose design - Returns manager or guard based on parameters
• Container integration - Leverages Hyperf's dependency injection
• Context-aware - Respects request-scoped defaults and customizations
• Method forwarding - AuthManager forwards calls to default guard for convenience

This design pattern makes authentication code concise while maintaining flexibility for advanced use cases.

Sources: src/Functions.php1-24 src/AuthManager.php22-255