Alpha ZealPHP is early-stage and under active development. APIs may change between minor versions until v1.0. Feedback and bug reports welcome on GitHub.
Esc
API Index — Namespaces, Packages, Reports, Indices

BasicAuthMiddleware
in package
implements MiddlewareInterface

HTTP Basic Auth Middleware

Validates an Authorization: Basic <base64(user:pass)> header against either an htpasswd-formatted credentials file or a callback verifier. Sends 401 Unauthorized with WWW-Authenticate: Basic realm="..." when credentials are missing or invalid — browsers respond by prompting.

Apache equivalent: AuthType Basic AuthName "Restricted" AuthUserFile /etc/apache2/.htpasswd Require valid-user

nginx equivalent: auth_basic "Restricted"; auth_basic_user_file /etc/nginx/.htpasswd;

Supported htpasswd hash formats:

  • bcrypt ($2y$…) — htpasswd -B
  • APR1 ($apr1$…) — htpasswd -m (Apache default)
  • SHA-1 ({SHA}base64) — htpasswd -s (legacy; insecure, accepted)
  • crypt() (anything else) — htpasswd -d (legacy DES)

Plain text passwords are NEVER accepted from the file. An explicit prefix guard (M13) refuses any hash whose prefix is not one of the recognised schemes before crypt() is ever called — relying on accidental crypt() failure is not sufficient. Setting user:hunter2 literally in the file will not authenticate hunter2.

Usage in app.php:

// File-based
$app->addMiddleware(new \ZealPHP\Middleware\BasicAuthMiddleware(
    htpasswdFile: '/etc/zealphp/.htpasswd',
    realm:        'Admin Area',
));

// Callback-based (e.g. validate against your DB)
$app->addMiddleware(new \ZealPHP\Middleware\BasicAuthMiddleware(
    verify: fn(string $u, string $p): bool => User::verify($u, $p),
    realm:  'API',
));

Table of Contents

Interfaces

MiddlewareInterface

Properties

$htpasswdCache  : array<string, string>|null
$htpasswdFile  : string|null
$htpasswdMtime  : int|null
$realm  : string
$verify  : callable|null

Methods

__construct()  : mixed
process()  : ResponseInterface
challenge()  : ResponseInterface
crypt_apr1_md5()  : string
APR1 (Apache MD5) reimplementation. PHP's crypt() doesn't support $apr1$.
loadHtpasswd()  : array<string, string>|null
Parse an htpasswd file (user:hash per line, # comments, blank lines).
parseAuthorization()  : array{0: string, 1: string}|null
verifyCredentials()  : bool
verifyHtpasswd()  : bool

Properties

$htpasswdCache

private array<string, string>|null $htpasswdCache = null

user => hash, lazily parsed from $htpasswdFile

Methods

__construct()

public __construct([string|null $htpasswdFile = null ][, callable|null $verify = null ][, string $realm = 'Restricted' ]) : mixed
Parameters
$htpasswdFile : string|null = null

Path to an htpasswd-formatted file

$verify : callable|null = null

Alternative: fn(string $user, string $pass): bool

$realm : string = 'Restricted'

Realm name shown in browser prompt

process()

public process(ServerRequestInterface $request, RequestHandlerInterface $handler) : ResponseInterface
Parameters
$request : ServerRequestInterface
$handler : RequestHandlerInterface
Return values
ResponseInterface

challenge()

private challenge() : ResponseInterface
Return values
ResponseInterface

crypt_apr1_md5()

APR1 (Apache MD5) reimplementation. PHP's crypt() doesn't support $apr1$.

private crypt_apr1_md5(string $password, string $hashOrSalt) : string

Algorithm reference: Apache's apr_md5_encode.c.

Parameters
$password : string
$hashOrSalt : string
Return values
string

loadHtpasswd()

Parse an htpasswd file (user:hash per line, # comments, blank lines).

private loadHtpasswd() : array<string, string>|null

Re-reads on mtime change so live edits work in dev without restarts.

Return values
array<string, string>|null

parseAuthorization()

private parseAuthorization(string $header) : array{0: string, 1: string}|null
Parameters
$header : string
Return values
array{0: string, 1: string}|null

verifyCredentials()

private verifyCredentials(string $user, string $pass) : bool
Parameters
$user : string
$pass : string
Return values
bool

verifyHtpasswd()

private verifyHtpasswd(string $user, string $pass) : bool
Parameters
$user : string
$pass : string
Return values
bool
On this page