README

Null Guard for Laravel. Designed for Middleware-based authentication and testing.

Requirements

• PHP: ^8.2
• Laravel: ^11.0 || ^12.0

Note

Older versions have outdated dependency requirements. If you cannot prepare the latest environment, please refer to past releases.

Installing

composer require mpyw/null-auth

Features

NullAuthenticatable family

• ❗️shows containing abstract methods.
• Strict traits throw BadMethodCallException on bad method calls.

NullGuard

• NullGuard::user() always returns Authenticatable already set by NullGuard::setUser().
• NullGuard::unsetUser() can unset user.

NullUserProvider

• All methods do nothing and always returns falsy value.

Usage

Basic Usage

Edit your config/auth.php.

<?php return [ /* ... */ /*  |--------------------------------------------------------------------------  | Authentication Guards  |--------------------------------------------------------------------------  |  | Next, you may define every authentication guard for your application.  | Of course, a great default configuration has been defined for you  | here which uses session storage and the Eloquent user provider.  |  | All authentication drivers have a user provider. This defines how the  | users are actually retrieved out of your database or other storage  | mechanisms used by this application to persist your user's data.  |  | Supported: "session", "token"  |  */ 'guards' => [ 'web' => [ 'driver' => 'null', // Use NullGuard for "web" 'provider' => 'users', ], 'api' => [ 'driver' => 'token', 'provider' => 'users', 'hash' => false, ], ], /*  |--------------------------------------------------------------------------  | User Providers  |--------------------------------------------------------------------------  |  | All authentication drivers have a user provider. This defines how the  | users are actually retrieved out of your database or other storage  | mechanisms used by this application to persist your user's data.  |  | If you have multiple user tables or models you may configure multiple  | sources which represent each model / table. These sources may then  | be assigned to any extra authentication guards you have defined.  |  | Supported: "database", "eloquent"  |  */ 'providers' => [ 'users' => [ 'driver' => 'null', // Use NullUserProvider for "users" ], // 'users' => [ // 'driver' => 'eloquent', // 'model' => App\User::class, // ], // 'users' => [ // 'driver' => 'database', // 'table' => 'users', // ], ], /* ... */ ];

Motivation

Guard-based API Authentication

Consider authentication that sends HTTP requests to the external platform.

In such a situation, you will probably use RequestGuard through Auth::viaRequest() call. However, some methods on the contracts UserProvider and Authenticatable are unsuitable for that. They heavily rely on the following flow:

1. Retrieve a user from database by email address
2. Verify user's password hash

This library provides a helper that makes the useless contract methods to do nothing; always return nullish or falsy values.

Now we include NullAuthenticatable trait on a user model.

<?php namespace App; use Illuminate\Contracts\Auth\Authenticatable; use Illuminate\Database\Eloquent\Model; use Mpyw\NullAuth\NullAuthenticatable; class User extends Model implements Authenticatable { use NullAuthenticatable; }

Then only getAuthIdentifierName() and getAuthIdentifier() are provided as a valid implementation.

<?php $user = User::find(1); // Minimal implementation for Authenticatable var_dump($user->getAuthIdentifierName()); // string(2) "id" var_dump($user->getAuthIdentifier()); // int(1) // Useless implementation for Authenticatable when we don't use StatefulGuard var_dump($user->getAuthPassword()); // string(0) "" var_dump($user->getRememberTokenName()); // string(0) "" var_dump($user->getRememberToken()); // string(0) "" $user->setRememberToken('...'); // Does nothing

Middleware-based Authentication

Suppose you hate using RequestGuard and wish implementing authentication on middleware.

Methods such as Auth::user() cause side effects when called for the first time on each request. This may lead to inappropriate behaviors if you concentrate authentication on middleware and use Auth::user() only as a container for Authenticatable object.

Don't worry. This library provides NullGuard, which is exactly as a simple Authenticatable container that you want. Auth::user() does nothing but returning the cached Authenticatable. You can just focus on calling Auth::setUser() on your cool middleware at ease.

<?php namespace App\Http\Middleware; use App\User; use Closure; use Illuminate\Http\Request; use Illuminate\Support\Facades\Auth; use Example\API\Authentication\Client; class AuthenticateThroughExternalAPI { /**  * @var \Example\API\Authentication\Client  */ protected $client; /**  * @param \Example\API\Authentication\Client $client  */ public function __construct(Client $client) { $this->client = $client; } /**  * @param \Illuminate\Http\Request $request  * @param \Closure $next  * @return mixed  */ public function handle(Request $request, Closure $next) { // Return user_id on success, throw AuthenticationException on failure $userId = $this->client->authenticate($request->input('token')); // Return User on success, throw ModelNotFoundException on failure $user = User::findOrFail($userId); Auth::setUser($user); return $next($request); } }

Testing

Needless to say, it is also useful for testing. There is no worry about causing side effects.