Home
It is a PHP library with the purpose of managing navigation routes from the URL using a pre-defined configuration structure and a constructor object.
By adjusting the configuration structure, it is possible to create free routes (without password) or restricted routes (with password); set maximum time between navigation; and add trigger for changing routes and checking authentication and access.
The page to be displayed is defined through an identifier contained in the URL that will establish the route to the target file, without displaying its path.
Authentication, access checking and route redirection are external functions, defined by the developer, which are called at certain moments of navigation that will subsidize the decision on the route to be taken.
It is up to the developer to establish security regarding access to files and application data, it is up to the library only to indicate the route to be taken as configured.
The tool is activated through the object named Driver.
Click here to download the tool.
The constructor is defined as follows:
Driver($config)| Argument | Type | Mandatory | Default | Description |
|---|---|---|---|---|
| config | Array/JSON File | Yes | None | Contains the configuration data for the navigation. |
It is recommended that the builder be called before sending any kind of information to the browser.
The config argument can be in the form of an array or contained in a JSON file. Therefore, accepted argument types are a list of data (array) or the address of a JSON file (string).
Below are configuration examples in array and JSON formats:
JSON
{
"CHECK": true,
"HOME": "content/home.php",
"ID": {
"config": "content/config.php",
"debug": "content/debug.php",
"only1": "content/only1.php",
"only2": "content/only2.php"
},
"LOG": {
"GATEWAY": "content/login.php",
"EXIT": "content/exit.php",
"DATA": ["usr", "pwd"],
"LOGIN": "credentialChecker",
"ALLOW": "accessChecker",
"LOAD": "loadChecker",
"TIME": 180
}
}Array
$config = array(
"CHECK" => true,
"HOME" => "content/home.php",
"ID" => array(
"config" => "content/config.php",
"debug" => "content/debug.php",
"only1" => "content/only1.php",
"only2" => "content/only2.php"
),
"LOG" => array(
"GATEWAY" => "content/login.php",
"EXIT" => "content/exit.php",
"DATA" => ["usr", "pwd"],
"LOGIN" => "credentialChecker",
"ALLOW" => "accessChecker",
"LOAD" => "loadChecker",
"TIME" => 180
)
);Configuration data has the following properties:
| Key | Subkey | Type | Optional | Description |
|---|---|---|---|---|
| CHECK | - | Boolean | Yes | Indicates whether the tool should carry out a previous data check. |
| HOME | - | String | No | Defines the path of the application's main page. |
| ID | - | Array/Object | No | Contains the list of paths to application files defined from identifiers. |
| LOG | - | Array/Object | Yes | Informs if the application will require authentication. |
| LOG | GATEWAY | String | No | Sets the authentication page path. |
| LOG | EXIT | String | No | Sets the exit page path. |
| LOG | DATA | Array | No | Informs the list of data that will be submitted in authentication. |
| LOG | LOGIN | String | No | Name of the function that will receive the authentication data and return the result. |
| LOG | ALLOW | String | Yes | Name of the function that will check the user's access to the given route. |
| LOG | LOAD | String | Yes | Route redirector function name. |
| LOG | TIME | Integer | Yes | Information in seconds about the maximum time allowed between navigations. |
| COOKIES | - | Array/Object | Yes | Defines cookie policy settings. |
| COOKIES | HTTPONLY | Boolean | Yes | Sets the session.cookie_httponly directive setting. |
| COOKIES | SECURE | Boolean | Yes | Sets the session.cookie_secure directive setting. |
| COOKIES | SAMESITE | String | Yes | Sets the session.cookie_samesite directive setting. |
| COOKIES | LIFETIME | Integer | Yes | Sets the session.cookie_lifetime directive setting. |
| COOKIES | PATH | String | Yes | Sets the session.cookie_path directive setting. |
| COOKIES | DOMAIN | String | Yes | Sets the session.cookie_domain directive setting. |
Optional keys, when unnecessary, must be set to null. (Not applicable as of v1.1.0.)
By default, the tool will check the configuration data each time the builder is called.
When the CHECK attribute is set to false, verification of configuration data is not done by the constructor, saving processing. Otherwise, verification will be performed.
During the construction process, it is advisable to leave it on to examine any mistakes in the configuration, and it can be turned off later to speed up loading.
The HOME attribute will set the path to the main application file.
The path section demonstrates which situations lead to the home page.
The ID attribute will define the list of route identifiers and their relative paths to the destination files.
The identifiers HOME and EXIT are reserved to indicate the home page and the end of the authenticated session, respectively. Therefore, they cannot be defined as identifiers.
The navigation route is defined by the URL, using data from the GET (QUERY) method, which will identify the destination page from the identifier associated with the id key.
For example, if the file content/page.html is associated with the identifier myID, you can create a navigation link for the mentioned route as follows:
<a href="?id=myID">Target Name</a>When clicking on the link above, the destination URL will point to an address similar to http://mypage/?id=myID. When analyzing the route, the tool will return, if allowed, the path to access the corresponding file.
The path section demonstrates which situations lead to the page defined in this key.
The LOG attribute will define the need for authentication to perform the navigation.
If not set, the navigation will not require authentication, otherwise, the parameters to allow its control must be informed.
The GATEWAY attribute will define the path of the file corresponding to the authentication page, where the user will inform his credentials for checking.
The path section demonstrates which situations lead to the authentication page.
The EXIT attribute will define the path of the session termination file, where the user can be informed about the procedure result.
The path section demonstrates which situations lead to the session end page.
The DATA attribute will inform the list containing the data that the user will inform in the authentication procedure.
The data correspond to the names (strings) of the form fields that the user will submit through the authentication page defined in the GATEWAY attribute. The sending of data must be by the POST method.
The LOGIN attribute must inform the name of the function that will receive the authentication data and will return the result of the success of the operation.
The function will need to contain an argument to receive the data informed by the user, which will occur by sending the PHP variable $_POST. Exemplifying:
function authenticator($post) {
/* parameters for checking */
return $success ? $userData : null;
}If the function returns null, the tool will understand that the authentication has failed, otherwise it will consider that the user has been successfully authenticated and will record this result to perform the route analysis.
The path section demonstrates the routes to be taken after verifying the authentication data.
The ALLOW attribute (optional) must inform the name of the function that will analyze the access permission for each route, returning true, if allowed, or false, if not allowed.
The function will need to contain three arguments that will receive user data, informed by the function defined in the LOGIN attribute, the route identifier and the corresponding path. Exemplifying:
function accessibility($userData, $id, $path) {
/* parameters for checking */
return $accessible ? true : false;
}The path section demonstrates the routes to be taken after checking access permission, if set.
The LOAD attribute (optional) must inform the name of the function that will be triggered before returning the route and that will have the power to redirect it, either to a pre-defined path or to another file.
The function will need to contain an attribute that will receive the data returned by the debug method. Exemplifying:
function redirector($debug) {
/* parameters for checking */
return $redirect ? $path : null;
}The function must return a string that will correspond to a valid identifier, constant in the ID attribute, HOME, EXIT or a valid path to a given file. Otherwise, the route returned will be the one defined before the function was fired.
The trigger can also be used to perform other navigation checks, regardless of whether the route is redirected.
The path section demonstrates the routes to follow after executing this trigger, if set.
Here the redirection will be in charge of the function, allowing behavior that contradicts that defined by the tool.
The TIME attribute (optional) must inform the time, in seconds and greater than zero, that each request can remain active.
When the time is extrapolated, when navigating to another route, the session will be terminated and a new authentication will be required.
The path section demonstrates the route in this situation, if defined.
The COOKIES attribute (optional) will define the directives for setting cookies.
If not defined, the settings will be assigned by the tool according to each policy.
The HTTPONLY attribute (optional) defines whether cookies can only be accessed through the HTTP protocol (no JavaScript access).
The default value is true.
The SECURE attribute (optional) informs whether cookies should only be sent over secure connections (HTTPS).
By default, if not set, the value will be true if the $_SERVER["HTTPS"] attribute is set, otherwise false.
The SAMESITE attribute (optional) controls the sending of the cookie between domains (see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).
Possible values are lax (default), strict or none.
The LIFETIME attribute (optional) defines the lifetime of the cookie.
The default value is zero.
The PATH attribute (optional) defines the path where the information is stored.
The default value is the one defined by the PHP configuration.
The DOMAIN attribute (optional) defines the domain of the cookie.
The default value is the one defined by the PHP configuration.
The Driver object has the following public methods.
Sets the route and returns the path to the file to be displayed (string).
The method can only be called once per request, calling it a second time will cause an error.
The route is defined by the following processing when authentication is required:
Before returning, the previously defined path can go through the route diverter:
When not requiring authentication, the following behavior will be observed:
status($text)| Argument | Type | Mandatory | Default | Description |
|---|---|---|---|---|
| text | Boolean | No | false | Defines whether the return will be in text form. |
The method returns the status identifier (integer) or its textual counterpart (string) as shown in the table below:
| Numerical ID | Text Value | Description |
|---|---|---|
| 0 | SESSION STARTED | Situation prior to the path call. |
| 1 | AUTHENTICATION REQUIRED | Situation when the authentication requirement has not been met. |
| 2 | AUTHENTICATION FAILED | Situation when authentication failed. |
| 3 | SUCCESSFULLY AUTHENTICATED | Situation when authentication was successful. |
| 4 | PERMITTED ACCESS | Situation when the chosen path is allowed. |
| 5 | ACCESS DENIED | Situation when the chosen path is not allowed. |
| 6 | PAGE NOT FOUND | Situation when the chosen path does not exist. |
| 7 | SESSION CLOSED | Situation when the session ends (EXIT). |
| 8 | SESSION EXPIRED | Situation when the time between requests expires, if defined. |
| 9 | MODIFIED ROUTE | Situation when the route is changed. |
The status (values 1 to 9) is set after the path method is called.
version()The method returns the version of the tool.
json($print)| Argument | Type | Mandatory | Default | Description |
|---|---|---|---|---|
| Boolean | No | false | Defines whether the configuration, in JSON format, should be displayed on the screen. |
The method returns the configuration used to define the route (array).
debug($print)| Argument | Type | Mandatory | Default | Description |
|---|---|---|---|---|
| Boolean | No | false | Defines whether to display session data on the screen. |
The method returns the session data stored by the tool during requests (array).
The PHP session will be started by the Driver constructor, if not already defined, and the data stored by the tool during requests will be cleared in status 7 and 8 cases (session will be destroyed in these situations).
The data stored by the tool in the $_SESSION variable will be registered in the __DRIVER__ key, whose manipulation is not recommended. Other information may be registered in other keys while the session is active.
The following data will be stored by the tool and can be observed through the debug method:
| Key | Type | Description |
|---|---|---|
| USER | Any | Records the data passed on after the authentication process. |
| TIME | Integer | Records the time of authentication in seconds. |
| DATE | String | Records the authentication date and time. |
| HASH | String | Registers the session identifier. |
| LOG | Array | Logs browsing history. |
| LAST | Array | Packs the information from the last record of the browsing history (LOG). |
As for the browsing history (LOG key), the following information will be recorded in the order of occurrence (from oldest to newest) when the path method is called:
| Key | Type | Description |
|---|---|---|
| ITEM | Integer | Informs the sequential identifier of the request history. |
| INFO | String | Logs the textual value of the status. |
| ID | String | Registers the id provided in the URL. |
| PAGE | String | Records the required path, if any. |
| PATH | String | Logs the path returned. |
| INDEX | String | Records the path of the executed file. |
| LOG | Boolean | Informs if authentication is required |
| LOGIN | Boolean | Informs if there was authentication. |
| STATUS | Integer | Registers the numeric value of status. |
| TIME | Integer | Records the time of the request in seconds. |
| DATE | String | Records the date and time of the request. |
The tool does not guarantee the security of the data contained in the server, this task is for the programmer.
It is up to the tool to indicate the route to the page to be accessed according to the defined configuration and the rules described.
Use the configuration framework to define some criteria involving cookies.
The session identifier is regenerated on each request, do not use it to compare information.
The example below exemplifies the basic use of the library on a web page:
<?php
/* Invoking the library: */
include "Driver.php";
/* Calling the constructor: */
$driver = new Driver("config.json");
/* Displaying the file defined by the object: */
include $driver->path();
?>Versioning is defined by three integers separated by dots with the following definitions:
| Level | Definition | Description |
|---|---|---|
| 1 | Compatibility | It is increased when the library loses compatibility with the previous version. |
| 2 | Innovation | Is increased when the library gains new tools. |
| 3 | Maintenance | Is increased when the library undergoes corrections or enhancements. |
- Possibility to define cookie directives through the configuration framework;
- Added mandatory log out file (EXIT) to configuration data when requiring restricted access;
- Session is now destroyed with user exit or timeout.
- Added LAST key in debug data to indicate last request information; and
- Addition of the ITEM key in the request records to indicate its sequential identifier.
- Initial release.