PHPackages                             rougin/authsum - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. rougin/authsum

ActiveLibrary[Authentication & Authorization](/categories/authentication)

rougin/authsum
==============

Simple authentication package in PHP.

v0.1.0(10mo ago)13921MITPHPPHP >=5.3.0CI failing

Since Jul 18Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/rougin/authsum)[ Packagist](https://packagist.org/packages/rougin/authsum)[ RSS](/packages/rougin-authsum/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

Authsum
=======

[](#authsum)

[![Latest Version on Packagist](https://camo.githubusercontent.com/2d050c92ea355a3d86a74b0b438b2e13b8d8751c43d78bb6830eb66186355319/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f726f7567696e2f6175746873756d2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rougin/authsum)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/rougin/authsum/blob/master/LICENSE.md)[![Build Status](https://camo.githubusercontent.com/458bdb422328551ca5b631d9e69f5f482a97f2db59de7c34f52211c30adc719f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f7567696e2f6175746873756d2f6275696c642e796d6c3f7374796c653d666c61742d737175617265)](https://github.com/rougin/authsum/actions)[![Coverage Status](https://camo.githubusercontent.com/fd620e3881eb1869f8870851041d46d60741cc43a5c0a617734b802aae368e7b/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f726f7567696e2f6175746873756d3f7374796c653d666c61742d737175617265)](https://app.codecov.io/gh/rougin/authsum)[![Total Downloads](https://camo.githubusercontent.com/25825ee6005751dd35506ce2522608f3c8a60d54500c390dd7d3a275e9e55417/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f726f7567696e2f6175746873756d2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rougin/authsum)

`Authsum` is a simple authentication package written in PHP which allows to create simple and extensible authentication logic.

Installation
------------

[](#installation)

Install the `Authsum` package via [Composer](https://getcomposer.org/):

```
$ composer require rougin/authsum
```

Basic usage
-----------

[](#basic-usage)

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

```
// 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:

```
// index.php

use Rougin\Authsum\Authsum;

// ...

$auth = new Authsum($source);

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

    echo 'Welcome ' . $user->getName() . '!';
}
else
{
    echo 'Invalid credentials!';
}
```

Customization
-------------

[](#customization)

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

### Pass or fail from `Authsum`

[](#pass-or-fail-from-authsum)

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

```
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:

```
// index.php

use Rougin\Authsum\Authsum;

// ...

$auth = new Authsum($source);

if ($auth->isValid($_POST))
{
    $result = $auth->getResult();

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

    echo 'Welcome ' . $name . '!';
}
else
{
    $error = $auth->getError();

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

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

[](#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`:

```
// 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`).

### Using sources

[](#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:

```
// index.php

use Rougin\Authsum\Authsum;
use Rougin\Authsum\Source\BasicSource;

// ...

// Initialize the source... --------------------
$username = 'admin';
$password = /** ... */;

$source = new BasicSource($username, $password);
// ---------------------------------------------

// ...then pass it to Authsum ---
$auth = new Authsum($source);
// ------------------------------

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

// ...
```

#### `PdoSource`

[](#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:

```
// 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:

```
// index.php

use Rougin\Authsum\Source\PdoSource;

// ...

$source = new PdoSource($pdo);

$source->setTableName('users');

// ...
```

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:

```
// 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.

#### `JwtSource`

[](#jwtsource)

The `JwtSource` class is a special class that checks a user's authentication using [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token):

```
// index.php

use Rougin\Authsum\Source\JwtSource;

// ...

/** @var \Rougin\Authsum\Source\JwtParserInterface */
$parser = /** ... */;

$source = new JwtSource($parser);
```

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

```
namespace Rougin\Authsum\Source;

interface JwtParserInterface
{
    /**
     * Parses the token string.
     *
     * @param string $token
     *
     * @return array
     */
    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:

```
// index.php

use Rougin\Authsum\Authsum;
use Rougin\Authsum\Source\JwtSource;

// ...

$source = new JwtSource($parser);

// Search "token" property from the payload ---
$source->setTokenField('token');
// --------------------------------------------

$auth = new Authsum($source);
```

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:

```
// 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

[](#creating-custom-sources)

To create a custom source, kindly use the `SourceInterface` for its implementation:

```
namespace Rougin\Authsum\Source;

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

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

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

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

```
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:

```
namespace Rougin\Authsum\Source;

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

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

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:

```
namespace Rougin\Authsum\Source;

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

Changelog
---------

[](#changelog)

Please see [CHANGELOG](https://github.com/rougin/authsum/blob/master/CHANGELOG.md) for more recent changes.

Contributing
------------

[](#contributing)

See [CONTRIBUTING](https://github.com/rougin/authsum/blob/master/CONTRIBUTING.md) on how to contribute.

License
-------

[](#license)

The MIT License (MIT). Please see [LICENSE](https://github.com/rougin/authsum/blob/master/LICENSE.md) for more information.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance63

Regular maintenance activity

Popularity15

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity21

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

302d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c7721589a958a1fbcef1b527c794d820d75b82988f14b2ed86a1c6904d76a59e?d=identicon)[rougin](/maintainers/rougin)

---

Top Contributors

[![rougin](https://avatars.githubusercontent.com/u/6078637?v=4)](https://github.com/rougin "rougin (59 commits)")

---

Tags

auth-logicphp-authphp-loginphp-authphp-loginauth-logic

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/rougin-authsum/health.svg)

```
[![Health](https://phpackages.com/badges/rougin-authsum/health.svg)](https://phpackages.com/packages/rougin-authsum)
```

###  Alternatives

[namshi/jose

JSON Object Signing and Encryption library for PHP.

1.8k99.6M101](/packages/namshi-jose)[league/oauth1-client

OAuth 1.0 Client Library

99698.8M106](/packages/league-oauth1-client)[gesdinet/jwt-refresh-token-bundle

Implements a refresh token system over Json Web Tokens in Symfony

70516.4M35](/packages/gesdinet-jwt-refresh-token-bundle)[league/oauth2-google

Google OAuth 2.0 Client Provider for The PHP League OAuth2-Client

41721.2M118](/packages/league-oauth2-google)[illuminate/auth

The Illuminate Auth package.

9327.3M1.0k](/packages/illuminate-auth)[beatswitch/lock

A flexible, driver based Acl package for PHP 5.4+

870304.7k2](/packages/beatswitch-lock)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)