rougin/authsum

Yet another PHP authentication library.

Authsum

![Software License][ico-license] ![Coverage Status][ico-coverage] , _(*1)

Authsum is a simple authentication package written in PHP which allows to create simple and extensible authentication logic., _(*2)

Installation

Install the Authsum package via Composer:, _(*3)

``` bash $ composer require rougin/authsum, <sub>(*4)</sub>

## Basic usage

Prior in using `Authsum`, a data source must be defined first (e.g., `BasicSource`):

``` php
// index.php

use Rougin\Authsum\Source\BasicSource;

// ...

$username = 'admin';
$password = /** ... */;

// Check if the provided username and password data ---
// matched from the given payload (e.g., $_POST) ------
$source = new BasicSource($username, $password);
// ----------------------------------------------------

// ...

Once the source is defined, use the Authsum class to perform the validation logic:, <sub>(*5)</sub>

``` php // index.php, <sub>(*6)</sub>

use Rougin\Authsum\Authsum;, <sub>(*7)</sub>

// ..., <sub>(*8)</sub>

$auth = new Authsum($source);, <sub>(*9)</sub>

if ($auth->isValid($_POST)) { /** @var \Acme\Models\User */ $user = $auth->getResult()->getField('user');, <sub>(*10)</sub>

echo 'Welcome ' . $user->getName() . '!';

} else { echo 'Invalid credentials!'; }, <sub>(*11)</sub>

## Customization

`Authsum` also provides simple extensibility utilities to be able to fit in from various use-cases.

### Pass or fail from `Authsum`

The `Authsum` class can also be extended to provide methods if the validation logic passed or failed:

``` php
namespace Acme;

use Acme\Depots\AuditDepot;
use Acme\Errors\NoAccount;
use Rougin\Authsum\Authsum;
use Rougin\Authsum\Error;
use Rougin\Authsum\Result;

class TestAuth extends Authsum
{
    protected $audit;

    public function __construct(AuditDepot $audit)
    {
        $this->audit = $audit;
    }

    /**
     * Executes if the validation failed.
     *
     * @param \Rougin\Authsum\Error $error
     *
     * @return void
     */
    protected function failed(Error $error)
    {
        throw new NoAccount($error->getText());
    }

    /**
     * Executes if the validation passed.
     *
     * @param \Rougin\Authsum\Result $data
     *
     * @return void
     */
    protected function passed(Result $data)
    {
        /** @var string */
        $user = $data->getField('name');

        $this->audit->userLoggedIn($user);
    }
}

Alternatively, the Authsum class can also get the error or the result after validation using getError() and getResult() respectively:, <sub>(*12)</sub>

``` php // index.php, <sub>(*13)</sub>

use Rougin\Authsum\Authsum;, <sub>(*14)</sub>

// ..., <sub>(*15)</sub>

$auth = new Authsum($source);, <sub>(*16)</sub>

if ($auth->isValid($_POST)) { $result = $auth->getResult();, <sub>(*17)</sub>

/** @var string */
$name = $result->getField('name');

echo 'Welcome ' . $name . '!';

} else { $error = $auth->getError();, <sub>(*18)</sub>

echo 'Error: ' . $auth->getText();

}, <sub>(*19)</sub>

> [!NOTE]
> An `UnexpectedValueException` will be thrown if trying to access an empty output (e.g., trying to access `getResult()` after the failed validation).

### Changing fields to check

By default, the `Authsum` class can check the `email` as its username and `password` for the password from the payload (e.g., `$_POST`). If this is not the case, kindly update the specified fields using `setUsernameField` or `setPasswordField`:

``` php
// index.php

// ...

$auth->setUsernameField('username');
$auth->setPasswordField('password');

// ...

[!NOTE] The specified fields will be used by the Authsum class if they are required by the specified source (e.g., BasicSource, PdoSource)., <sub>(*20)</sub>

Using sources

Sources in Authsum are PHP classes that provide user data. They can be used for checking the specified username and password fields against its data source:, <sub>(*21)</sub>

``` php // index.php, <sub>(*22)</sub>

use Rougin\Authsum\Authsum; use Rougin\Authsum\Source\BasicSource;, <sub>(*23)</sub>

// ..., <sub>(*24)</sub>

// Initialize the source... -------------------- $username = 'admin'; $password = /** ... */;, <sub>(*25)</sub>

$source = new BasicSource($username, $password); // ---------------------------------------------, <sub>(*26)</sub>

// ...then pass it to Authsum --- $auth = new Authsum($source); // ------------------------------, <sub>(*27)</sub>

// The source will be used to check if --- // the provided payload matches in the --- // given payload ($_POST) from its source $valid = $auth->isValid($_POST); // ---------------------------------------, <sub>(*28)</sub>

// ..., <sub>(*29)</sub>

#### `PdoSource`

Besides from `BasicSource`, another available source that can be used is `PdoSource` which uses [PDO](https://www.php.net/manual/en/intro.pdo.php) to interact with a database:

``` php
// index.php

use Rougin\Authsum\Source\PdoSource;

// ...

// Create a PDO instance... --------------
$dsn = 'mysql:host=localhost;dbname=demo';

$pdo = new PDO($dsn, 'root', /** ... */);
// ---------------------------------------

// ...then pass it to the PdoSource ---
$source = new PdoSource($pdo);
// ------------------------------------

// ...

The setTableName method can also be used to specify its database table name:, <sub>(*30)</sub>

``` php // index.php, <sub>(*31)</sub>

use Rougin\Authsum\Source\PdoSource;, <sub>(*32)</sub>

// ..., <sub>(*33)</sub>

$source = new PdoSource($pdo);, <sub>(*34)</sub>

$source->setTableName('users');, <sub>(*35)</sub>

// ..., <sub>(*36)</sub>

> [!NOTE]
> If the `setTableName` is not specified, it always refer to the `users` table.

When using `PdoSource`, the value in the `password` field will be assumed as a hash (e.g., `$2y$10...`). If this is not the case, kindly add the `withoutHash` method:

``` php
// index.php

use Rougin\Authsum\Source\PdoSource;

// ...

$source = new PdoSource($pdo);

$source->withoutHash();

// ...

Doing this will make a strict comparison of the provided password against the result from the database., <sub>(*37)</sub>

JwtSource

The JwtSource class is a special class that checks a user's authentication using JSON Web Token:, <sub>(*38)</sub>

``` php // index.php, <sub>(*39)</sub>

use Rougin\Authsum\Source\JwtSource;, <sub>(*40)</sub>

// ..., <sub>(*41)</sub>

/** @var \Rougin\Authsum\Source\JwtParserInterface */ $parser = /** ... */;, <sub>(*42)</sub>

$source = new JwtSource($parser);, <sub>(*43)</sub>

From the example above, initializing `JwtSource` requires a `JwtParserInterface` for parsing the JSON web tokens from payload:

``` php
namespace Rougin\Authsum\Source;

interface JwtParserInterface
{
    /**
     * Parses the token string.
     *
     * @param string $token
     *
     * @return array<string, mixed>
     */
    public function parse($token);
}

If JwtSource is used as a source, the token field must be updated also from the Authsum class based on the query parameter or parsed body where the token exists:, <sub>(*44)</sub>

``` php // index.php, <sub>(*45)</sub>

use Rougin\Authsum\Authsum; use Rougin\Authsum\Source\JwtSource;, <sub>(*46)</sub>

// ..., <sub>(*47)</sub>

$source = new JwtSource($parser);, <sub>(*48)</sub>

// Search "token" property from the payload --- $source->setTokenField('token'); // --------------------------------------------, <sub>(*49)</sub>

$auth = new Authsum($source);, <sub>(*50)</sub>

> [!NOTE]
> If `setTokenField` is not specified, its default value is `token`.

Then use the `setUsernameField` to specify the field to be compared against the parsed data from the JSON web token:

``` php
// index.php

use Rougin\Authsum\Authsum;

// ...

$auth = new Authsum($source);

// ...

$auth->setUsernameField('email');

// The $_POST data should contains the ---
// "token" field and the "email" field ---
$valid = $auth->isValid($_POST);
// ---------------------------------------

Creating custom sources

To create a custom source, kindly use the SourceInterface for its implementation:, <sub>(*51)</sub>

``` php namespace Rougin\Authsum\Source;, <sub>(*52)</sub>

interface SourceInterface { /** * Returns the error after validation. * * @return \Rougin\Authsum\Error */ public function getError();, <sub>(*53)</sub>

/**
 * Returns the result after validation.
 *
 * @return \Rougin\Authsum\Result
 */
public function getResult();

/**
 * Checks if it exists from the source.
 *
 * @return boolean
 */
public function isValid();

}, <sub>(*54)</sub>

If the custom source requires an `username` field, kindly add the `WithUsername` interface:

``` php
namespace Rougin\Authsum\Source;

interface WithUsername
{
    /**
     * Sets the username field.
     *
     * @param string $username
     *
     * @return self
     */
    public function setUsernameField($username);

    /**
     * Sets the username.
     *
     * @param string $username
     *
     * @return self
     */
    public function setUsernameValue($username);
}

The WithPassword interface can be also added if the custom source requires a password to be defined:, <sub>(*55)</sub>

``` php namespace Rougin\Authsum\Source;, <sub>(*56)</sub>

interface WithPassword { /** * Sets the password field. * * @param string $password * * @return self */ public function setPasswordField($password);, <sub>(*57)</sub>

/**
 * Sets the password value.
 *
 * @param string $password
 *
 * @return self
 */
public function setPasswordValue($password);

}, <sub>(*58)</sub>

Some custom sources may require to use the provided payload instead of `username` and `password` fields (e.g., `JwtSource`). With this, kindly use the `WithPayload` interface:

``` php
namespace Rougin\Authsum\Source;

interface WithPayload
{
    /**
     * Sets the prepared payload.
     *
     * @param array<string, string> $payload
     *
     * @return self
     */
    public function setPayload($payload);
}

Testing

If there is a need to check the source code of Authsum for development purposes (e.g., creating fixes, new features, etc.), kindly clone this repository first to a local machine:, <sub>(*59)</sub>

``` bash $ git clone https://github.com/rougin/authsum.git "Sample", <sub>(*60)</sub>

After cloning, use `Composer` to install its required packages:

``` bash
$ cd Sample
$ composer update

[!NOTE] Please see also the build.yml of Authsum to check any packages that needs to be installed based on the PHP version., <sub>(*61)</sub>

Once the required packages were installed, kindly check the following below on how to maintain the code quality and styling guide when interacting the source code of Authsum:, <sub>(*62)</sub>

Unit tests

Authsum also contains unit tests that were written in PHPUnit:, <sub>(*63)</sub>

``` bash $ composer test, <sub>(*64)</sub>

When creating fixes or implementing new features, it is recommended to run the above command to always check if the updated code introduces errors during development.

### Code quality

To retain the code quality of `Authsum`, a static code analysis code tool named [PHPStan](https://phpstan.org/) is being used during development. To start, kindly install the specified package in the global environment of `Composer`:

``` bash
$ composer global require phpstan/phpstan --dev

Once installed, PHPStan can now be run using its namesake command:, <sub>(*65)</sub>

``` bash $ cd Sample $ phpstan, <sub>(*66)</sub>

> [!NOTE]
> When running `phpstan`, it will use the `phpstan.neon` file which is already provided by `Authsum`.

### Coding style

Aside from code quality, `Authsum` also uses a tool named [PHP Coding Standards Fixer](https://cs.symfony.com/) for maintaining an opinionated style guide. To use this tooling, it needs also to be installed in the `Composer`'s global environment first:

``` bash
$ composer global require friendsofphp/php-cs-fixer --dev

After its installation, kindly use the php-cs-fixer command in the same Authsum directory:, <sub>(*67)</sub>

bash $ cd Sample $ php-cs-fixer fix --config=phpstyle.php, <sub>(*68)</sub>

The phpstyle.php file provided by Authsum currently follows the PSR-12 standard as its baseline for the coding style and uses Allman as its indentation style., <sub>(*69)</sub>

[!NOTE] Installing both PHPStan and PHP Coding Standards Fixer requires a minimum version of PHP at least 7.4., <sub>(*70)</sub>

Changelog

Please see CHANGELOG for more information what has changed recently., <sub>(*71)</sub>

License

The MIT License (MIT). Please see LICENSE for more information., <sub>(*72)</sub>