 |
VOOZH | about |
|
VOOZH | about |
The SessionGuard is a stateful authentication guard implementation that manages user authentication through server-side sessions. It stores the authenticated user's identifier in the session and retrieves the full user object on each request, providing traditional session-based authentication suitable for web applications.
For information about other guard types, see Guards. For details on the shared guard functionality, see GuardHelpers Trait. For session-less JWT authentication, see JwtGuard.
The SessionGuard implements the StatefulGuard contract and integrates with Hyperf's session management and context systems to provide efficient, secure session-based authentication.
Sources: src/Guards/SessionGuard.php1-149 src/Guards/GuardHelpers.php1-116
The SessionGuard stores only the user's authentication identifier in the session, not the complete user object. This approach balances security and performance.
| Purpose | Key Format | Example |
|---|---|---|
| Session storage | auth.guards.session.{guardName} | auth.guards.session.web |
| Context cache (started) | auth.guards.{guardName}.result:{sessionId} | auth.guards.web.result:abc123 |
| Context cache (unstarted) | auth.guards.{guardName}.unstarted | auth.guards.web.unstarted |
The sessionKey() method generates the session storage key, while getContextKey() and getUnstartedContextKey() generate context cache keys.
Sources: src/Guards/SessionGuard.php145-148 src/Guards/SessionGuard.php93-101
The guard implements session regeneration as a security measure against session fixation attacks:
The updateSession() method at src/Guards/SessionGuard.php72-77 performs two operations:
session->migrate(true) to regenerate the session ID and destroy the old sessionSources: src/Guards/SessionGuard.php62-77
The SessionGuard implements a sophisticated two-level context caching system to optimize performance and handle edge cases with session initialization.
Sources: src/Guards/SessionGuard.php103-126
The dual context key system handles a specific edge case in Hyperf's session lifecycle:
Started Session Context (auth.guards.{name}.result:{sessionId}): Used when the session has been initialized. The key includes the session ID to ensure cache invalidation across different session IDs.
Unstarted Session Context (auth.guards.{name}.unstarted): Used when the session hasn't been started yet but a user object needs to be cached (e.g., when setUser() is called before session initialization).
The setUser() method at src/Guards/SessionGuard.php135-143 demonstrates this logic:
Sources: src/Guards/SessionGuard.php93-101 src/Guards/SessionGuard.php135-143
The SessionGuard provides multiple authentication methods for different use cases.
| Method | Persists to Session | Returns | Use Case |
|---|---|---|---|
attempt() | Yes (if $login=true) | bool | Standard login with credentials |
login() | Yes | void | Direct login with user object |
once() | No | bool | One-time auth without persistence |
loginUsingId() | Yes | Authenticatable|bool | Login by user ID |
onceUsingId() | No | Authenticatable|bool | One-time auth by ID |
validate() | No | bool | Credentials check only |
The attempt() method at src/Guards/SessionGuard.php30-43 implements the complete authentication flow:
Sources: src/Guards/SessionGuard.php30-43 src/Guards/GuardHelpers.php107-114
The login() method at src/Guards/SessionGuard.php62-67 accepts a user object directly:
Sources: src/Guards/SessionGuard.php62-67
The once() and onceUsingId() methods provide authentication without session persistence:
once(credentials) at src/Guards/SessionGuard.php48-57: Authenticates with credentials, caches user in context, but doesn't persist to sessiononceUsingId(id) at src/Guards/SessionGuard.php82-91: Authenticates by ID without session persistenceThese methods are useful for API endpoints that need temporary authentication or for validating credentials without establishing a session.
Sources: src/Guards/SessionGuard.php48-57 src/Guards/SessionGuard.php82-91
The user() method at src/Guards/SessionGuard.php103-126 implements the complete user retrieval logic with exception handling:
The user() method wraps session and provider operations in a try-catch block at src/Guards/SessionGuard.php116-123 If any exception occurs during session retrieval or user lookup, the method caches null and returns it gracefully. This prevents authentication errors from propagating as exceptions.
Sources: src/Guards/SessionGuard.php103-126
The logout() method at src/Guards/SessionGuard.php128-133 performs a complete cleanup:
This three-step process ensures:
Sources: src/Guards/SessionGuard.php128-133
The SessionGuard depends on a UserProvider implementation (injected via constructor at src/Guards/SessionGuard.php20-25) for all user data operations:
| Operation | Provider Method | Purpose |
|---|---|---|
| Retrieve by ID | retrieveById(id) | Get user from session-stored ID |
| Retrieve by credentials | retrieveByCredentials(credentials) | Find user for authentication |
| Validate credentials | validateCredentials(user, credentials) | Verify password/credentials |
For details on user provider implementations, see User Providers.
Sources: src/Guards/SessionGuard.php20-25
The guard requires a SessionContract implementation (from the hypervel/session package). Key session operations used:
| Method | Usage in SessionGuard | Line Reference |
|---|---|---|
put(key, value) | Store user ID | src/Guards/SessionGuard.php74 |
get(key) | Retrieve user ID | src/Guards/SessionGuard.php117 |
remove(key) | Clear user ID on logout | src/Guards/SessionGuard.php132 |
migrate(destroy) | Regenerate session ID | src/Guards/SessionGuard.php76 |
getId() | Get session ID for context key | src/Guards/SessionGuard.php95 |
isStarted() | Check if session initialized | src/Guards/SessionGuard.php137 |
Sources: src/Guards/SessionGuard.php20-25
The SessionGuard uses the GuardHelpers trait at src/Guards/SessionGuard.php17 to provide standard guard methods:
| Method | Description | Source |
|---|---|---|
authenticate() | Get user or throw exception | src/Guards/GuardHelpers.php21-28 |
check() | Check if authenticated | src/Guards/GuardHelpers.php77-80 |
guest() | Check if not authenticated | src/Guards/GuardHelpers.php41-44 |
id() | Get user identifier | src/Guards/GuardHelpers.php49-56 |
hasUser() | Check if user exists | src/Guards/GuardHelpers.php33-36 |
loginUsingId() | Login by ID with session | src/Guards/GuardHelpers.php85-94 |
validate() | Validate credentials only | src/Guards/GuardHelpers.php99-102 |
hasValidCredentials() | Internal credential validation | src/Guards/GuardHelpers.php107-114 |
For details on these shared methods, see GuardHelpers Trait.
Sources: src/Guards/SessionGuard.php17 src/Guards/GuardHelpers.php1-116
The SessionGuard includes the Macroable trait at src/Guards/SessionGuard.php18 allowing runtime method injection for custom functionality:
Sources: src/Guards/SessionGuard.php18
This diagram illustrates the complete lifecycle showing:
Sources: src/Guards/SessionGuard.php1-149 src/Guards/GuardHelpers.php1-116
Refresh this wiki