PHPackages                             wscore/auth - 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. wscore/auth

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

wscore/auth
===========

Authentication helpers (v2). Breaking upgrade from pre-2.0 beta API.

0.4.1(5y ago)130MITPHPCI passing

Since Mar 10Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/WScore/Auth)[ Packagist](https://packagist.org/packages/wscore/auth)[ RSS](/packages/wscore-auth/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (1)Versions (11)Used By (0)

WScore.Auth
===========

[](#wscoreauth)

**v2** is built around `Identity` and `UserProviderInterface`.

It is **not API-compatible** with earlier **0.x (beta-era)** releases. Treat upgrades as a rewrite; breaking changes are expected.

### License

[](#license)

MIT License

### PSR

[](#psr)

PSR-1, PSR-2, and PSR-4.

### Requirements

[](#requirements)

PHP 8.2+

### Installation

[](#installation)

```
composer require "wscore/auth:^2.0"
```

Before v2 is tagged on Packagist, pin VCS / `@dev` / pre-release tags as needed.

Getting Started
---------------

[](#getting-started)

`Auth` requires a `UserProviderInterface` (`WScore\Auth\Contracts`) implementation.

```
$auth = new Auth($userProvider);
// optional: `new Auth($userProvider, $sessionStore)` for DI, or third arg for tests:
// `new Auth($userProvider, null, $sessionByRef)`
$auth->setSession($session); // optional; if not set, active `$_SESSION` is used when using the default array store
```

Password login (convenience):

```
use WScore\Auth\Auth;

if ($auth->loginWithPassword($id, $password)) {
    echo 'login success!';
}
```

Or with an `Identity` value object:

```
use WScore\Auth\Identity;

$ok = $auth->login(Identity::newPassword($id, $password));

// OAuth: provider user id (extract sub / id from raw responses in your bridge)
$ok = $auth->login(Identity::newOAuth('google', $googleUserId, [
    'email' => $email,
]));
// In UserProvider, read credentials[Identity::CREDENTIAL_PROVIDER_USER_ID]
```

Check login state:

```
$auth->isLogin();
$user = $auth->user();
$id = $auth->getLoginId();
$auth->getUserProvider(); // the UserProviderInterface instance
```

`user()` resolves in order: in-memory cache → session → remember-me cookie (if `setRememberMe` was configured).

**Note:** Calling `isLogin()` or `user()` may trigger an automatic login attempt via remember-me cookies if no active session exists. This can result in new cookies being sent or backend tokens being rotated.

```
$auth->logout(); // clears session segment, in-memory state, and remember-me cookies/tokens.
```

### Timeouts

[](#timeouts)

You can configure automatic logout based on the time elapsed since initial login (absolute timeout) or since the last access (activity timeout).

```
// Invalidate after 1 hour from initial login
$auth->setAbsoluteTimeout(3600);

// Invalidate after 15 minutes of inactivity
$auth->setActivityTimeout(900);
```

When a timeout is detected, `logout()` is automatically called during `isLogin()` or `user()`.

### AuthKind

[](#authkind)

`getLoginInfo()['kind']` and `isLoginBy()` use `WScore\Auth\AuthKind`: `Password`, `ForceLogin`, `OAuth`, `OneTimeToken`, `Remember`.

- **`Remember`** — the session was established via remember-me cookie validation (no password submitted on this login). This differs from password login with the “remember me” box checked, which stays **`Password`**.
- Use `isLoginBy(AuthKind::Remember)` (or inspect `getLoginInfo()['kind']`) to distinguish that path from interactive logins.

Other `Identity` constructors: `Identity::newForceLogin`, `Identity::newOneTimeToken`, `Identity::newRemember` (for providers that resolve remember pairs in `findByIdentity`).

### Force Login

[](#force-login)

```
use WScore\Auth\AuthKind;

$auth->forceLogin($id);
$auth->isLoginBy(AuthKind::ForceLogin);
```

`getLoginInfo()` includes `kind` (`AuthKind`), `loginId`, `type` (provider key), `time`.

UserProvider
------------

[](#userprovider)

Implement `WScore\Auth\Contracts\UserProviderInterface`:

- `findByIdentity(Identity $identity): ?object` — resolve and verify credentials.
- `getUserId(object $user): string|int` — id stored in session.
- `findByUserId(string|int $userId): ?object` — restore user from that id.
- `getProviderKey(): string` — session segment key (namespaces `Auth::KEY`).

Remember-Me Option
------------------

[](#remember-me-option)

Do **not** pass remember-me dependencies into the `Auth` constructor. Configure everything with **`setRememberMe()`** (e.g. after constructing `Auth` from a DI container factory).

`RememberCookie` handles HTTP cookies (id + token) and **lifetime in days** (default 7).

```
use WScore\Auth\RememberAdaptor\RememberCookie;

$auth = new Auth($userProvider, null, $session);

// Production: 30-day browser cookie (uses RememberCookie::forBrowser(30) internally)
$auth->setRememberMe($rememberMe, null, 30);

// Or pass an explicit RememberCookie
$auth->setRememberMe($rememberMe, RememberCookie::forBrowser(30));

// Tests: bag + replace setSetCookie
$bag = new \ArrayObject();
$cookie = new RememberCookie($bag, 7);
$cookie->setSetCookie($mockSetter);
$auth->setRememberMe($rememberMe, $cookie);
```

`$rememberMe` implements `WScore\Auth\Contracts\RememberMeInterface`. A PDO sample lives at `WScore\Auth\RememberAdaptor\RememberMePdoSample` (reference only—use your own in production). Call `setRememberMe(null)` to disable.

### Advanced

[](#advanced)

Constructor: `new Auth(UserProviderInterface $provider, ?AuthSessionStoreInterface $sessionStore = null, ?array &$session = null)`. When `$sessionStore` is null, an `ArrayAuthSessionStore` is built (PHP session or the passed `$session` array). When a store is injected, it is shared as usual; `read` / `write` / `clear` take a **segment key** (typically `UserProviderInterface::getProviderKey()`), so one implementation can serve multiple `Auth` instances.

`setAuthSessionStore(AuthSessionStoreInterface $store)` — replace the session store after construction (e.g. tests).

#### Session Regeneration

[](#session-regeneration)

By default, `Auth::login()` calls `session_regenerate_id(true)` for security (session fixation prevention). However, this can cause session loss on unstable networks or specific browser environments. You can disable this behavior if needed:

```
$auth->setRegenerateSessionOnLogin(false);
```

Enable on login:

```
$auth->loginWithPassword($id, $password, true);
// or Identity::newPassword($id, $password, ['remember' => true])
```

---

Japanese documentation: [README.ja.md](README.ja.md).

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance58

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 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

Every ~581 days

Recently: every ~775 days

Total

8

Last Release

62d ago

Major Versions

0.4.1 → 2.0.0-beta12026-04-06

### Community

Maintainers

![](https://www.gravatar.com/avatar/8ed783829e6fa0bd4b0def8c04ccfdfb2fc99f9e61e4a9470acad9e5abc5fcac?d=identicon)[asaokamei](/maintainers/asaokamei)

---

Top Contributors

[![asaokamei](https://avatars.githubusercontent.com/u/747030?v=4)](https://github.com/asaokamei "asaokamei (64 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wscore-auth/health.svg)

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

###  Alternatives

[kartik-v/yii2-password

Useful password strength validation utilities for Yii Framework 2.0

761.3M17](/packages/kartik-v-yii2-password)[vitalybaev/laravel5-dkim

Laravel 5/6 package for signing outgoing messages with DKIM.

3163.1k](/packages/vitalybaev-laravel5-dkim)

PHPackages © 2026

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