Mezzio Authentication

https://github.com/mezzio/mezzio-authentication
Admin
Mezzio Authentication provides PSR-15 middleware and user repository interfaces for authenticating...
Tokens:24,725
Snippets:383
Trust Score:7.5
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Constructor Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-middleware.md

Example of instantiating the AuthenticationMiddleware with an authentication adapter.

```php
use Mezzio\Authentication\AuthenticationMiddleware;
use SomePackage\BasicAuthentication;

$authentication = new BasicAuthentication(/* config */);
$middleware = new AuthenticationMiddleware($authentication);
```

--------------------------------

### Container Integration Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-middleware.md

Example of piping the AuthenticationMiddleware into the Mezzio application pipeline.

```php
// In your Mezzio application configuration
use Mezzio\Authentication\AuthenticationMiddleware;

$app->pipe(AuthenticationMiddleware::class);
```

--------------------------------

### PdoDatabase Initialization Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

An example showing how to instantiate the PdoDatabase repository with a PDO connection, configuration array, and user factory.

```php
use Mezzio\Authentication\UserRepository\PdoDatabase;
use PDO;

$pdo = new PDO('sqlite::memory:');

$config = [
    'table' => 'users',
    'field' => [
        'identity' => 'username',
        'password' => 'password_hash',
    ],
    'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
    'sql_get_details' => 'SELECT * FROM user_profiles WHERE username = :identity',
];

$userFactory = fn($identity, $roles = [], $details = []) => 
    new DefaultUser($identity, $roles, $details);

$repository = new PdoDatabase($pdo, $config, $userFactory);
```

--------------------------------

### AuthenticationMiddlewareFactory Configuration Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example configuration for registering the AuthenticationInterface and AuthenticationMiddleware in config/autoload/authentication.global.php.

```php
// config/autoload/authentication.global.php
use Mezzio\Authentication\AuthenticationMiddleware;
use SomePackage\BasicAuthentication;

return [
    'dependencies' => [
        'factories' => [
            AuthenticationInterface::class => BasicAuthenticationFactory::class,
            AuthenticationMiddleware::class => AuthenticationMiddlewareFactory::class,
        ],
    ],
];
```

--------------------------------

### PostgreSQL DSN Examples

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Examples of DSN strings for connecting to PostgreSQL databases.

```php
'dsn' => 'pgsql:host=localhost;dbname=myapp'
'dsn' => 'pgsql:host=db.example.com;port=5432;dbname=users'
```

--------------------------------

### authenticate() Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-interface.md

Example showing how to use the authenticate method to verify a user.

```php
// Implementation would authenticate based on request contents
$user = $authentication->authenticate($request);
if ($user instanceof UserInterface) {
    echo "Authenticated as: " . $user->getIdentity();
} else {
    echo "Authentication failed";
}
```

--------------------------------

### MySQL DSN Examples

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Examples of DSN strings for connecting to MySQL databases.

```php
'dsn' => 'mysql:host=localhost;dbname=myapp'
'dsn' => 'mysql:host=db.example.com:3306;dbname=users'
```

--------------------------------

### Htpasswd Authentication Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example of retrieving the Htpasswd repository from the container and authenticating a user.

```php
use Mezzio\Authentication\UserRepository\Htpasswd;

$htpasswd = $container->get(Htpasswd::class);
$user = $htpasswd->authenticate('john', 'mypassword');
```

--------------------------------

### Example Htpasswd Configuration File

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

A sample configuration file typically stored in config/autoload/.

```php
// config/autoload/authentication.local.php
return [
    'authentication' => [
        'htpasswd' => '/var/www/myapp/.htpasswd',
    ],
];
```

--------------------------------

### Creating DefaultUser Instances

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

Examples of instantiating DefaultUser with identity, roles, and optional details.

```php
use Mezzio\Authentication\DefaultUser;

// Basic user with only identity
$user = new DefaultUser('john@example.com');

// User with roles
$user = new DefaultUser('john@example.com', ['user', 'admin']);

// User with roles and details
$user = new DefaultUser(
    'john@example.com',
    ['user', 'admin'],
    [
        'email' => 'john@example.com',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'department' => 'Engineering',
    ]
);
```

--------------------------------

### PdoDatabase Authentication Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example of retrieving the PdoDatabase service and authenticating a user.

```php
use Mezzio\\Authentication\\UserRepository\\PdoDatabase;

$pdo = $container->get(PdoDatabase::class);
$user = $pdo->authenticate('john@example.com', 'password123');
```

--------------------------------

### SQLite DSN Examples

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Examples of DSN strings for connecting to SQLite databases.

```php
'dsn' => 'sqlite:/var/lib/users.db'
'dsn' => 'sqlite::memory:'
```

--------------------------------

### PdoDatabase Configuration with Inline PDO

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Configuration example using an inline PDO connection string.

```php
// config/autoload/authentication.local.php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => 'mysql:host=localhost;dbname=myapp',
            'username' => 'user',
            'password' => 'pass',
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
            'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
            'sql_get_details' => 'SELECT * FROM user_profiles WHERE username = :identity',
        ],
    ],
];
```

--------------------------------

### Instantiating Htpasswd repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/htpasswd-repository.md

Example showing how to instantiate the Htpasswd repository with a user factory and handle potential configuration errors.

```php
use Mezzio\Authentication\UserRepository\Htpasswd;
use Mezzio\Authentication\DefaultUser;

$userFactory = fn($identity, $roles = [], $details = []) => 
    new DefaultUser($identity, $roles, $details);

try {
    $repository = new Htpasswd('/etc/apache2/htpasswd', $userFactory);
} catch (InvalidConfigException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Process Method Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-middleware.md

Example of accessing the authenticated user from the request attribute within a handler.

```php
use Mezzio\Authentication\AuthenticationMiddleware;
use Mezzio\Authentication\UserInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

// Assuming middleware is already in the pipeline
// In your handler code:
public function handle(ServerRequestInterface $request): ResponseInterface
{
    $user = $request->getAttribute(UserInterface::class);
    
    if ($user instanceof UserInterface) {
        return $this->successResponse("Welcome, " . $user->getIdentity());
    } else {
        // This shouldn't happen if middleware is properly configured
        // because the request would not reach here if unauthenticated
        return $this->failureResponse();
    }
}
```

--------------------------------

### Install mezzio-authentication via Composer

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/index.md

Use this command to add the mezzio-authentication library to your project dependencies.

```bash
$ composer require mezzio/mezzio-authentication
```

--------------------------------

### UserRepositoryInterface Usage Patterns

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-repository-interface.md

Examples demonstrating password-based authentication, token-based authentication, and exception handling for configuration or runtime errors.

```php
// Password-based authentication
$user = $repository->authenticate('john@example.com', 'secretpassword');
if ($user instanceof UserInterface) {
    echo "Authenticated: " . $user->getIdentity();
} else {
    echo "Authentication failed";
}

// Token-based authentication (password omitted)
$user = $repository->authenticate('auth_token_here');
if ($user instanceof UserInterface) {
    echo "Token valid for: " . $user->getIdentity();
}

// Error handling
try {
    $user = $repository->authenticate($credential, $password);
} catch (InvalidConfigException $e) {
    // Configuration error - check setup
    error_log("Repository config error: " . $e->getMessage());
} catch (RuntimeException $e) {
    // Runtime error - database or file access issues
    error_log("Repository error: " . $e->getMessage());
}
```

--------------------------------

### getDetails() Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-interface.md

Retrieving and iterating over all available user details.

```php
$user = $request->getAttribute(UserInterface::class);
$allDetails = $user->getDetails();

// Typical structure
foreach ($allDetails as $key => $value) {
    echo "$key: " . json_encode($value);
}

// Example output might be:
// email: "john@example.com"
// first_name: "John"
// last_name: "Doe"
// department: "Engineering"
```

--------------------------------

### SQL query for getUserRoles

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

Example SQL queries for the sql_get_roles configuration, which must return the role name as the first column.

```sql
-- Single role per row (recommended)
SELECT role FROM user_roles WHERE username = :identity

-- Alternative: comma-separated roles in single column
SELECT role FROM user_roles WHERE username = :identity
```

--------------------------------

### ConfigProvider __invoke Usage

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example of invoking the ConfigProvider instance to retrieve the configuration array.

```php
$provider = new ConfigProvider();
$config = $provider(); // Returns complete config array
```

--------------------------------

### Merging ConfigProvider with Base Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example of manually merging the ConfigProvider configuration with an existing base configuration.

```php
$provider = new ConfigProvider();
$config = array_merge(
    $baseConfig,
    $provider()
);
```

--------------------------------

### Authentication Template Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example structure for the authentication configuration template, which can be overridden with adapter-specific settings.

```php
[
    'authentication' => [
        'htpasswd' => 'path/to/.htpasswd',
        // OR
        'pdo' => [
            'dsn' => '...',
            'username' => '...',
            'password' => '...',
            'table' => '...',
            'field' => [...],
            'sql_get_roles' => '...',
            'sql_get_details' => '...',
        ],
    ],
]
```

--------------------------------

### SQL query for getUserDetails

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

Example SQL query for the sql_get_details configuration, which must return results as an associative array.

```sql
SELECT user_id, email, first_name, last_name, department 
FROM user_profiles 
WHERE username = :identity
```

--------------------------------

### Serialization Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

Serializing the user object to JSON for storage or caching.

```php
$user = new DefaultUser(
    'user123',
    ['admin'],
    ['email' => 'user@example.com']
);

// Serializable
$json = json_encode([
    'identity' => $user->getIdentity(),
    'roles' => $user->getRoles(),
    'details' => $user->getDetails(),
]);
```

--------------------------------

### Handle Authentication Errors

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Example of catching authentication exceptions and handling invalid credentials.

```php
try {
    $user = $repository->authenticate($credential, $password);
    if ($user === null) {
        // Authentication failed (expected)
        echo "Invalid credentials";
    }
} catch (InvalidConfigException $e) {
    // Configuration error
    error_log("Config: " . $e->getMessage());
} catch (RuntimeException $e) {
    // System error
    error_log("Error: " . $e->getMessage());
}
```

--------------------------------

### unauthorizedResponse() Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-interface.md

Example showing how to retrieve the status code from an unauthorized response.

```php
$response = $authentication->unauthorizedResponse($request);
echo $response->getStatusCode(); // e.g., 401 or 403
```

--------------------------------

### Define Environment Variables in .env

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Example of defining database environment variables in a .env file.

```text
// .env
DB_DSN=mysql:host=localhost;dbname=myapp
DB_USER=dbuser
DB_PASS=dbpass
```

--------------------------------

### Registering ConfigProvider in config.php

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Example of registering the ConfigProvider class within the application configuration file.

```php
// config/config.php
use Mezzio\Authentication\ConfigProvider;

return [
    ConfigProvider::class,
];
```

--------------------------------

### getDetail() Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-interface.md

Retrieving user details with optional default values.

```php
$user = $request->getAttribute(UserInterface::class);

// Get a detail with default
$email = $user->getDetail('email', 'unknown@example.com');

// Custom user properties
$department = $user->getDetail('department');
if ($department === null) {
    echo "No department assigned";
} else {
    echo "Department: " . $department;
}
```

--------------------------------

### getRoles() Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-interface.md

Iterating through user roles and checking for specific permissions.

```php
$user = $request->getAttribute(UserInterface::class);
$roles = $user->getRoles();

foreach ($roles as $role) {
    echo "Role: " . $role;
}

// Common role usage
if (in_array('admin', $roles)) {
    // Admin-specific logic
}
```

--------------------------------

### Catching InvalidConfigException

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/errors.md

Example of catching an InvalidConfigException when a factory fails due to incomplete configuration.

```php
use Mezzio\Authentication\Exception\InvalidConfigException;
use Mezzio\Authentication\UserRepository\PdoDatabaseFactory;

$factory = new PdoDatabaseFactory();
try {
    $repo = $factory($container); // $container has incomplete PDO config
} catch (InvalidConfigException $e) {
    echo "Config error: " . $e->getMessage();
    // Possible outputs:
    // - "PDO values are missing in authentication config"
    // - "The PDO table name is missing in the configuration"
    // - "The PDO identity field is missing in the configuration"
    // - "The PDO password field is missing in the configuration"
    // - "The sql_get_roles configuration setting must include an :identity parameter"
    // - "The sql_get_details configuration setting must include a :identity parameter"
}
```

--------------------------------

### Handling RuntimeException in Htpasswd Repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/errors.md

Example of catching a RuntimeException when initializing an Htpasswd repository with an inaccessible file.

```php
use Mezzio\Authentication\Exception\RuntimeException;
use Mezzio\Authentication\UserRepository\Htpasswd;

try {
    $repository = new Htpasswd('/nonexistent/.htpasswd', $userFactory);
} catch (RuntimeException $e) {
    echo "Error: " . $e->getMessage();
    // Output: "I cannot access the htpasswd file /nonexistent/.htpasswd"
}
```

--------------------------------

### Common webmozart/assert type assertions

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/types.md

Examples of type assertions used for constructor parameter validation, including checks for array elements, associative arrays, and non-empty strings.

```php
// In constructor parameter validation
Assert::allString($roles);           // Verify all array elements are strings
Assert::isMap($details);             // Verify array is associative (string keys)
Assert::nullOrIsInstanceOf(...);     // Verify type or null
Assert::stringNotEmpty($hash);       // Verify non-empty string
```

--------------------------------

### Authenticate user with Htpasswd repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/htpasswd-repository.md

Demonstrates how to initialize the Htpasswd repository and perform authentication checks for successful, failed, and non-existent user scenarios.

```php
use Mezzio\Authentication\UserRepository\Htpasswd;

$repository = new Htpasswd('/etc/htpasswd', $userFactory);

// Successful authentication
$user = $repository->authenticate('john', 'mypassword');
if ($user instanceof UserInterface) {
    echo "Logged in as: " . $user->getIdentity();
}

// Failed authentication
$user = $repository->authenticate('john', 'wrongpassword');
if ($user === null) {
    echo "Invalid credentials";
}

// User not found
$user = $repository->authenticate('nonexistent', 'password');
if ($user === null) {
    echo "User not found";
}
```

--------------------------------

### PDO Connection and Constructor Usage

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/types.md

Demonstrates direct instantiation of the PDO class and its expected injection into the PdoDatabase constructor.

```php
// Direct usage
$pdo = new PDO(
    'mysql:host=localhost;dbname=myapp',
    'username',
    'password'
);

// In PdoDatabase
public function __construct(PDO $pdo, array $config, callable $userFactory)
```

--------------------------------

### getIdentity() Usage Example

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-interface.md

Retrieving the user identity from the request attribute.

```php
$user = $request->getAttribute(UserInterface::class);
$userId = $user->getIdentity(); // "john@example.com" or "12345"
echo "User: " . $userId;
```

--------------------------------

### Catching Specific Authentication Exceptions

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/errors.md

Demonstrates how to handle InvalidConfigException and RuntimeException separately when initializing the repository.

```php
use Mezzio\Authentication\Exception\InvalidConfigException;
use Mezzio\Authentication\Exception\RuntimeException;

try {
    $repository = $factory($container);
} catch (InvalidConfigException $e) {
    // Configuration error - check application setup
    error_log("Config problem: " . $e->getMessage());
    die("Authentication not configured properly");
} catch (RuntimeException $e) {
    // System error - may be transient
    error_log("Runtime error: " . $e->getMessage());
    // Could retry or fallback
}
```

--------------------------------

### Configure Authentication via Environment Variables

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Use environment variables in config/autoload/authentication.local.php to configure database settings.

```php
// config/autoload/authentication.local.php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => getenv('DB_DSN'),
            'username' => getenv('DB_USER'),
            'password' => getenv('DB_PASS'),
            'table' => getenv('DB_TABLE'),
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
        ],
    ],
];
```

--------------------------------

### Authenticate user with PdoDatabase

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

Demonstrates how to instantiate the PdoDatabase repository and use the authenticate method to verify credentials, handle successful logins, and catch potential exceptions.

```php
use Mezzio\\\Authentication\\\UserRepository\\\PdoDatabase;

$repository = new PdoDatabase($pdo, $config, $userFactory);

// Successful authentication with roles and details
$user = $repository->authenticate('john@example.com', 'password123');
if ($user instanceof UserInterface) {
    echo "User: " . $user->getIdentity();
    echo "Roles: " . implode(', ', $user->getRoles());
    echo "Email: " . $user->getDetail('email');
}

// Failed authentication
$user = $repository->authenticate('john@example.com', 'wrongpassword');
if ($user === null) {
    echo "Invalid credentials";
}

// Error handling
try {
    $user = $repository->authenticate($credential, $password);
} catch (RuntimeException $e) {
    error_log("Database error: " . $e->getMessage());
} catch (InvalidConfigException $e) {
    error_log("Config error: " . $e->getMessage());
}
```

--------------------------------

### Create .htpasswd File

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Use the htpasswd command-line utility to create a new .htpasswd file with bcrypt encryption.

```bash
htpasswd -B -c .htpasswd username
```

--------------------------------

### Configure Htpasswd repository in authentication.local.php

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/htpasswd-repository.md

Register the Htpasswd repository by defining the path to the htpasswd file within the authentication configuration.

```php
// config/autoload/authentication.local.php
return [
    'authentication' => [
        'htpasswd' => '/path/to/htpasswd',
    ],
];
```

--------------------------------

### PDOException Handling

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/types.md

Shows how to catch database preparation errors using the PDOException class.

```php
try {
    $stmt = $pdo->prepare($sql);
} catch (PDOException $e) {
    // Database preparation error
}
```

--------------------------------

### Factory Usage

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

Creating a user instance via the DefaultUserFactory.

```php
$userFactory = $container->get(UserInterface::class);
$user = $userFactory('john@example.com', ['user'], ['email' => 'john@example.com']);
```

--------------------------------

### Handling Authentication Exceptions

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

Demonstrates how to catch InvalidConfigException for configuration issues and RuntimeException for database-related failures when calling the authenticate method.

```php
try {
    $user = $repository->authenticate($credential, $password);
} catch (InvalidConfigException $e) {
    // Missing required configuration
    // - table, field.identity, field.password
    // - missing :identity in SQL queries
    error_log("Config error: " . $e->getMessage());
} catch (RuntimeException $e) {
    // Database errors
    // - connection failure
    // - query preparation failed
    // - query execution failed
    error_log("Database error: " . $e->getMessage());
}
```

--------------------------------

### AuthenticationMiddleware::__construct

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-middleware.md

Creates a new instance of the AuthenticationMiddleware with a specific authentication adapter.

```APIDOC
## __construct(AuthenticationInterface $auth)

### Description
Create a new authentication middleware with the specified authentication adapter.

### Parameters
- **$auth** (AuthenticationInterface) - Required - The authentication adapter implementation

### Example
```php
use Mezzio\Authentication\AuthenticationMiddleware;
use SomePackage\BasicAuthentication;

$authentication = new BasicAuthentication(/* config */);
$middleware = new AuthenticationMiddleware($authentication);
```
```

--------------------------------

### Service Configuration for UserInterface

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/intro.md

Mapping the UserInterface service to a factory in the Mezzio dependency configuration.

```php
use Mezzio\Authentication\DefaultUserFactory;
use Mezzio\Authentication\UserInterface;

return [
    // ...
    'dependencies' => [
        'factories' => [
            // ...
            // Change the DefaultUserFactory::class with your custom service
            // factory that produces a user factory:
            UserInterface::class => DefaultUserFactory::class
        ]
    ]
];
```

--------------------------------

### Project Configuration Structure

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

The typical directory structure for Mezzio authentication configuration files within the config/autoload directory.

```text
config/
├── autoload/
│   ├── authentication.global.php      # Factories and defaults
│   ├── authentication.local.php.dist  # Template for local config
│   ├── authentication.local.php       # Local config (in .gitignore)
│   └── ...
├── config.php                         # Main config aggregator
├── pipeline.php                       # Middleware pipeline
└── routes.php                         # Route configuration
```

--------------------------------

### Minimal htpasswd Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Configure the authentication adapter to use an htpasswd file by specifying the path in the authentication configuration array.

```php
// config/autoload/authentication.local.php
return [
    'authentication' => [
        'htpasswd' => '/path/to/.htpasswd',
    ],
];
```

--------------------------------

### Generate and Verify Password Hashes

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Demonstrates using password_hash and password_verify for secure password management, along with the command-line syntax for creating htpasswd files.

```php
// Generate bcrypt hash
$password = 'user_password';
$hash = password_hash($password, PASSWORD_BCRYPT, ['cost' => 10]);

// Verify password
if (password_verify($password, $hash)) {
    echo "Password matches";
}

// Command line for htpasswd files
// htpasswd -B -c .htpasswd username
```

--------------------------------

### Global Authentication Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

The authentication.global.php file registers the authentication ConfigProvider.

```php
// Global/default configuration
use Mezzio\Authentication\ConfigProvider;

return [
    ConfigProvider::class,
];
```

--------------------------------

### Catching Authentication Exceptions

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/errors.md

Demonstrates how to catch all authentication-specific exceptions using the ExceptionInterface.

```php
try {
    // Some authentication operation
} catch (ExceptionInterface $e) {
    // Handle all mezzio-authentication errors
    error_log("Auth error: " . $e->getMessage());
}
```

--------------------------------

### Configure Htpasswd Repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Configuration settings for the Htpasswd authentication repository.

```php
'authentication' => [
    'htpasswd' => '/path/to/.htpasswd',
]
```

--------------------------------

### Configure htpasswd user repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/user-repository.md

Requires the path to the htpasswd file and a realm. The htpasswd file must use the bcrypt hash algorithm.

```php
return [
    'authentication' => [
        'realm' => 'insert realm value',
        'htpasswd' => 'insert the path to htpasswd file',
    ],
];
```

--------------------------------

### Instantiate DefaultUser

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Create an instance of the built-in DefaultUser implementation.

```php
$user = new DefaultUser(
    'john@example.com',
    ['admin', 'user'],
    ['email' => 'john@example.com', 'department' => 'Engineering']
);
```

--------------------------------

### Constructor Signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-middleware.md

The signature for the AuthenticationMiddleware constructor.

```php
public function __construct(AuthenticationInterface $auth)
```

--------------------------------

### Configure PDO Authentication with DSN

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

Register the PDO authentication adapter using a DSN string in your configuration file.

```php
// config/autoload/authentication.local.php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => 'mysql:host=localhost;dbname=myapp',
            'username' => 'db_user',
            'password' => 'db_password',
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
            'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
            'sql_get_details' => 'SELECT * FROM user_profiles WHERE username = :identity',
        ],
    ],
];
```

--------------------------------

### Add User to Htpasswd File

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Command to add a new user to an existing htpasswd file.

```bash
htpasswd -B /path/to/.htpasswd newusername
```

--------------------------------

### Database Schema for Users, Roles, and Profiles

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Defines the SQL tables for storing user credentials, roles, and profile details, along with sample data insertion.

```sql
-- Users table (main authentication)
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- User roles (many-to-many)
CREATE TABLE user_roles (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(255) NOT NULL,
    role VARCHAR(100) NOT NULL,
    FOREIGN KEY (username) REFERENCES users(username),
    UNIQUE(username, role)
);

-- User profiles (one-to-one details)
CREATE TABLE user_profiles (
    username VARCHAR(255) PRIMARY KEY,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    email VARCHAR(255),
    department VARCHAR(100),
    FOREIGN KEY (username) REFERENCES users(username)
);

-- Insert sample data
INSERT INTO users (username, password_hash) VALUES
('john', '$2y$10$...bcrypt_hash...'),
('jane', '$2y$10$...bcrypt_hash...');

INSERT INTO user_roles (username, role) VALUES
('john', 'user'),
('john', 'admin'),
('jane', 'user');

INSERT INTO user_profiles (username, first_name, last_name, email, department) VALUES
('john', 'John', 'Doe', 'john@example.com', 'Engineering'),
('jane', 'Jane', 'Smith', 'jane@example.com', 'Sales');
```

--------------------------------

### Configure Authentication Settings

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/types.md

The authentication configuration key holds repository-specific settings for providers like Htpasswd or PdoDatabase.

```php
// For Htpasswd
array{
    'htpasswd'?: string,
}

// For PdoDatabase
array{
    'pdo'?: array{
        'dsn'?: string,
        'username'?: string,
        'password'?: string,
        'service'?: string,
        'table': string,
        'field': array{
            'identity': string,
            'password': string,
        },
        'sql_get_roles'?: string,
        'sql_get_details'?: string,
    },
}
```

--------------------------------

### Configure PDO user repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/user-repository.md

Requires dsn, table, and field parameters. Username and password are optional depending on the database.

```php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => '',
            'username' => '',
            'password' => '',
            'table' => 'user table name',
            'field' => [
                'identity' => 'identity field name',
                'password' => 'password field name',
            ],
            'sql_get_roles'   => 'SQL to retrieve roles with :identity parameter',
            'sql_get_details' => 'SQL to retrieve user details by :identity',
        ],
    ],
];
```

--------------------------------

### Constructor signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/htpasswd-repository.md

The signature for the Htpasswd constructor.

```php
public function __construct(string $filename, callable $userFactory)
```

--------------------------------

### Authenticate User with PdoDatabase

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Demonstrates how to retrieve the PdoDatabase service from the container and authenticate a user, accessing their identity, roles, and profile details.

```php
$pdo = $container->get(PdoDatabase::class);
$user = $pdo->authenticate('john@example.com', 'password123');

if ($user instanceof UserInterface) {
    echo "Identity: " . $user->getIdentity();
    echo "Roles: " . implode(', ', $user->getRoles());
    echo "Email: " . $user->getDetail('email');
}
```

--------------------------------

### Constructor Signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

The signature for the DefaultUser constructor.

```php
public function __construct(
    string $identity,
    array $roles = [],
    array $details = []
)
```

--------------------------------

### authenticate(string $credential, ?string $password)

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/htpasswd-repository.md

Authenticates a user by username and password against an htpasswd file.

```APIDOC
## authenticate(string $credential, ?string $password)

### Description
Authenticates a user by username and password against the htpasswd file. Returns an authenticated user if credentials match, or null if the username is not found or the password does not match.

### Signature
`public function authenticate(string $credential, ?string $password = null): ?UserInterface`

### Parameters
- **$credential** (string) - Required - The username to authenticate
- **$password** (string) - Optional - The password to verify

### Return Type
- **?UserInterface** - Returns authenticated user if credentials match, otherwise null.

### Throws
- **RuntimeException** - If htpasswd file uses non-bcrypt hash algorithm.
```

--------------------------------

### Register ConfigProvider in application configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Shows how to include the ConfigProvider class in the application's configuration array to register default factories.

```php
use Mezzio\\Authentication\\ConfigProvider;

return [
    ConfigProvider::class,
];
```

--------------------------------

### Configure PDO Authentication with Container Service

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Uses a container service name for the PDO instance and defines the factory in the dependencies configuration.

```php
return [
    'authentication' => [
        'pdo' => [
            'service' => 'Pdo', // Container service name
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
        ],
    ],
    'dependencies' => [
        'factories' => [
            'Pdo' => function($container) {
                return new PDO('mysql:host=localhost;dbname=myapp', 'user', 'pass');
            },
        ],
    ],
];
```

--------------------------------

### HtpasswdFactory::__invoke

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Creates an instance of the Htpasswd user repository using the provided PSR container.

```APIDOC
## HtpasswdFactory::__invoke

### Description
Creates an htpasswd repository instance from configuration stored in the container.

### Signature
`public function __invoke(ContainerInterface $container): Htpasswd`

### Parameters
- **$container** (Psr\Container\ContainerInterface) - Required - The PSR container instance.

### Return Type
`Mezzio\Authentication\UserRepository\Htpasswd`

### Throws
- `InvalidConfigException` - If configuration is missing or the htpasswd file is not found.

### Container Requirements
- Must have `config` service (array with `authentication.htpasswd` key).
- Must have `UserInterface` service (user factory callable).
```

--------------------------------

### DefaultUser Serialization and Deserialization

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/types.md

Illustrates how to serialize a DefaultUser instance to JSON and reconstruct it later, which is recommended for session storage.

```php
// Serialize to JSON
$json = json_encode([
    'identity' => $user->getIdentity(),
    'roles' => $user->getRoles(),
    'details' => $user->getDetails(),
]);

// Later deserialize
$data = json_decode($json, true);
$user = new DefaultUser(
    $data['identity'],
    $data['roles'],
    $data['details']
);
```

--------------------------------

### Handle Authentication Failures

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Invalid credentials return null instead of throwing an exception. Check for null to identify when credentials do not match.

```php
$user = $repository->authenticate($credential, $password);

if ($user === null) {
    // Expected: credentials didn't match
    echo "Invalid credentials";
}
```

--------------------------------

### Configure PdoDatabase Repository

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Configuration settings for the PdoDatabase authentication repository, including DSN, credentials, and SQL queries.

```php
'authentication' => [
    'pdo' => [
        'dsn' => 'mysql:host=localhost;dbname=myapp',
        'username' => 'user',
        'password' => 'pass',
        'table' => 'users',
        'field' => [
            'identity' => 'username',
            'password' => 'password_hash',
        ],
        'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
        'sql_get_details' => 'SELECT * FROM user_profiles WHERE username = :identity',
    ],
]
```

--------------------------------

### Minimal PDO Database Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Configure the authentication adapter to use a PDO database connection by providing the DSN, credentials, table name, and field mapping for identity and password hash.

```php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => 'mysql:host=localhost;dbname=myapp',
            'username' => 'user',
            'password' => 'pass',
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
        ],
    ],
];
```

--------------------------------

### Immutability Demonstration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

DefaultUser is immutable; properties cannot be modified directly. Create a new instance to update user data.

```php
$user = new DefaultUser('john');

// This would fail at runtime (property is readonly)
// $user->identity = 'jane'; // TypeError

// Create a new user instead
$newUser = new DefaultUser('jane', $user->getRoles(), $user->getDetails());
```

--------------------------------

### Local Authentication Configuration Template

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

The authentication.local.php.dist file serves as a template for local environment settings, such as PDO database credentials.

```php
// Template for local configuration (copy to authentication.local.php)
return [
    'authentication' => [
        'pdo' => [
            'dsn' => 'mysql:host=localhost;dbname=myapp',
            'username' => 'user',
            'password' => 'pass',
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
            'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
        ],
    ],
];
```

--------------------------------

### Configure PDO Authentication with Existing Service

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

Register the PDO authentication adapter by referencing an existing PDO service name from the container.

```php
return [
    'authentication' => [
        'pdo' => [
            'service' => 'Pdo', // Container service name
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
            'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
        ],
    ],
];
```

--------------------------------

### Implement Custom User

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Create a custom user class by implementing the UserInterface.

```php
class MyUser implements UserInterface
{
    public function __construct(
        private string $identity,
        private array $roles = [],
        private array $details = []
    ) {}
    
    public function getIdentity(): string { return $this->identity; }
    public function getRoles(): iterable { return $this->roles; }
    public function getDetail(string $name, $default = null) {
        return $this->details[$name] ?? $default;
    }
    public function getDetails(): array { return $this->details; }
}
```

--------------------------------

### PdoDatabase Constructor Signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/pdo-database-repository.md

The constructor signature for initializing the PdoDatabase repository.

```php
public function __construct(
    PDO $pdo,
    array $config,
    callable $userFactory
)
```

--------------------------------

### Configure PDO service name

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/user-repository.md

Use the service key instead of dsn to provide a service name that resolves to a PDO instance. Requires table and field parameters.

```php
return [
    'authentication' => [
        'pdo' => [
            'service' => \PDO::class,                 // "service" instead of "dsn"
            'table' => 'user table name',
            'field' => [
                'identity' => 'identity field name',
                'password' => 'password field name',
            ],
            'sql_get_roles'   => 'SQL to retrieve roles with :identity parameter',
            'sql_get_details' => 'SQL to retrieve user details by :identity',
        ],
    ],
];
```

--------------------------------

### Handle System Errors

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Configuration and runtime errors throw exceptions. Use try-catch blocks to handle InvalidConfigException and RuntimeException.

```php
try {
    $user = $repository->authenticate($credential, $password);
} catch (InvalidConfigException $e) {
    // Configuration is wrong - check setup
    error_log("Config: " . $e->getMessage());
} catch (RuntimeException $e) {
    // System error - may be transient
    error_log("Error: " . $e->getMessage());
}
```

--------------------------------

### Minimal PDO Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

The basic configuration required to authenticate users against a relational database using PDO.

```php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => 'mysql:host=localhost;dbname=myapp',
            'username' => 'dbuser',
            'password' => 'dbpass',
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
        ],
    ],
];
```

--------------------------------

### Configure authentication services with laminas-servicemanager

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/intro.md

Use service container aliases to map AuthenticationInterface and UserRepositoryInterface to specific implementations like BasicAccess and Htpasswd.

```php
use Mezzio\Authentication\AuthenticationInterface;
use Mezzio\Authentication\Basic;
use Mezzio\Authentication\UserRepository;
use Mezzio\Authentication\UserRepositoryInterface;

return [
    // ...
    'dependencies' => [
        // ...
        'aliases' => [
            // ...
            AuthenticationInterface::class => Basic\BasicAccess::class,
            UserRepositoryInterface::class => UserRepository\Htpasswd::class
        ]
    ]
];
```

--------------------------------

### Handling Authentication Failures vs Exceptions

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/errors.md

Distinguishes between invalid credentials, which return null, and system errors, which throw exceptions.

```php
// Returns null (not an exception)
$user = $repository->authenticate($credential, $wrongPassword);
if ($user === null) {
    echo "Invalid credentials"; // Expected scenario
}

// Throws exception (unexpected system error)
try {
    $user = $repository->authenticate($credential, $password);
} catch (RuntimeException $e) {
    error_log("Database error: " . $e->getMessage()); // Unexpected
}
```

--------------------------------

### Standard Apache htpasswd file format

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/htpasswd-repository.md

The repository expects a standard Apache htpasswd file format where each line contains a username, a colon separator, and a Bcrypt password hash.

```text
username:$2y$10$encrypted_password_hash
john:$2y$10$encrypted_password_hash
jane:$2y$10$encrypted_password_hash
```

--------------------------------

### sql_get_details Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Configuration for the SQL query used to retrieve user details, including the expected associative array result format.

```php
'sql_get_details' => 'SELECT id, email, first_name, last_name, department FROM user_profiles WHERE username = :identity'

// Result format (for user 'john'):
// [
//     'id' => '123',
//     'email' => 'john@example.com',
//     'first_name' => 'John',
//     'last_name' => 'Doe',
//     'department' => 'Engineering',
// ]
```

--------------------------------

### Class Definition

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/authentication-middleware.md

The class structure for AuthenticationMiddleware implementing MiddlewareInterface.

```php
final class AuthenticationMiddleware implements MiddlewareInterface
{
    public function __construct(AuthenticationInterface $auth)
    protected $auth;
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
}
```

--------------------------------

### Authentication Configuration Structure

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

The standard structure for authentication configuration within Mezzio/Laminas applications.

```php
return [
    'authentication' => [
        // Authentication configuration goes here
    ],
    'dependencies' => [
        'factories' => [
            // Factory registrations
        ],
    ],
];
```

--------------------------------

### getDetails() Method Signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-interface.md

The signature for retrieving all user details as an associative array.

```php
public function getDetails(): array
```

--------------------------------

### Register Authentication Middleware Pipeline

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/configuration.md

Register the authentication middleware in config/pipeline.php. It should be placed early in the pipeline.

```php
// config/pipeline.php
use Mezzio\Authentication\AuthenticationMiddleware;

return function(Application $app, MiddlewareFactory $factory): void {
    // Authentication middleware should be early in the pipeline
    $app->pipe(AuthenticationMiddleware::class);
    
    // Other middleware...
    $app->pipe(SomeOtherMiddleware::class);
};
```

--------------------------------

### Registering DefaultUserFactory

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Configuration to register the DefaultUserFactory in the service container.

```php
// config/autoload/authentication.global.php
use Mezzio\Authentication\UserInterface;
use Mezzio\
Authentication\DefaultUserFactory;

return [
    'dependencies' => [
        'factories' => [
            UserInterface::class => DefaultUserFactory::class,
        ],
    ],
];
```

--------------------------------

### Configure PDO Authentication with Inline Connection

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Configures PDO authentication by providing the DSN, credentials, and table mapping directly in the configuration.

```php
return [
    'authentication' => [
        'pdo' => [
            'dsn' => 'mysql:host=localhost;dbname=myapp',
            'username' => 'dbuser',
            'password' => 'dbpass',
            'table' => 'users',
            'field' => [
                'identity' => 'username',
                'password' => 'password_hash',
            ],
            'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
            'sql_get_details' => 'SELECT * FROM user_profiles WHERE username = :identity',
        ],
    ],
];
```

--------------------------------

### Namespace Declaration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-repository-interface.md

The namespace for the authentication repository interface.

```php
Mezzio\Authentication
```

--------------------------------

### ConfigProvider Class Definition

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

The class definition for ConfigProvider, outlining the available public methods.

```php
final class ConfigProvider
{
    public function __invoke(): array
    public function getAuthenticationConfig(): array
    public function getDependencies(): array
}
```

--------------------------------

### SQL query for retrieving user roles

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/user-repository.md

Optional SQL query for retrieving user roles using the :identity placeholder.

```sql
SELECT role FROM user WHERE username = :identity
```

--------------------------------

### SQL query for retrieving user details

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/user-repository.md

Optional SQL query for retrieving additional user details using the :identity placeholder.

```sql
SELECT email FROM user WHERE username = :identity
```

--------------------------------

### PdoDatabase Factory Registration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

Dependency configuration to register the PdoDatabaseFactory.

```php
// Automatically registered via ConfigProvider
use Mezzio\Authentication\UserRepository\PdoDatabase;
use Mezzio\Authentication\UserRepository\PdoDatabaseFactory;

return [
    'dependencies' => [
        'factories' => [
            PdoDatabase::class => PdoDatabaseFactory::class,
        ],
    ],
];
```

--------------------------------

### MiddlewareInterface Process Method

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/types.md

The PSR-15 MiddlewareInterface definition used by AuthenticationMiddleware.

```php
interface MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}
```

--------------------------------

### Mezzio Authentication Exception Hierarchy

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Visual representation of the exception inheritance tree for the authentication component.

```text
Throwable
  └─ Exception
       └─ RuntimeException
            └─ Mezzio\Authentication\Exception\RuntimeException
                 └─ Mezzio\Authentication\Exception\InvalidConfigException

Mezzio\Authentication\Exception\ExceptionInterface (marker)
```

--------------------------------

### getDetail() Usage

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

Retrieving a specific detail by key, with an optional default fallback value.

```php
$user = new DefaultUser('john', [], ['email' => 'john@example.com']);

$email = $user->getDetail('email'); // "john@example.com"
$phone = $user->getDetail('phone', 'N/A'); // "N/A"
$missing = $user->getDetail('nonexistent'); // null
```

--------------------------------

### Catch InvalidConfigException

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Handles errors related to missing or invalid configuration, such as unregistered interfaces or missing keys.

```php
try {
    $middleware = $factory($container);
} catch (InvalidConfigException $e) {
    // AuthenticationInterface not registered, missing config keys, etc.
}
```

--------------------------------

### Create Bcrypt Password Hash

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Generate a password hash using the PASSWORD_BCRYPT algorithm with a cost factor of 10.

```php
$hash = password_hash('password', PASSWORD_BCRYPT, ['cost' => 10]);
```

--------------------------------

### getDetails() Usage

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/default-user.md

Retrieving all user details as an associative array.

```php
$user = new DefaultUser('john', [], ['email' => 'john@example.com', 'age' => 30]);
$details = $user->getDetails();
// ['email' => 'john@example.com', 'age' => 30]
```

--------------------------------

### Configure Htpasswd Authentication

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Defines the path to the .htpasswd file within the authentication configuration array.

```php
return [
    'authentication' => [
        'htpasswd' => '/path/to/.htpasswd',
    ],
];
```

--------------------------------

### PdoDatabase Repository Configuration

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/README.md

Configuration required to use the PdoDatabase repository for authentication against a PDO-compatible database.

```php
'authentication' => [
    'pdo' => [
        'dsn' => 'mysql:host=localhost;dbname=myapp',
        'username' => 'user',
        'password' => 'pass',
        'table' => 'users',
        'field' => ['identity' => 'username', 'password' => 'password_hash'],
        'sql_get_roles' => 'SELECT role FROM user_roles WHERE username = :identity',
        'sql_get_details' => 'SELECT * FROM user_profiles WHERE username = :identity',
    ],
]
```

--------------------------------

### Secure a route with AuthenticationMiddleware

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/docs/book/v1/intro.md

Add the AuthenticationMiddleware class to the route pipeline to enforce authentication. If unauthenticated, the application returns a 401 Unauthorized response.

```php
$app->get('/admin/dashboard', [
    Mezzio\Authentication\AuthenticationMiddleware::class,
    Admin\Action\Dashboard::class
], 'admin.dashboard');
```

--------------------------------

### authenticate() Method Signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-repository-interface.md

The method signature for authenticating an identity.

```php
public function authenticate(string $credential, ?string $password = null): ?UserInterface
```

--------------------------------

### ConfigProvider __invoke Signature

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/factories.md

The signature for the __invoke method, which returns the complete configuration array.

```php
public function __invoke(): array
```

--------------------------------

### Register AuthenticationMiddleware in Pipeline

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/overview.md

Register the AuthenticationMiddleware in the Mezzio application middleware pipeline.

```php
use Mezzio\Authentication\AuthenticationMiddleware;

// Registered in middleware pipeline
$app->pipe(AuthenticationMiddleware::class);
```

--------------------------------

### getDetails()

Source: https://github.com/mezzio/mezzio-authentication/blob/1.14.x/_autodocs/api-reference/user-interface.md

Retrieves all user details as an associative array.

```APIDOC
### getDetails()

**Signature:** `public function getDetails(): array`

Returns an associative array of all user details. Returns an empty array if no details are available.
```
Tokens:
Raw