README

Description : Implementation of Http Router classes for PHP7.1 or higher with authentication.

This library is mainly composed of 8 classes.

AuthRouter

The AuthRouter class extends from the hunomina\Routing\Router class.

Therefore it can handle request by calling the request(string $method, string $url) method which must return a route action response.

Read this documentation in order to understand how the base routing system works.

This class can be instantiated by passing a route file, an AuthenticationCheckerInterface instance and a type (json, yaml... extend if you want to add new ones).

The route file syntax is identical to the hunomina\Routing\Router route file syntax.

Examples here.

AuthenticationCheckerInterface

The AuthenticationCheckerInterface has three methods :

bool isAuthenticated() : Returns true if an user is connected to your application. You can whatever you want : cookies, sessions, headers...
?UserInterface getAuthenticatedUser() : Returns the authenticated user for session, cookie, headers...
bool checkAuthorization(?UserInterface $user, SecurityContext $securityContext, string $method, string $url) : Returns true if a specific user can access to a route (method + url) based on a security context

In order for the AuthRouter to work with your application, you have to create a class that implements the AuthenticationCheckerInterface interface and her methods.

You absolutely can add some methods if needed.

UserInterface

The UserInterface must be implemented by all user entities that will log into your application.

This interface has two methods :

string[] getRoles() : Returns a string list of all the user's security context roles
string getUsername() : Returns the username used to authenticate the user

SecurityContext

Allow to define role based rules for specific routes.

This class loads the security context from a configuration file, check his validity and instantiate multiple Role and Rule objects according to the configuration file.

You can then use the security context object in your AuthenticationChecker application instance to check users rights.

This class is abstract and has two methods that you have to implement :

void load(): Once the configuration file has been validated, loads it and instantiates Role and Rule object to feet the configuration
bool isSecurityContextValid() : Returns true if the configuration file syntax is valid

This package comes with two built-in SecurityContext implementation :

If you want to add a new SecurityConext type, you'll have to create two classes :

A class extending the AuthRouter class in order to be able to use the new SecurityContext type
A class extending the SecurityContext class in order to create a new configuration file parser

Role

A Role is just a name with child roles.

This class has two properties :

string $_name : The name of the role
Role[] $_children : A list of child roles. Allow to define a role hierarchy

And one method :

bool contains(Role $role) : Returns true if the Role instance is $role or has $role as a child

Rule

A Rule has 3 properties :

string $_path : Pseudo regular expression matching the urls the rule must apply to. "Pseudo regular expression" means that it's a regular expression without "/" escaped
string[] $_methods : List of http methods. Restrict the http methods on which the rule can match
Role[] $_roles : List of Role who can access to the $_path with the $methods http methods

Those three properties are passed to the constructor. Make sure all of them are valid (e.g. valid pseudo regular expression for $_path property)

YamlSecurityContext

The YamlSecurityContext is a built-in SecurityContext implementation.

It allow you to use Yaml configuration file for your application AuthRouter SecurityContext. If you use this SecurityContext class you must follow this simple configuration file syntax :

Have a root element security.
Have two children element : auth_firewall and role_hierarchy.
auth_firewall contains the list of all the application firewall rules.
role_hierarchy contains the list of all the application roles and their hierarchy.

Each rule is composed of :

path : Pseudo regular expression for the Rule object.
roles : A string or a string list of the roles the rule uses. If empty, nothing can validate the rule.
methods : An optional list of http methods to use to match the rule

Each role is composed of :

A key : The role name
A value : A string or a string list of child roles

Example here (Yaml)

JsonSecurityContext

The JsonSecurityContext is a built-in SecurityContext implementation too.

It allow you to use Json configuration file for your application AuthRouter SecurityContext.

For this SecurityContext class, the configuration file syntax is the same as the YamlSecurityContext.

Example here (Json)

Examples

For more examples, check those here

hunomina / http-auth-router-php

Maintainers

Details