Laravel Magic Login

https://github.com/maize-tech/laravel-magic-login
Admin
Laravel Magic Login is a Laravel package that enables passwordless authentication by allowing users...
Tokens:32,397
Snippets:252
Trust Score:8.2
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Full customization

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/configuration.md

Full customization example showing all configuration options with example values and comments.

```php
use App\Models\MagicLogin;
use App\Actions\MySendMagicLinkAction;
use App\Notifications\MagicLinkNotification;
use App\Exceptions\MagicLoginException;

return [

    'model' => MagicLogin::class,

    'expiration' => 60,               // 1 hour
    'guard' => 'web',
    'redirect_url' => '/dashboard',

    'exception' => MagicLoginException::class, // zero-arg constructor

    'force_single' => true,
    'logins_limit' => 3,

    'send_notification_action' => MySendMagicLinkAction::class,
    'notification' => MagicLinkNotification::class,

    'route' => [
        'methods' => 'GET',
        'uri' => 'auth/magic-login',
        'name' => 'auth.magic-login',      // must match link generation routeName
        'controller' => \Maize\MagicLogin\Http\Controllers\MagicLoginController::class,
        'middleware' => [
            \Maize\MagicLogin\Http\Middleware\ValidateSignature::class,
        ],
    ],
];
```

--------------------------------

### Install via Composer

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/README.md

Install the package using Composer.

```bash
composer require maize-tech/laravel-magic-login
```

--------------------------------

### Minimal setup

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/configuration.md

Minimal setup. With this, MagicLink::make(authenticatable: $user) works without any per-call URL (otherwise it throws).

```php
return [
    'redirect_url' => '/home',
];
```

--------------------------------

### configurePackage method body

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginServiceProvider.md

Configures the package with name, config file, migration, and install command.

```php
$package
    ->name('laravel-magic-login')
    ->hasConfigFile()
    ->hasMigration('create_magic_logins_table')
    ->hasInstallCommand(
        fn (InstallCommand $command) => $command
            ->publishConfigFile()
            ->publishMigrations()
            ->askToRunMigrations()
            ->askToStarRepoOnGitHub('maize-tech/laravel-magic-login')
    );
```

--------------------------------

### Example magic login URL

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/endpoints.md

Example URL produced by MagicLink::make() or send(). Contains encrypted data, expiration timestamp, and signature as query parameters.

```text
GET https://yourapp.test/magic-login?data={encrypted}&expires={unix_timestamp}&signature={hash}
```

--------------------------------

### Example usage of MagicLink::send()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Shows how to call send() with named arguments. It sends the magic link notification to the user and returns the signed URL.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    redirectUrl: 'yourapplication.test/your-path',
);
// Equivalent to MagicLink::make(authenticatable: $user, redirectUrl: ..., notify: true);
```

--------------------------------

### Replacing or extending the middleware

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/ValidateSignature.md

Configuration example for customizing the route middleware, allowing custom middleware to run before the ValidateSignature middleware.

```php
// config/magic-login.php
'route' => [
    'middleware' => [
        \App\Http\Middleware\MyCustomMiddleware::class,     // runs first
        \Maize\MagicLogin\Http\Middleware\ValidateSignature::class,
    ],
],
```

--------------------------------

### Calling the config reader directly

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/Config.md

Shows how to resolve effective configuration values with overrides and handle failures. getExpiration() ignores config defaults, getGuard() returns 'web' unless set, getRouteMethods() returns ['GET'], and getRedirectUrl() throws an exception with message 'The redirect url is required.' on failure.

```php
use Maize\MagicLogin\Support\Config;

// Resolve effective values with overrides
$expiresAt = Config::getExpiration(now()->addHour()); // Carbon, ignores config/defaults
$guard = Config::getGuard();                          // 'web' (default) unless config set
$methods = Config::getRouteMethods();                 // ['GET']

// Respond to failures
try {
    $url = Config::getRedirectUrl();
} catch (\Exception $e) {
    // 'The redirect url is required.'
}
```

--------------------------------

### Creating and inspecting a link row (as MagicLink::make does)

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLogin.md

Example of creating a MagicLogin model instance with the required attributes and inspecting its generated fields. Uses Config::getModel()->create() to create the row, and demonstrates the uuid (generated by HasUuids), expires_at (Carbon datetime cast), and metadata (array cast) properties.

```php
use Maize\MagicLogin\Models\MagicLogin;
use Maize\MagicLogin\Support\Config;
use App\Models\User;

$user = User::first();

$model = Config::getModel()->create([
    'authenticatable_id' => $user->getKey(),
    'authenticatable_type' => $user->getMorphClass(),
    'logins' => 0,
    'logins_limit' => -1,
    'guard' => 'web',
    'redirect_url' => '/home',
    'expires_at' => now()->addMinutes(120),
    'metadata' => ['campaign' => 'spring'],
]);

echo $model->uuid;            // generated by HasUuids
echo $model->expires_at;      // Carbon (datetime cast)
echo $model->metadata['campaign']; // 'spring' (array cast)
```

--------------------------------

### Runtime override precedence

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/configuration.md

Runtime override precedence example showing that per-call arguments win over config values.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

// Per-call argument wins over config:
MagicLink::send(
    authenticatable: User::first(),
    redirectUrl: '/admin',   // overrides config('magic-login.redirect_url')
    guard: 'admin',          // overrides config('magic-login.guard')
    expiration: 10,          // overrides config('magic-login.expiration')
    loginsLimit: 1,          // overrides config('magic-login.logins_limit')
);
```

--------------------------------

### Usage and error handling (as the controller does)

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLogin.md

Example of querying a MagicLogin model by UUID, loading the authenticatable relation, and calling login() within a try-catch. Throws ModelNotFoundException if the link was revoked/deleted, and catches exceptions thrown when isAuthenticable() is false (related authenticatable deleted or logins_limit reached).

```php
use Maize\MagicLogin\Models\MagicLogin;

/** @var MagicLogin $model */
$model = MagicLogin::query()
    ->with('authenticatable')
    ->findOrFail($uuid);      // ModelNotFoundException if the link was revoked/deleted

try {
    $model->login();          // guard login + logins++
} catch (\Exception) {
    // thrown when isAuthenticable() is false:
    //  - related authenticatable was deleted, or
    //  - logins_limit reached (logins_limit !== -1 && logins >= logins_limit)
}
```

--------------------------------

### Generate Magic Link with make Method

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/README.md

Generates an invitation link for any model extending the Authenticatable class using the make method. The example uses a User model and passes the user as the authenticatable parameter.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::make(
    authenticatable: $user
);
```

--------------------------------

### revokeAll() usage example

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Example of revoking all magic login rows for a user by calling MagicLink::revokeAll($user).

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

MagicLink::revokeAll($user); // every pending magic login row for $user is deleted
```

--------------------------------

### AuthData error handling example

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/AuthData.md

Shows how to catch exceptions when decrypting a garbage string. DecryptException is swallowed and the configured exception (default InvalidSignatureException) is thrown.

```php
use Maize\MagicLogin\Support\AuthData;
use Illuminate\Routing\Exceptions\InvalidSignatureException;

try {
    $data = AuthData::fromString($garbage);
} catch (\Exception $e) {
    // DecryptException is swallowed and the configured exception is thrown
    // (default: InvalidSignatureException → 403)
    report($e);
}
```

--------------------------------

### AuthData round-trip example

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/AuthData.md

Shows the encode and decode sides as used internally by MagicLink::make and MagicLoginRequest::getAuthData. The encode side creates an encrypted string from an array; the decode side decrypts it back to the original array.

```php
use Maize\MagicLogin\Support\AuthData;

// Encode side (as used in MagicLink::make, src/MagicLink.php:40-46)
$payload = AuthData::fromArray([
    'uuid' => 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
])->toString();

// Decode side (as used in MagicLoginRequest::getAuthData)
$decoded = AuthData::fromString($payload)->toArray();
// ['uuid' => 'f47ac10b-58cc-4372-a567-0e02b2c3d479']
```

--------------------------------

### Custom request class

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginRequest.md

Example of extending MagicLoginRequest to add custom methods for additional data fields.

```php
namespace App\Http\Requests;

use Maize\MagicLogin\Http\Requests\MagicLoginRequest as BaseRequest;

class MyMagicLoginRequest extends BaseRequest
{
    public function getRedirectHint(): ?string
    {
        return data_get($this->getAuthData(), 'redirect_hint');
    }
}
```

--------------------------------

### Send magic link with custom metadata and query

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/README.md

Stores custom metadata for custom queries. The example shows how to query the MagicLogin model using `whereJsonContains` to count records with specific metadata values.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;
use Maize\MagicLogin\Models\MagicLogin;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    metadata: ['test' => true]
);

MagicLogin::query()
    ->whereJsonContains('metadata->test', true)
    ->count(); // returns 1

MagicLogin::query()
    ->whereJsonContains('metadata->test', false)
    ->count(); // returns 0
```

--------------------------------

### Sending through the package API

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLinkNotification.md

Example of sending a magic link notification using the MagicLink facade. The comment shows the internal Notification::send call.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

MagicLink::send(authenticatable: $user, redirectUrl: '/home');
// internally: Notification::send([$user], new MagicLinkNotification($uri, $model))
```

--------------------------------

### Usage inside a custom controller

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginRequest.md

Example of using MagicLoginRequest in a custom controller to retrieve the UUID and auth data.

```php
namespace App\Http\Controllers;

use Maize\MagicLogin\Http\Requests\MagicLoginRequest;

class DebugController
{
    public function __invoke(MagicLoginRequest $request)
    {
        $uuid = $request->uuid();              // 'f47ac10b-...'
        $authData = $request->getAuthData();   // ['uuid' => 'f47ac10b-...']
        return response()->json(compact('uuid', 'authData'));
    }
}
```

--------------------------------

### GET /magic-login

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/endpoints.md

Consumes a magic login link by validating the signed URL and logging in the associated user. Redirects to the configured redirect URL on success, or throws an exception on failure.

```APIDOC
## GET /magic-login

### Description
Consumes a magic login link by validating the signed URL and logging in the associated user. Redirects to the configured redirect URL on success, or throws an exception on failure.

### Method
GET

### Endpoint
/magic-login

### Parameters
#### Query Parameters
- **data** (string) - Required - Encrypted payload containing the user's UUID. Format: `Crypt::encryptString(json_encode(['uuid' => '{uuid}']))`.
- **expires** (int) - Required - UNIX timestamp after which the URL is rejected.
- **signature** (string) - Required - HMAC hash over the URL, verified by the `ValidateSignature` middleware.

### Request Example
```
GET https://yourapp.test/magic-login?data={encrypted}&expires={unix_timestamp}&signature={hash}
```

### Response
#### Success Response (302)
- Redirects to the magic login row's `redirect_url`.

#### Response Example
```
302 Redirect to https://yourapp.test/dashboard
```

#### Failure Response (403)
- **Invalid signature.** - Thrown when the signature is invalid, expired, missing, or when the row is not found or login fails.

#### Response Example
```
403 Forbidden
Invalid signature.
```

### Auth Requirements
None on the route itself. The route authenticates the user onto the configured guard; it is not protected by `auth`.
```

--------------------------------

### Publish Config and Migration Files

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/README.md

Run the artisan command to publish the config and migration files and run the migrations.

```bash
php artisan magic-login:install
```

--------------------------------

### Run tests with Composer

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/README.md

Executes the project's test suite using Composer. Run this command from the project root to verify the package works as expected.

```bash
composer test
```

--------------------------------

### route() internal implementation

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Shows the internal implementation of route() using Route::match with configuration values for methods, URI, action, name, and middleware.

```php
Route::match(
    methods: Config::getRouteMethods(),
    uri: Config::getRouteUri(),
    action: Config::getRouteController()
)
    ->name(Config::getRouteName())
    ->middleware(Config::getRouteMiddleware());
```

--------------------------------

### Basic usage of MagicLink::make()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Creates a magic login link for a user with default options. The redirect URL, expiration, guard, and other settings fall back to configuration values.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::make(
    authenticatable: $user,
);
```

--------------------------------

### make()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Creates a magic login link for an authenticatable model and returns the signed URL. This is the primary generator method.

```APIDOC
## make()

### Description
Creates a magic login link for an authenticatable model and returns the signed URL. This is the primary generator method.

### Signature
```php
public function make(
    Authenticatable $authenticatable,
    ?string $redirectUrl = null,
    Carbon|int|null $expiration = null,
    ?string $routeName = null,
    ?string $guard = null,
    ?int $loginsLimit = null,
    array $metadata = [],
    bool $notify = false
): string
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `authenticatable` | `Authenticatable` | Yes | — | The model to log in when the link is used. Its `getKey()` becomes `authenticatable_id` and `getMorphClass()` becomes `authenticatable_type` on the stored row. |
| `redirectUrl` | `?string` | No | `null` → `config('magic-login.redirect_url')` → throws | Destination after successful login. If `null` and no config value exists, `Config::getRedirectUrl()` throws. |
| `expiration` | `Carbon\|int\|null` | No | `null` → `config('magic-login.expiration')` → `120` | Either a `Carbon` instance (used as-is) or an int number of minutes from now. Applied to both the row's `expires_at` and the signed URL's `expires` parameter. |
| `routeName` | `?string` | No | `null` → `config('magic-login.route.name')` → `'magic-login'` | Name of the route the signed link points at. |
| `guard` | `?string` | No | `null` → `config('magic-login.guard')` → `'web'` | Auth guard used at login time (stored per row). |
| `loginsLimit` | `?int` | No | `null` → `config('magic-login.logins_limit')` → `-1` | Number of allowed logins `>= 1`, or `-1` for unlimited. `Config::getLoginLimits()` throws for `< -1` or `0`. |
| `metadata` | `array` | No | `[]` | Arbitrary data stored in the JSON `metadata` column; queryable via `whereJsonContains` at consumption time. |
| `notify` | `bool` | No | `false` | When `true`, sends the notification after generating the URI via `Config::getSendNotificationAction()`. |

### Return Value
`string` — the absolute temporary signed URL, e.g. `https://yourapp.test/magic-login?data={encrypted}&expires={ts}&signature={hash}`.

### Behavior
1. If `Config::forceSingle()` is `true`, all existing rows for this authenticatable are deleted first (`revokeAll`).
2. A new row is created on `Config::getModel()` with `logins` = `0` and the resolved values for `logins_limit`, `guard`, `redirect_url`, `expires_at`, `metadata`.
3. The URI is built with `URL::temporarySignedRoute(name: ..., expiration: ..., parameters: ['data' => AuthData::fromArray(['uuid' => $model->uuid])->toString()])`.
4. If `notify` is `true`, the send-notification action is invoked with `uri` and `model`.

### Throws
| Error | Condition |
|-------|-----------|
| `Exception` | Redirect URL not provided and no config default (`Config::getRedirectUrl`) |
| `Exception` | `loginsLimit < -1` or `loginsLimit === 0` (`Config::getLoginLimits`) |

### Examples
Basic call:
```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::make(
    authenticatable: $user,
);
```

Non-trivial options + error handling:
```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

try {
    // 5 logins max, expires in 60 minutes, custom guard and metadata
    $uri = MagicLink::make(
        authenticatable: $user,
        redirectUrl: '/dashboard',
        expiration: 60,
        guard: 'admin',
        loginsLimit: 5,
        metadata: ['campaign' => 'spring-sale'],
        notify: true, // sends MagicLinkNotification as well
    );
} catch (\Exception $e) {
    // raised by Config::getLoginLimits() if loginsLimit is 0 or < -1,
    // or by Config::getRedirectUrl() if no redirect url is available
    report($e);
}
```
```

--------------------------------

### Full published config skeleton

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/configuration.md

Exact structure of config/magic-login.php (190 lines, all values null in the published file).

```php
return [

    'model' => null,
    'expiration' => null,
    'guard' => null,
    'redirect_url' => null,
    'exception' => null,
    'force_single' => null,
    'logins_limit' => null,
    'send_notification_action' => null,
    'notification' => null,

    'route' => [
        'methods' => null,
        'uri' => null,
        'name' => null,
        'controller' => null,
        'middleware' => null,
    ],

];
```

--------------------------------

### configurePackage method signature

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginServiceProvider.md

Signature of the configurePackage method.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### toMail() method

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLinkNotification.md

Builds the mail message with an intro line, a 'Sign in' action button, and an expiry line using the model's expires_at.

```php
public function toMail($notifiable)
{
    return (new MailMessage)
        ->line(__('You are receiving this email because we received a sign in request for your account.'))
        ->action(__('Sign in'), $this->uri)
        ->line(__('This sign in link will expire at :date.', ['date' => $this->model->expires_at]));
}
```

--------------------------------

### make() method signature

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

The exact signature of the make() method from src/MagicLink.php:14-56. It accepts an Authenticatable model and optional parameters for redirect URL, expiration, route name, guard, login limit, metadata, and notification flag.

```php
public function make(
    Authenticatable $authenticatable,
    ?string $redirectUrl = null,
    Carbon|int|null $expiration = null,
    ?string $routeName = null,
    ?string $guard = null,
    ?int $loginsLimit = null,
    array $metadata = [],
    bool $notify = false
): string
```

--------------------------------

### Constructor signature

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLinkNotification.md

The constructor accepts a signed URI and the MagicLogin model. Both parameters are promoted protected properties, accessible in subclasses.

```php
public function __construct(
    protected string $uri,
    protected MagicLogin $model
) {
    //
}
```

--------------------------------

### Custom exception class for magic link failures

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/errors.md

Set config('magic-login.exception') to a zero-arg-constructible exception class to control the HTTP status. The example defines a custom MagicLoginException extending HttpException with status 419 and message 'Magic link invalid or expired.', configures it in config/magic-login.php, and catches it in the Laravel exception handler to render a custom view.

```php
// app/Exceptions/MagicLoginException.php
namespace App\Exceptions;

use Symfony\Component\HttpKernel\Exception\HttpException;

class MagicLoginException extends HttpException
{
    public function __construct()
    {
        parent::__construct(419, 'Magic link invalid or expired.');
    }
}

```

```php
// config/magic-login.php
'exception' => \App\Exceptions\MagicLoginException::class,

```

```php
// app/Exceptions/Handler.php
public function render($request, Throwable $e)
{
    if ($e instanceof \App\Exceptions\MagicLoginException) {
        return response()->view('errors.magic-link', ['message' => $e->getMessage()], 419);
    }

    return parent::render($request, $e);
}

```

--------------------------------

### send()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Creates a signed magic login URL and sends a notification to the given authenticatable. It is a convenience wrapper for make() with notify: true.

```APIDOC
## send()

### Description
Convenience wrapper: identical to `make(...)` with `notify: true` hard-coded. Creates a signed magic login URL and sends a notification to the given authenticatable.

### Method
send

### Signature
```php
public function send(
    Authenticatable $authenticatable,
    ?string $redirectUrl = null,
    ?Carbon $expiration = null,
    ?string $routeName = null,
    ?string $guard = null,
    ?int $loginsLimit = null,
    array $metadata = [],
): string
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `authenticatable` | `Authenticatable` | Yes | — | As in `make()`. |
| `redirectUrl` | `?string` | No | `null` → config → throws | As in `make()`. |
| `expiration` | `?Carbon` | No | `null` → config → `120` minutes | Carbon instance only (per signature); forwarded to `make()`. |
| `routeName` | `?string` | No | `null` → config → `'magic-login'` | As in `make()`. |
| `guard` | `?string` | No | `null` → config → `'web'` | As in `make()`. |
| `loginsLimit` | `?int` | No | `null` → config → `-1` | As in `make()`. |
| `metadata` | `array` | No | `[]` | As in `make()`. |

### Return Value
`string` — the signed URL; additionally sends the notification (default `MagicLinkNotification`) to the authenticatable.

### Throws
Same as `make()` (both validation exceptions and any failure from the notification send action).

### Example
```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

$magicLink = MagicLink::send(
    authenticatable: $user,
    redirectUrl: 'yourapplication.test/your-path',
);
// Equivalent to MagicLink::make(authenticatable: $user, redirectUrl: ..., notify: true);
```
```

--------------------------------

### Default flow: register route and generate URL

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginController.md

Two code blocks showing the default flow. The first registers the magic login route in routes/web.php. The second shows how to generate a magic link on the generation side. Visiting the generated URI logs the user in and redirects to the specified URL.

```php
// routes/web.php — register the route, then visit the generated URL
use Maize\MagicLogin\Facades\MagicLink;

MagicLink::route();
```

```php
// generation side
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$uri = MagicLink::send(authenticatable: User::first(), redirectUrl: '/dashboard');
// Visiting $uri → controller logs the user in → redirect to /dashboard
```

--------------------------------

### Registering the route with default middleware

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/ValidateSignature.md

Shows how to register the magic login route using the default ValidateSignature middleware via the MagicLink facade.

```php
use Maize\MagicLogin\Facades\MagicLink;

MagicLink::route(); // middleware: [Maize\MagicLogin\Http\Middleware\ValidateSignature::class]
```

--------------------------------

### Customizing by subclassing

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLinkNotification.md

Shows how to subclass the base notification and override toMail(). The $this->uri property is accessible. Then set the class in config/magic-login.php.

```php
use Illuminate\Notifications\Messages\MailMessage;
use Maize\MagicLogin\Notifications\MagicLinkNotification as BaseMagicLinkNotification;

class MagicLinkNotification extends BaseMagicLinkNotification
{
    public function toMail($notifiable): MailMessage
    {
        return (new MailMessage)
            ->line(__('This is my custom magic link notification message'))
            ->action(__('Join now'), $this->uri);   // $this->uri is accessible
    }
}
```

```php
'notification' => \App\Notifications\MagicLinkNotification::class,
```

--------------------------------

### Custom controller: config and subclass

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginController.md

Two code blocks showing how to use a custom controller. The first is a config snippet pointing 'route.controller' to a custom controller class and setting a default redirect_url. The second is the custom controller subclass that overrides __invoke() to add extra side effects after calling parent::__invoke().

```php
// config/magic-login.php
'route' => [
    'controller' => \App\Http\Controllers\CustomMagicLoginController::class,
],

'redirect_url' => '/home', // config default fallback
```

```php
namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Routing\Redirector;
use Maize\MagicLogin\Http\Controllers\MagicLoginController;
use Maize\MagicLogin\Http\Requests\MagicLoginRequest;

class CustomMagicLoginController extends MagicLoginController
{
    public function __invoke(MagicLoginRequest $request): Redirector|RedirectResponse
    {
        $response = parent::__invoke($request);

        // extra side effects (audit log, cookies, etc.) here

        return $response;
    }
}
```

--------------------------------

### login() method signature

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLogin.md

Authenticates the related authenticatable on the row's guard and increments the logins counter. Throws an unparameterized \Exception when not authenticable.

```php
public function login(): self
```

--------------------------------

### getRouteMiddleware()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/Config.md

Returns the middleware class name(s) applied to the magic login route. Accepts an optional middleware parameter that defaults to the configured middleware.

```APIDOC
## getRouteMiddleware()

### Description
Returns the middleware class name(s) applied to the magic login route. Accepts an optional middleware parameter that defaults to the configured middleware.

### Signature
```php
public static function getRouteMiddleware(array|string|null $middleware = null): array
```

### Parameters
- `middleware` (array|string|null) - Optional - Middleware class name(s). Defaults to `config('magic-login.route.middleware')` then `ValidateSignature::class`.

### Returns
- `array` - The middleware class name(s) wrapped via `Arr::wrap()`.
```

--------------------------------

### route() method signature

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Declares the public route() method with no parameters and no return type.

```php
public function route()
```

--------------------------------

### __invoke(MagicLoginRequest $request): Redirector|RedirectResponse

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginController.md

Handles a magic login URL visit. Validates the signed request, loads the magic login record by UUID, authenticates the related user, and redirects to the configured URL. On failure, logs out the current guard and throws the configured exception.

```APIDOC
## __invoke(MagicLoginRequest $request): Redirector|RedirectResponse

### Description
Handles a magic login URL visit. Validates the signed request, loads the magic login record by UUID, authenticates the related user, and redirects to the configured URL. On failure, logs out the current guard and throws the configured exception.

### Method
__invoke (invokable controller method)

### Endpoint
Handled via the route registered by `MagicLink::route()` (default route action).

### Parameters
#### Path Parameters
- **request** (MagicLoginRequest) - Required - Form request injected by the router; validated signature plus the decrypted `data` payload (`uuid()`) are already available.

### Request Example
No explicit request body is documented. The request is a signed URL with a `data` parameter containing the UUID.

### Response
#### Success Response (200)
- **Redirector|RedirectResponse** - Redirect to `$model->redirect_url`.

#### Response Example
Redirect response to the configured redirect URL.

### Error Handling
- On any `Exception` (e.g., `ModelNotFoundException`, bare `Exception` from `login()`), the current guard session is logged out and `Config::getException()` is thrown (default `InvalidSignatureException`, HTTP 403).
- Before the handler runs, the `ValidateSignature` middleware throws `Config::getException()` for missing/expired/tampered signatures.
```

--------------------------------

### MagicLinkNotification

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLinkNotification.md

Documentation for the MagicLinkNotification class constructor and its methods (via, toMail, toArray) as they can be called directly by users. Includes parameter details and return types.

```APIDOC
## Constructor __construct(string $uri, MagicLogin $model)

### Description
Creates a new MagicLinkNotification instance with the signed magic login URI and the magic login model. Both parameters are promoted to protected properties so subclasses can access them.

### Parameters
- **uri** (string) - Required - The signed magic login URL used as the email action button link.
- **model** (MagicLogin) - Required - The magic login row; `$model->expires_at` is used in the email body and `$model->authenticatable` is the recipient.

### Returns
- No return value (constructor).
```

```APIDOC
## Method via($notifiable)

### Description
Returns the notification delivery channels. Always returns `['mail']` for the mail channel only.

### Parameters
- **$notifiable** (mixed) - Required - The notifiable being notified (the authenticatable model).

### Returns
- **array** - Always `['mail']`.
```

```APIDOC
## Method toMail($notifiable)

### Description
Builds the mail message. Adds an intro line, a `Sign in` action button pointing to the signed URI, and an expiry line using `$model->expires_at`.

### Parameters
- **$notifiable** (mixed) - Required - The notifiable being notified.

### Returns
- **Illuminate\Notifications\Messages\MailMessage** - The mail message with three lines.
```

```APIDOC
## Method toArray($notifiable)

### Description
Returns the array representation for database/array channels. Returns an empty array as no data is provided.

### Parameters
- **$notifiable** (mixed) - Required - The notifiable being notified.

### Returns
- **array** - Always an empty array.
```

--------------------------------

### Flow diagram of magic login request handling

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/endpoints.md

Visual flow of the request lifecycle: from clicking the link, through signature validation, controller handling, and redirect. Shows failure paths and success path.

```text
[user clicks magic link]
   │  GET /magic-login?data&expires&signature
   ▼
ValidateSignature (middleware)
   ├─ signature invalid / expired / missing ──► throw Config::getException()  → 403
   ▼
MagicLoginController::__invoke(MagicLoginRequest)
   ├─ row not found (revoked/deleted/never existed) ──► logout guard, throw Config::getException() → 403
   ├─ login() fails (user deleted / quota exhausted) ──► logout guard, throw Config::getException() → 403
   ▼
auth()->guard($row->guard)->login($authenticatable); $row->increment('logins')
   ▼
302 redirect → $row->redirect_url
```

--------------------------------

### Published Config File

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/README.md

The default configuration file published by the package. It includes settings for the magic login model, expiration time, authentication guard, default redirect URL, exception class, force single link, and logins limit.

```php
return [

    /*
    |--------------------------------------------------------------------------
    | Magic Login model
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the magic login
    | model.
    | By default, the value is Maize\MagicLogin\Models\MagicLogin::class
    |
    */

    'model' => null,

    /*
    |--------------------------------------------------------------------------
    | Expiration time
    |--------------------------------------------------------------------------
    |
    | Here you may specify the amount of minutes before the magic login link
    | expires.
    | By default, the value is 120 minutes (2 hours).
    |
    */

    'expiration' => null,

    /*
    |--------------------------------------------------------------------------
    | Authentication guard
    |--------------------------------------------------------------------------
    |
    | Here you may specify the guard you want to use to authenticate the user.
    | The guard name must be defined in your application's auth.php config file.
    | By default, the value is 'web'.
    |
    */

    'guard' => null,

    /*
    |--------------------------------------------------------------------------
    | Default redirect url
    |--------------------------------------------------------------------------
    |
    | Here you may specify the redirect url used by default if none is specified
    | when creating the magic link.
    |
    */

    'redirect_url' => null,

    /*
    |--------------------------------------------------------------------------
    | Exception class
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default exception class used for all package
    | related exceptions.
    | Useful if you need to customize the http status code in case an exception
    | is thrown during the magic login process.
    | By default, the value is Illuminate\Routing\Exceptions\InvalidSignatureException::class
    |
    */

    'exception' => null,

    /*
    |--------------------------------------------------------------------------
    | Force single link
    |--------------------------------------------------------------------------
    |
    | Here you can specify whether a user can only have one valid magic link
    | at a time or not.
    | If true, when you generate a new magic link for a specific user all
    | previously generated links will be revoked.
    | By default, the value is true.
    |
    */

    'force_single' => null,

    /*
    |--------------------------------------------------------------------------
    | Logins limit
    |--------------------------------------------------------------------------
    |
    | Here you can specify the amount of logins a user can perform with the
    | same magic link.
    | Can be either -1, which lets the user login indefinitely, or any number
    | greater than or equal to 1.
    | By default, the value is -1.
    |
    */

    'logins_limit' => null,

]
```

--------------------------------

### MagicLink Facade Static Method Annotations

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

PHPDoc annotations on the facade declaring the static methods make and send, with their parameters and return types. These methods are used to generate and send magic login links.

```php
/**
 * @method static string make(\Illuminate\Contracts\Auth\Authenticatable $authenticatable, ?string $redirectUrl = null, \Illuminate\Support\Carbon|int|null $expiration = null, ?string $routeName = null, ?string $guard = null, ?int $loginsLimit = null, array $metadata = [], bool $notify = false)
 * @method static string send(\Illuminate\Contracts\Auth\Authenticatable $authenticatable, ?string $redirectUrl = null, \Illuminate\Support\Carbon|int|null $expiration = null, ?string $routeName = null, ?string $guard = null, ?int $loginsLimit = null, array $metadata = [])
 *
 * @see \Maize\MagicLogin\MagicLink
 */
```

--------------------------------

### handle()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/ValidateSignature.md

Handles the incoming request by delegating to Laravel's signed-URL validation and rethrowing a package-configured exception on failure.

```APIDOC
## handle()

### Description
Validates the signed URL of the incoming request. Delegates to Laravel's built-in ValidateSignature middleware and rethrows a package-configured exception if the signature is invalid.

### Method
handle

### Signature
public function handle($request, Closure $next, ...$args)

### Parameters
- **$request** (mixed) - Required - The incoming request.
- **$next** (Closure) - Required - Next middleware / route handler.
- **...$args** (mixed) - Optional - Variadic args forwarded to Laravel's base middleware (e.g., `relative`, `ignoreExpired`).

### Behavior
1. Delegates to `Illuminate\Routing\Middleware\ValidateSignature::handle()` to verify the signed-URL `signature`, `expires` timestamp, and payload query parameters.
2. Catches `InvalidSignatureException` and rethrows `Config::getException()` (default: `InvalidSignatureException` with HTTP 403, or a custom class configured via `config('magic-login.exception')`).

### Returns
- The parent handle result (request passed through / response) on success.

### Throws
- `Config::getException()` instance on signature failure.

### Example — registering the route with default middleware
```php
use Maize\MagicLogin\Facades\MagicLink;

MagicLink::route(); // middleware: [Maize\MagicLogin\Http\Middleware\ValidateSignature::class]
```

### Example — replacing or extending the middleware
```php
// config/magic-login.php
'route' => [
    'middleware' => [
        \App\Http\Middleware\MyCustomMiddleware::class,     // runs first
        \Maize\MagicLogin\Http\Middleware\ValidateSignature::class,
    ],
],
```
```

--------------------------------

### MagicLink::make() with options and error handling

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLink.md

Generates a magic link with custom redirect URL, expiration, guard, login limit, metadata, and notification. Wraps the call in a try-catch to handle exceptions from Config::getLoginLimits() or Config::getRedirectUrl().

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

$user = User::firstOrFail();

try {
    // 5 logins max, expires in 60 minutes, custom guard and metadata
    $uri = MagicLink::make(
        authenticatable: $user,
        redirectUrl: '/dashboard',
        expiration: 60,
        guard: 'admin',
        loginsLimit: 5,
        metadata: ['campaign' => 'spring-sale'],
        notify: true, // sends MagicLinkNotification as well
    );
} catch (\Exception $e) {
    // raised by Config::getLoginLimits() if loginsLimit is 0 or < -1,
    // or by Config::getRedirectUrl() if no redirect url is available
    report($e);
}
```

--------------------------------

### MagicLoginController __invoke() method signature

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginController.md

The exact signature of the __invoke() method from the source file. It accepts a MagicLoginRequest and returns a Redirector or RedirectResponse.

```php
public function __invoke(MagicLoginRequest $request): Redirector|RedirectResponse
```

--------------------------------

### getLoginLimits()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/Config.md

Retrieves the login limit value. If no argument is provided, it falls back to the magic-login.logins_limit configuration value, defaulting to -1 (unlimited). Validates that the limit is not less than -1 or equal to 0.

```APIDOC
## getLoginLimits()

### Description
Retrieves the login limit value. If no argument is provided, it falls back to the magic-login.logins_limit configuration value, defaulting to -1 (unlimited). Validates that the limit is not less than -1 or equal to 0.

### Signature
```php
public static function getLoginLimits(?int $loginLimits = null): int
```

### Parameters
- **loginLimits** (`?int`) - Optional - The login limit. Must be -1 (unlimited) or >= 1. Defaults to `null`, which resolves to `config('magic-login.logins_limit')` or `-1`.

### Returns
`int` - The validated limit.

### Throws
- `\Exception('The logins limit cannot be less than -1')` when the value is less than -1.
- `\Exception('The logins limit cannot be equal to 0')` when the value is exactly 0.
```

--------------------------------

### MagicLoginServiceProvider class declaration

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/MagicLoginServiceProvider.md

Declares the MagicLoginServiceProvider class extending PackageServiceProvider.

```php
class MagicLoginServiceProvider extends PackageServiceProvider
```

--------------------------------

### getRouteController()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/Config.md

Returns the invokable controller FQCN used for the magic login route. Accepts an optional controller parameter that defaults to the configured controller class.

```APIDOC
## getRouteController()

### Description
Returns the invokable controller FQCN used for the magic login route. Accepts an optional controller parameter that defaults to the configured controller class.

### Signature
```php
public static function getRouteController(?string $controller = null): string
```

### Parameters
- `controller` (?string) - Optional - Invokable controller FQCN. Defaults to `config('magic-login.route.controller')` then `MagicLoginController::class`.

### Returns
- `string` - The controller FQCN.
```

--------------------------------

### getRedirectUrl()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/Config.md

Retrieves the post-login redirect URL. If no argument is provided, it falls back to the magic-login.redirect_url configuration value. Throws an exception if neither is set.

```APIDOC
## getRedirectUrl()

### Description
Retrieves the post-login redirect URL. If no argument is provided, it falls back to the magic-login.redirect_url configuration value. Throws an exception if neither is set.

### Signature
```php
public static function getRedirectUrl(?string $redirectUrl = null): string
```

### Parameters
- **redirectUrl** (`?string`) - Optional - Post-login redirect destination. Defaults to `null`, which resolves to `config('magic-login.redirect_url')`.

### Returns
`string` - The redirect URL.

### Throws
- `\Exception('The redirect url is required.')` when both the argument and the config value are missing.
```

--------------------------------

### getGuard()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/api-reference/Config.md

Retrieves the guard name to be used for authentication. If no argument is provided, it falls back to the magic-login.guard configuration value, defaulting to 'web'.

```APIDOC
## getGuard()

### Description
Retrieves the guard name to be used for authentication. If no argument is provided, it falls back to the magic-login.guard configuration value, defaulting to 'web'.

### Signature
```php
public static function getGuard(?string $guard = null): string
```

### Parameters
- **guard** (`?string`) - Optional - Guard name, must be defined in the app's `config/auth.php`. Defaults to `null`, which resolves to `config('magic-login.guard')` or `'web'`.

### Returns
`string` - The guard name.

### Throws
No exceptions are documented for this method.
```

--------------------------------

### GET|HEAD /magic-login

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/index.md

The default HTTP route for handling magic login requests. It validates the signature and invokes the MagicLoginController to authenticate the user.

```APIDOC
## GET|HEAD /magic-login

### Description
Handles magic login requests by validating the signature and invoking the controller to authenticate the user.

### Method
GET|HEAD

### Endpoint
/magic-login

### Parameters
#### Query Parameters
- **data** (string) - Required - The encrypted payload.
- **expires** (integer) - Required - The expiration timestamp.
- **signature** (string) - Required - The signature hash.

### Middleware
- Maize\MagicLogin\Http\Middleware\ValidateSignature

### Handler
MagicLoginController (invokable)

### Route Name
magic-login
```

--------------------------------

### Catch exceptions around MagicLink::make()

Source: https://github.com/maize-tech/laravel-magic-login/blob/main/_autodocs/errors.md

Catch the three plain Exceptions (catalog items 1–3) thrown synchronously when generating a magic link. The try-catch wraps MagicLink::make() and reports the exception, with comments listing the exact messages for missing redirect url, loginsLimit < -1, and loginsLimit === 0.

```php
use App\Models\User;
use Maize\MagicLogin\Facades\MagicLink;

try {
    MagicLink::make(authenticatable: User::first());
} catch (\Exception $e) {
    // 'The redirect url is required.'            — no redirect url anywhere
    // 'The logins limit cannot be less than -1'  — loginsLimit < -1
    // 'The logins limit cannot be equal to 0'    — loginsLimit === 0
    report($e);
}

```
Tokens:
Raw