fyre/auth

An authentication and authorization library.

v2.0.1 2024-10-18 07:17 UTC

Requires

• fyre/error: ^4.0
• fyre/inflector: ^2.0
• fyre/middleware: ^2.1
• fyre/orm: ^8.0
• fyre/server: ^3.1
• fyre/session: ^4.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^10

MIT

• elusivecodes

README

FyreAuth is a free, open-source authentication/authorization library for PHP.

Table Of Contents

• Installation
• Auth
• Identity
• Access
• Policy Registry
• Policies
• Authenticators
  • Cookie
  • Session
  • Token
• Middleware

Installation

Using Composer

composer require fyre/auth

In PHP:

use Fyre\Auth\Auth;

Auth

The Auth class provides the basis for authentication.

$auth = new Auth();

Instance

Load a shared Auth instance.

$auth = Auth::instance();

Set Instance

Set a shared Auth instance.

• $instance is an Auth, or a Closure that returns an Auth.

Auth::setInstance($instance);

Auth Methods

Add Authenticator

• $authenticator is an Authenticator.
• $key is a string representing the authenticator key, and will default to the Authenticator class name.

$auth->addAuthenticator($authenticator, $key);

Attempt

Attempt to login as a user.

• $identifier is a string representing the user identifier.
• $password is a string representing the user password.
• $rememberMe is a boolean indicating whether the user should be remembered, and will default to false.

$user = $auth->attempt($identifier, $password, $rememberMe);

Authenticator

Get an authenticator by key.

• $key is a string representing the authenticator key.

$authenticator = $auth->authenticator($key);

Authenticators

Get the authenticators.

$authenticators = $auth->authenticators();

Is Logged In

Determine if the current user is logged in.

$isLoggedIn = $auth->isLoggedIn();

Login

Login as a user.

• $user is an Entity representing the user.
• $rememberMe is a boolean indicating whether the user should be remembered, and will default to false.

$auth->login($user, $rememberMe);

Logout

Logout the current user.

$auth->logout();

User

Get the current user.

$user = $auth->user();

Identity

The Identity class provides the basis for user identification.

use Fyre\Auth\Identity;

Attempt

Attempt to identify a user.

• $identifier is a string representing the user identifier.
• $password is a string representing the user password.

$user = Identity::attempt($identifier, $password);

Get Identifier Fields

Get the user identifier fields.

$identifierFields = Identity::getIdentifierFields();

Get Model

Get the identity Model.

$model = Identity::getModel();

Get Password Field

Get the user password field.

$passwordField = Identity::getPasswordField();

Identify

Find an identity by identifier.

• $identifier is a string representing the user identifier.

$user = Identity::identify($identifier);

Set Identifier Fields

Get the user identifier fields.

• $identifierFields is an array containing the user identifier fields.

Identity::setIdentifierFields($identifierFields);

Set Model

Set the identity Model.

• $model is a Model.

Identity::setModel($model);

Set Password Field

Get the user password field.

• $passwordField is an string representing the user password field.

Identity::setPasswordField($passwordField);

Access

The Access class provides the basis for authorization.

use Fyre\Auth\Access;

After

Execute a callback after checking rules.

• $afterCallback is a Closure that accepts the current user, access rule name, current result and any additional arguments.

Access::after($afterCallback);

Allows

Check whether an access rule is allowed.

• $rule is a string representing the access rule name or Policy method.

Any additional arguments supplied will be passed to the access rule callback or Policy method.

$result = Access::allows($rule, ...$args);

Any

Check whether any access rule is allowed.

• $rules is an array containing access rule names or Policy methods.

Any additional arguments supplied will be passed to the access rule callbacks or Policy methods.

$result = Access::any($rules, ...$args);

Authorize

Authorize an access rule.

• $rule is a string representing the access rule name or Policy method.

Any additional arguments supplied will be passed to the access rule callback or Policy method.

Access::authorize($rule, ...$args);

Before

Execute a callback before checking rules.

• $beforeCallback is a Closure that accepts the current user, access rule name and any additional arguments.

Access::before($beforeCallback);

Clear

Clear all rules and callbacks.

Access::clear();

Define

Define an access rule.

• $rule is a string representing the access rule name.
• $callback is a Closure that accepts the current user and any additional arguments.

Access::define($rule, $callback);

Denies

Check whether an access rule is not allowed.

• $rule is a string representing the access rule name or Policy method.

Any additional arguments supplied will be passed to the access rule callback or Policy method.

$result = Access::denies($rule, ...$args);

None

Check whether no access rule is allowed.

• $rules is an array containing access rule names or Policy methods.

Any additional arguments supplied will be passed to the access rule callbacks or Policy methods.

$result = Access::none($rules, ...$args);

Policy Registry

Add Namespace

Add a namespace for loading policies.

• $namespace is a string representing the namespace.

PolicyRegistry::addNamespace($namespace);

Clear

Clear all namespaces and policies.

PolicyRegistry::clear();

Get Namespaces

Get the namespaces.

$namespaces = PolicyRegistry::namespaces();

Has Namespace

Determine if a namespace exists.

• $namespace is a string representing the namespace.

$hasNamespace = PolicyRegistry::hasNamespace($namespace);

Load

Load a Policy.

• $alias is a string representing the Model alias or class name.

$policy = PolicyRegistry::load($alias);

Map

Map an alias to a Policy class name.

• $alias is a string representing the Model alias or class name.
• $className is a string representing the Policy class name.

PolicyRegistry::map($alias, $className);

Remove Namespace

Remove a namespace.

• $namespace is a string representing the namespace.

PolicyRegistry::removeNamespace($namespace);

Unload

Unload a policy.

• $alias is a string representing the Model alias or class name.

PolicyRegistry::unload($alias);

Use

Load a shared Policy instance.

• $alias is a string representing the Model alias or class name.

$policy = PolicyRegistry::use($alias);

Policies

Custom policies can be created by extending the \Fyre\Auth\Policy class, suffixing the singular alias with "Policy".

Policy rules should be represented as methods on the class, that accept the current user and resolved Entity as arguments.

Get Model

Get the Model.

$model = $policy->getModel();

Resolve Entity

Resolve an Entity from access rule arguments.

• $args is an array containing the access rule arguments.

$entity = $policy->resolveEntity($args);

Authenticators

Custom authenticators can be created by extending the \Fyre\Auth\Authenticator class, and overwriting the below methods as required.

Authenticate

Authenticate a ServerRequest.

• $request is a ServerRequest.

$user = $authenticator->authenticate($request);

Before Response

Update the ClientResponse before sending to client.

• $response is a ClientResponse.

$response = $authenticator->beforeResponse($response);

Login

Login as a user.

• $user is an Entity representing the user.
• $rememberMe is a boolean indicating whether the user should be remembered, and will default to false.

$authenticator->login($user, $rememberMe);

Logout

Logout the current user.

$authenticator->logout();

Cookie

use Fyre\Auth\Authenticators\CookieAuthenticator;

The cookie authenticator can be loaded using custom configuration.

• $options is an array containing configuration options.
  • cookieName is a string representing the cookie name, and will default to "auth".
  • cookieOptions is an array containing additional options for setting the cookie.
    • expires is a number representing the cookie lifetime, and will default to null.
    • domain is a string representing the cookie domain, and will default to "".
    • path is a string representing the cookie path, and will default to "/".
    • secure is a boolean indicating whether to set a secure cookie, and will default to false.
    • httpOnly is a boolean indicating whether to the cookie should be HTTP only, and will default to true.
    • sameSite is a string representing the cookie same site, and will default to "Lax".
  • identifierField is a string representing the identifier field of the user, and will default to "email".
  • passwordfield is a string representing the password field of the user, and will default to "password".
  • salt is a string representing the salt to use when generating the token, and will default to null.

$authenticator = new CookieAuthenticator($options);

This authenticator is only active when the $rememberMe argument is set to true in the Auth::attempt and Auth::login methods.

Session

use Fyre\Auth\Authenticators\SessionAuthenticator;

The session authenticator can be loaded using custom configuration.

• $options is an array containing configuration options.
  • sessionKey is a string representing the session key, and will default to "auth".
  • sessionField is a string representing the session field of the user, and will default to "id".

$authenticator = new SessionAuthenticator($options);

Token

use Fyre\Auth\Authenticators\TokenAuthenticator;

The token authenticator can be loaded using custom configuration.

• $options is an array containing configuration options.
  • tokenHeader is a string representing the token header name, and will default to "Authorization".
  • tokenHeaderPrefix is a string representing the token header prefix, and will default to "Bearer".
  • tokenQuery is a string representing the query parameter, and will default to null.
  • tokenField is a string representing the token field of the user, and will default to "token".

$authenticator = new TokenAuthenticator($options);

Middleware

Auth Middleware

use Fyre\Auth\Middleware\AuthMiddleware;

This middleware will authenticate using the loaded authenticators, and add any authentication headers to the response.

$middleware = new AuthMiddleware();

Process

• $request is a ServerRequest.
• $handler is a RequestHandler.

$response = $middleware->process($request, $handler);

Authenticated Middleware

This middleware will throw an UnauthorizedException if the user is not authenticated.

use Fyre\Auth\Middleware\AuthenticatedMiddleware;

$middleware = new AuthenticatedMiddleware();

Process

• $request is a ServerRequest.
• $handler is a RequestHandler.

$response = $middleware->process($request, $handler);

Authorized Middleware

This middleware will throw a ForbiddenException if the user is not authorized.

use Fyre\Auth\Middleware\AuthorizedMiddleware;

$middleware = new AuthorizedMiddleware();

Process

• $request is a ServerRequest.
• $handler is a RequestHandler.

$response = $middleware->process($request, $handler, ...$args);

Unauthenticated Middleware

This middleware will return a RedirectResponse if the user is authenticated.

use Fyre\Auth\Middleware\UnauthenticatedMiddleware;

• $redirect is a Uri or string representing the URI to redirect to, and will default to "/".

$middleware = new UnauthenticatedMiddleware($redirect);

Process

• $request is a ServerRequest.
• $handler is a RequestHandler.

$response = $middleware->process($request, $handler);