Signed URLs are available in Laravel since version 5.6, but in my experience they aren’t known enough.

📌 We assume you have the login view with a form with only the email field.

We need just 2 routes, that is…

Route 1: Post user email

This route:

• receive the user email

• create a Signed URL

• and send it to user via email (or other channel).

// routes/web.php

Route::post('/passwordless/login', function(Request $request) {
    // please, move me to a Controller ;)

    $request->validate([
        'email' => 'required|email'
    ]);

    $user = User::query()
        ->where('email', $request->email)
        ->first();

    if ($user) {
        $passwordlessUrl = \URL::temporarySignedRoute(
            'passwordless.login',
            now()->addMinutes(10),
            ['user' => $user->id]
        );

        // notify user via email or other channel...
        $user->notify(new PasswordlessNotification($passwordlessUrl));
    }
    // else... we send always a success message to avoid any "info extraction"

    return back()->with('success', 'You have an email!');
});

Route 2: check signature and login

Here, we have the route that login the user:

• it receive the user id (the model is loaded automatically by Model Binding)

• it validate signature (🎯 it’s really important! 😎)

• and finally login the user.

// routes/web.php

Route::get('/passwordless/login/{user}', function(Request $request, User $user) {
    // please, move me to a Controller ;)

    if (! $request->hasValidSignature()) {
        abort(401);
    }

    \Auth::login($user);

    return redirect('/');

})->name('passwordless.login');

…and that’s it!

The PasswordlessNotification class

In the Route 1, we assumed that you have a PasswordNotification class.

For simply do that:

php artisan make:notification PasswordlessNotification

And then:

// app/Notifications/PasswordlessNotification.php

class PasswordlessNotification extends Notification
{
    use Queueable;

    public function __construct(
        public string $passwordlessUrl
    ) {}

    public function via(object $notifiable): array
    {
        return ['mail'];
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('Your magic link to login')

            ->line("Hi {$notifiable->firstname}")
            ->line('you can login by the link below:')
            ->action('Login', $this->passwordlessUrl)

            ->line('Thank you for using our application!');
    }
}

Some important considerations

First of all: is it secure?

The short answer is: it depends.

I'll state the obvious, but it's important to be clear: the tutorial above doesn't cover every situation!

In some simple situations this may be enough, but in many others it is not!

On the other hand, it says "Easiest" in the title!

Some question that you need to ask yourself:

• What is the context?

• What is the level of risk to manage?

• What additional security mechanisms are needed?

Do you hate Passwordless Login in general?

If the answer is true, this tutorial is not for you.

After years of development, I have met many developers (even good ones!) who don't even want to consider systems of this type.

I think that everything needs to be put into context: booking on the barbershop app is not the same as accessing home banking!

If the barbershop app asked me for 2FA with an external app... I would actually laugh. But worse, if the barbershop app asked me to enter a password, I'd be worried. What is the probability that it would store my password securely? I've seen so many DBs with passwords saved in MD5 or so.

How can we improve the tutorial above?

1. Add nonce to URL

2. One-time use of URL (for example, using Cache (or DB) to invalidate used URL)

3. Switch to generated token, instead of Signed URLs (again, using Cache or DB)

4. And many other… add your own in the comments!

Now, let’s see improvement 1, 2 and 3.

1. Add nonce to URL

In “Route 1”, let’s add a parameter (hello in this example) containing a random string.

$passwordlessUrl = \URL::temporarySignedRoute(
    'passwordless.login',
    now()->addMinutes(10),
    ['user' => $user->id, 'hello' => \Str::random(64)]
);

2. One-time use of URL

In “Route 2”, let’s add full URL in Cache (just 10 minutes, equals to the Signed URL duration) and check if it is already in Cache, before login.

// routes/web.php

Route::get('/passwordless/login/{user}', function(Request $request, User $user) {
    // please, move me to a Controller ;)

    if (! $request->hasValidSignature()) {
        abort(401);
    }

    $onetimeCacheKey = "pwl.url.{$request->fullUrl()}";

    if (\Cache::has($onetimeCacheKey)) {
        abort(401);
    }

    \Auth::login($user);

    \Cache::put($onetimeCacheKey, 1, 10 * 60);

    return redirect('/');

})->name('passwordless.login');

3. Switch to generated token

In this case, we change the approach: we move to a generated token, instead of Signed URL.

And then, “Route 1":

Route::post('/passwordless/login', function(Request $request) {
    // please, move me to a Controller ;)

    $request->validate([
        'email' => 'required|email'
    ]);

    $user = User::query()
        ->where('email', $request->email)
        ->first();

    if ($user) {
        $token = \Str::random(64);

        \Cache::put("pwl.tkn.{$token}", $user->id, 10 * 60);

        $passwordlessUrl = route('passwordless.login', [
            'token' => $token
        ]);

        // notify user via email or other channel...
        $user->notify(new PasswordlessNotification($passwordlessUrl));
    }
    // else... we send always a success message to avoid any "info extraction"

    return back()->with('success', 'You have an email!');
});

Finally, “Route 2":

Route::get('/passwordless/login/{token}', function(Request $request, string $token) {
    // please, move me to a Controller ;)

    $tokenCacheKey = "pwl.tkn.{$token}";

    $userId = \Cache::get($tokenCacheKey);

    abort_if($userId == null, 401);

    $user = User::findOrFail($userId);

    \Auth::login($user);

    \Cache::forget($tokenCacheKey);

    return redirect('/');

})->name('passwordless.login');

✸ Enjoy your coding!

If you liked this post, don't forget to Subscribe to my newsletter!

data_get()

data_get() is a useful helper function in Laravel that retrieves values from a nested array or an object using dot notation. The strength of data_get() is also that it accepts wildcards.

If you don't know or you don't use it, I suggest you to discover it (here the docs), with brothers and sisters: data_set(), data_fill(), data_forget()! ;)

Arr::get()

Unlike data_get(), Arr::get() works only on arrays and it doesn't accept wildcards.

The Tip

Let’s show this example:

$array = [
    'key.sub' => 'a-value'
];

data_get($array, 'key.sub');  // --> null ❗

// instead...
\Arr::get($array, 'key.sub'); // --> "a-value"

Instead of this:

$array = [
    'key' => [
        'sub' => 'a-value'
    ]
];

data_get($array, 'key.sub');  // --> "a-value"

// and also...
\Arr::get($array, 'key.sub'); // --> "a-value"

And you?

• Did you use already data_get()?
• And Arr::get()?
• Did you know that difference?

Leave your comment!

✸ Enjoy your coding!

If you liked this post, don't forget to Subscribe to my newsletter!

class MyModel extends Model
{
    protected $fillable = [
        'name'
    ];

    protected static function booted(): void
    {
        static::created(function ($model) {
            $model->dumpEvent('CREATED');
        });

        static::updated(function ($model) {
            $model->dumpEvent('UPDATED');
        });

        static::saved(function ($model) {
            $model->dumpEvent('SAVED');
        });
    }

    public function dumpEvent(string $event): void
    {
        dump([
            'event' => $event,
            'wasChanged()' => $this->wasChanged(),
            'wasRecentlyCreated' => $this->wasRecentlyCreated
        ]);
    }
}

Let’s create a new model:

$model = MyModel::create(['name' => 'ABC']);

We get:

array:3 [ // app/Models/MyModel.php:30
  "event" => "CREATED"
  "wasChanged()" => false      // <-- ❗
  "wasRecentlyCreated" => true
]
array:3 [ // app/Models/MyModel.php:30
  "event" => "SAVED"
  "wasChanged()" => false      // <-- ❗
  "wasRecentlyCreated" => true
]

NOTE:

• ❗wasChanged() is false

If we call save() without changes on the same model instance:

// $model = MyModel::create(['name' => 'ABC']);
// ...
// ... no changes on `$model` fields

$model->save();

We get:

array:3 [ // app/Models/MyModel.php:30
  "event" => "SAVED"
  "wasChanged()" => false
  "wasRecentlyCreated" => true
]

NOTE:

• it will be triggered the saved() event
• but it will not be triggered the updated() event
• wasRecentlyCreated is still true (remember: it’s the same $model instance)

Now, let’s make some changes, always on the same model instance:

// $model = MyModel::create(['name' => 'ABC']);
// ...

$model->name = 'ABC new';
$model->save();

We get:

array:3 [ // app/Models/MyModel.php:30
  "event" => "UPDATED"
  "wasChanged()" => true
  "wasRecentlyCreated" => true // <-- ❗
]
array:3 [ // app/Models/MyModel.php:30
  "event" => "SAVED"
  "wasChanged()" => true
  "wasRecentlyCreated" => true // <-- ❗
]

NOTE:

• wasChanged() is true (OK, we expected it to be)
• ❗wasRecentlyCreated is still true (remember: it’s the same $model instance)

What happens after a refresh()?

// $model = MyModel::create(['name' => 'ABC']);
// ...

// $model->name = 'ABC new';
// $model->save();

$model->refresh();
$model->save();

We get again:

array:3 [ // app/Models/MyModel.php:30
  "event" => "SAVED"
  "wasChanged()" => true       // <-- ❗
  "wasRecentlyCreated" => true // <-- ❗
]

So even after a refresh(), it doesn’t change the internal status for the wasChanged() or wasRecentlyCreated!

Conclusion

In general, between different requests, reloading a model from the DB does not generate problems. But the behavior of wasChanged() and wasRecentlyCreated can become bizarre in the same request, i.e. on the same instance of the newly created model, especially if the model is configured to trigger events in the saved() method, when something has actually changed, for example:

protected static function booted(): void
{
    static::saved(function ($model) {
        if (! $model->wasChanged() && ! $model->wasRecentlyCreated) {
            return; // no changes and no new record
        }

        event(new MyCustomEvent(
            $model->wasRecentlyCreated ? 'mymodel.new' : 'mymodel.updated'),
            $model
        );
    });
}

✸ Enjoy your coding!

If you liked this post, don't forget to add your Subscribe to my newsletter!

"Hey Tony 🙏, I need to export those results to Excel by tomorrow morning otherwise I get fired! 🤯"

Has something like this ever happened to you?

Ok, keep calm and don't reinvent the wheel.

Fortunately, the Laravel ecosystem is wonderful and provides us with truly great tools. This is the case with the package we are going to rely on now:
👉 Laravel Excel (laravel-excel.com).

This package can be used to manage many aspects of both data export and import.

Here we will focus on data export, in a very common situation, that is, when the data source is a Model and therefore, presumably, the corresponding table in the DB.

Steps

1. Before we go, what is the Model?

2. Install the Laravel Excel package

3. Create the export class

4. Create the controller and open a route

1. Before we go, what is the Model?

Let's assume we have Orders, each of which is connected to a Customer.

The Order Model:

class Order extends Model
{
    protected $fillable = [
        'code',
        'status',
        'amount',
        'notes',
    ];

    public function customer(): BelongsTo
    {
        return $this->belongsTo(Customer::class);
    }
}

The Customer Model:

class Customer extends Model
{
    protected $fillable = [
        'business_name',
        'vat',
        'email',
    ];

    public function orders(): HasMany
    {
        return $this->hasMany(Order::class);
    }
}

2. Install the Laravel Excel package

Let's start!

Install the package:

composer require maatwebsite/excel:^3.1

Publish the config file config/excel.php:

php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config

You can find many default parameters in the configuration file that you can customize if necessary. But right now you can just move on.

3. Create the export class

Once the package has been installed, we have the make:export generator available.

We use it now:

php artisan make:export OrdersExport --model=Order

Ok, now let's open the newly created class:

// app/Exports/OrdersExport.php

namespace App\Exports;

use App\Models\Order;
use Maatwebsite\Excel\Concerns\FromCollection;

class OrdersExport implements FromCollection
{
    /**
    * @return \Illuminate\Support\Collection
    */
    public function collection()
    {
        return Order::all();
    }
}

This is a really basic version and we will almost certainly need to modify it.

First of all, let's remove the implementation of the FromCollection interface and replace it with the FromQuery interface. In this way, the query will be executed in chunks.

Furthermore, we add:

class OrdersExport implements FromQuery, WithHeadings, WithMapping, WithCustomCsvSettings
{
    use Exportable;

    // ...

    /**
     * Prepare the query for data export
     */
    public function query()
    {
        // ...
    }

    /**
     * Customize the csv header (first row)
     */
    public function headings(): array
    {
        // ...
    }

    /**
     * Get and (eventually) customize single row
     */
    public function map($order): array
    {
        // ...
    }

    /**
     * Customize CSV seettings
     */
    public function getCsvSettings(): array
    {
        // ...
    }
}

Finally, here is the complete version of the OrdersExport class, in which we also manage 2 very simple filters, on Customer and on the reference year:

// app/Exports/OrdersExport.php

namespace App\Exports;

use App\Models\Order;
use Maatwebsite\Excel\Concerns\Exportable;
use Maatwebsite\Excel\Concerns\FromQuery;
use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;
use Maatwebsite\Excel\Concerns\WithHeadings;
use Maatwebsite\Excel\Concerns\WithMapping;

class OrdersExport implements FromQuery, WithHeadings, WithMapping, WithCustomCsvSettings
{
    use Exportable;

    private ?Customer $customer;
    private ?int $year;

    /**
     * Filter orders by specific Customer
     */
    public function forCustomer(?Customer $customer): self
    {
        $this->customer = $customer;

        return $this;
    }

    /**
     * Filter orders by specific year
     */
    public function forYear(?int $year): self
    {
        $this->year = $year;

        return $this;
    }

    /**
     * Prepare the query for data export
     */
    public function query()
    {
        $q = Order::query()->with(['customer']);

        if ($this->customer != null) {
            $q->where('customer_id', $this->customer->id);
        }

        if (filled($this->year) && $this->year > 1970) {
            $q->whereYear('created_at', $this->year);
        }

        return $q->latest();
    }

    /**
     * Customize the csv header (first row)
     */
    public function headings(): array
    {
        return [
            'Order ID',
            'Order Code',
            'Order Status',
            'Order Amount',

            'Customer Business Name',
            'Customer VAT',
            'Customer Email',

            'Order Notes',
            'Created At',
            'Last Updated At',
        ];
    }

    /**
     * Get and (eventually) customize single row
     */
    public function map($order): array
    {
        return [
            $order->id,
            $order->code,
            $order->status,
            $order->amount,

            $order->customer?->business_name ?? '(Unknown)',
            $order->customer?->vat,
            $order->customer?->email,

            $order->notes ?? '(No notes)',
            $order->created_at,
            $order->updated_at,
        ];
    }

    /**
     * Customize CSV seettings
     */
    public function getCsvSettings(): array
    {
        return [
            'delimiter' => ',',
            'use_bom' => false,
            'output_encoding' => 'UTF-8',
        ];
    }
}

4. Create the controller and open a route

Now that the OrdersExport class is ready, we are almost done. All we have to do is use it in a controller and then open a specific route.

Here is an example controller:

// app/Http/Controllers/OrdersController.php

namespace App\Http\Controllers;

use App\Exports\OrdersExport;

class OrdersController extends Controller
{
    public function export(?Customer $customer = null, ?int $year = null)
    {
        $filename = $this->buildFilename('orders', $customer, $year);

        return (new OrdersExport)
            ->forCustomer($customer)
            ->forYear($year)
            ->download($filename);
    }

    protected function buildFilename($basename, ?Customer $customer = null, ?int $year = null)
    {
        $customerfmt = ($customer)
            ? \Str::slug($customer->business_name)
            : 'anycustomer';

        $yearfmt = filled($year) ? $year : 'anytime';
        $today = date('Ymd');

        return "{$basename}-{$customerfmt}-{$yearfmt}-{$today}.csv";
    }
}

And finally, the route:

// routes/web.php

Route::get('/orders/export/{customer?}/{year?}', [OrdersController::class, 'export'])
    ->name('orders.export');

✸ Enjoy your coding!

If you liked this post, don't forget to Subscribe to my newsletter!

In this tutorial, we will see how to make our Laravel application capable of requesting an access code before starting to use it.

First, the basics: What is a Private Beta?

A private (or closed) beta is an app accessible by invitation to a small group of testers. In contrast, a public (or open) beta is accessible to anyone interested.

Generally, the private beta is not ready to be used by everyone for various reasons: perhaps some features are still missing or there are potential scalability problems or the app simply needs to be shown to potential investors before the actual launch on the market.

Steps

1. Make the Model and Migration for Invitations

2. Add some Config parameters

3. Make a Service class

4. Make the Routes, the View and the Controller

5. Make the Middleware: This is where the work happens

6. Check that everything works!

1. Make the Model and Migration for Invitations

Let's create a Model named PrivateBetaInvitation and its migration:

php artisan make:model PrivateBetaInvitation --migration

In the migration, let's add the following fields to the table private_beta_invitations:

The migration:

// database/migrations/XXXX_create_private_beta_invitations_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('private_beta_invitations', function (Blueprint $table) {
            $table->id();

            $table->string('email')->index();
            $table->string('status', 16)->index()->default('pending')
                ->comment('pending|waiting|active|archived');
            $table->string('access_code', 32)->index()
                ->comment('the code that users (testers) will receive and must enter to access the app');
            $table->timestamp('expire_at')->nullable();
            $table->unsignedInteger('num_requests')->default(0);
            $table->timestamp('last_access_at')->nullable();

            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('private_beta_invitations');
    }
};

Migrate:

php artisan migrate

The Model PrivateBetaInvitation:

// app/Models/PrivateBetaInvitation.php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class PrivateBetaInvitation extends Model
{
    protected $fillable = [
        'email',
        'status',
        'access_code',
        'expire_at',
    ];

    protected $casts = [
        'expire_at' => 'datetime',
        'num_requests' => 'integer',
        'last_access_at' => 'datetime',
    ];
}

2. Add some Config parameters

Add variables in .env file:

PRIVATE_BETA_ENABLED=true

# whitelist IPs example: <my-home-ip>,<my-office-ip>
PRIVATE_BETA_WHITELIST_IPS=""

Then, refer to these variables in the config/app.php file:

// config/app.php

return [
    // ...

    'private-beta' => [
        /*
        | When `true`, the app can't be browsed without an access code!
        */
        'enabled' => env('PRIVATE_BETA_ENABLED', false),

        /*
        | Comma separated IP list for exclude the access code required when Private Beta is `enabled`.
        | You can put here YOUR IP.
        */
        'whitelist_ips' => env('PRIVATE_BETA_WHITELIST_IPS', ''),
    ],

];

💡 SMALL TIP: In case, remember to launch php artisan config:clear or php artisan config:cache

3. Make a Service class

Let's create a Service class PrivateBetaService where we put all the logic.

Since there is no "make:service" command in Laravel (yet?) we can simply create an empty file in the app/Services folder by running:

mkdir app/Services && touch app/Services/PrivateBetaService.php

Before implementation, here is an overview of the method interfaces of the Service class:

// app/Services/PrivateBetaService.php

namespace App\Services;

use App\Models\PrivateBetaInvitation;

class PrivateBetaService
{

    public function isEnabled(): bool
    {
        // ...
    }

    public function isIpWhitelisted(?string $ip): bool
    {
        // ...
    }

    public function checkAccessCode(string $accessCode): PrivateBetaInvitation
    {
        // ...
    }

    public function access(string $accessCode): PrivateBetaInvitation
    {
        // ...
    }

}

Finally, the full implementation of the Service class:

// app/Services/PrivateBeteService.php

namespace App\Services;

use App\Models\PrivateBetaInvitation;

class PrivateBetaService
{

    public function isEnabled(): bool
    {
        return config('app.private-beta.enabled', false);
    }

    public function isIpWhitelisted(?string $ip): bool
    {
        if (blank($ip)) {
            return false;
        }

        $whitelistIps = config('app.private-beta.whitelist_ips');
        if (blank($whitelistIps)) {
            return false;
        }

        return \Str::of($whitelistIps)
            ->split('/[\s,]+/')
            ->contains($ip);
    }

    public function checkAccessCode(string $accessCode): PrivateBetaInvitation
    {
        if (! $this->isEnabled()) {
            throw new \Exception(__('Private Beta is not enabled!'));
        }

        $invitation = PrivateBetaInvitation::query()
            ->where('access_code', $accessCode)
            ->latest()
            ->first();

        if (! $invitation) {
            throw new \Exception(__('The access code you sent is invalid'));
        }

        if ($invitation->status != 'active') {
            $msg = match($invitation->status) {
                'pending'  => __('Your access code is currenty pending.'),
                'waiting'  => __('Your access code is currenty waiting for the staff.'),
                'archived' => __('Your access code has expired.'),
                default    => __('The access code you sent is invalid!')
            };

            throw new \Exception($msg);
        }

        if ($invitation->expire_at && now()->gt($invitation->expire_at)) {
            throw new \Exception(__('Your access code has expired.'));
        }

        return $invitation;
    }

    public function access(string $accessCode): PrivateBetaInvitation
    {
        $invitation = $this->checkAccessCode($accessCode);

        $invitation->num_requests += 1;
        $invitation->last_access_at = now();
        $invitation->save();

        return $invitation;
    }

}

4. Make the Routes, the View and the Controller

The Routes

Let's add 2 routes:

1. GET /private-beta (named: private-beta.index)

2. POST /private-beta/access (named: private-beta.access)

// routes/web.php

use App\Http\Controllers\PrivateBetaController;

// ...
Route::get('/private-beta', [PrivateBetaController::class, 'index'])
    ->name('private-beta.index');

Route::post('/private-beta/access', [PrivateBetaController::class, 'access'])
    ->middleware('throttle:5,1')
    ->name('private-beta.access');

Note the 'throttle:5,1': you cannot attempt to access more than 5 times per minute.

The View

Make the View private-beta.index:

php artisan make:view private-beta.index

Then the content with a form pointing to the route named private-beta.access:

<!-- resources/views/private-beta/index.blade.php -->

<x-guest-layout>
    <x-auth-session-status class="mb-4" :status="session('status')" />

    <h1 class="text-center text-4xl font-extrabold leading-none tracking-tight text-gray-600 dark:text-white">
        @lang('Private Beta')
    </h1>

    <p class="mt-3 text-center text-gray-700 dark:text-white">
        @lang('This app is only open to users with an access code.')
    </p>

    <hr class="my-6">

    @if (! $isIpWhitelisted)
    <form method="POST" action="{{ route('private-beta.access') }}">
        @csrf

        <div>
            <x-input-label for="access_code" :value="__('Access Code') . ':'" class="sm:text-lg sm:text-blue-700" />
            <x-text-input id="access_code" class="block mt-1 w-full"
                type="text" name="access_code" :value="old('access_code', $currentAccessCode ?? null)"
                required autofocus />
            <x-input-error :messages="$errors->get('access_code')" class="mt-2" />
        </div>

        <div class="mt-4">
            <x-primary-button class="text-center w-full sm:block sm:text-lg">
                @lang('Enter Private Beta')
            </x-primary-button>
        </div>
    </form>
    @else
    <p class="text-center text-green-600 font-bold">
        @lang('Your IP is Whitelisted!')
    </p>
    @endif
</x-guest-layout>

Here, we will use Blade and assume that the Breeze Starter Kit is installed, but you can create the view however you like.

The Controller

Now, let's add the Controller PrivateBetaController with 2 methods:

1. index() renders the view

2. access() receives and validates the access code and, when it is correct, sends a cookie to the client for the next requests.

php artisan make:controller PrivateBetaController

The Controller:

// app/Http/Controllers/PrivateBetaController.php

namespace App\Http\Controllers;

use App\Services\PrivateBetaService;
use Illuminate\Http\Request;

class PrivateBetaController extends Controller
{

    public function __construct(
        protected PrivateBetaService $privateBetaService
    ) {}

    public function index(Request $request)
    {
        if (! $this->privateBetaService->isEnabled()) {
            return back();
        }

        $isIpWhitelisted = $this->privateBetaService->isIpWhitelisted($request->ip());
        $currentAccessCode = $request->cookie('private_beta_access_code');

        return view('private-beta.index', compact('isIpWhitelisted', 'currentAccessCode'));
    }

    public function access(Request $request)
    {
        if (! $this->privateBetaService->isEnabled()) {
            return back();
        }

        $request->validate([
            'access_code' => 'required',
        ]);

        try {
            $this->privateBetaService->checkAccessCode($request->access_code);
        } catch (\Exception $e) {
            return back()->withErrors(['access_code' => $e->getMessage()]);
        }

        $cookie = cookie('private_beta_access_code', $request->access_code);

        return redirect()
            ->intended() // <-- this is where the user originally wanted to go
            ->withCookie($cookie);
    }
}

5. Make the Middleware: This is where the work happens

Let's make the Middleware with the name PrivateBetaMiddleware:

php artisan make:middleware PrivateBetaMiddleware

The Service class implementation:

<?php

namespace App\Http\Middleware;

use App\Services\PrivateBetaService;
// use ...

class PrivateBetaMiddleware
{

    public function __construct(
        protected PrivateBetaService $privateBetaService
    ) {}

    public function handle(Request $request, Closure $next): Response
    {
        if (
            ! $this->isCheckPassed($request)
            && ! $request->route()?->named('private-beta.*')
        ) {
            return redirect()
                ->setIntendedUrl(url()->current()) 
                // ^ here is where the user will be redirect back
                ->route('private-beta.index');
        }

        return $next($request);
    }

    public function isCheckPassed(Request $request): bool
    {
        if (! $this->privateBetaService->isEnabled()) {
            return true;
        }

        if ($this->privateBetaService->isIpWhitelisted($request->ip())) {
            return true;
        }

        $cookieAccessCode = $request->cookie('private_beta_access_code');
        if (blank($cookieAccessCode)) {
            return false;
        }

        try {
            $this->privateBetaService->access($cookieAccessCode);
            return true;
        } catch (\Exception $e) {
            return false;
        }
    }
}

Now, we add the middleware to the 'web' group of App\Http\Kernel class. In this way, it will be applied to each web request.

// app/Http/Kernel.php

// ...
class Kernel extends HttpKernel
{
    // ...

    protected $middlewareGroups = [
        'web' => [
            // ...

            \App\Http\Middleware\PrivateBetaMiddleware::class,
        ],
    ];

    // ...
}

6. Check that everything works!

For simplicity, let's create a PrivateBetaInvitation Model record directly via Tinker.

IMPORTANT: status must be set to 'active'

Now, let's open the app in the browser. If everything is ok, you will be redirected to the /private-beta page.

In a first test, we enter the incorrect code "WRONGCODE" and verify that the error message is displayed as we expect:

Finally, it's time to put the correct code “JUSTATEST":

Boom! It works!

Let's open browser DevTools and check that the cookie is set as we expect:

Back to Tinker, fetch again the invitation record and check if num_requests and last_access_at are changed:

Great!

Next Steps

What is missing?

Obviously, to manage a private beta it is not enough to have an access point but, at a minimum, you need to be able to manage requests from new testers and send them access codes via email, in order to simplify access as much as possible.

All these operations can be automated. This makes sense to do when the numbers are not manageable manually. Perhaps we will address these aspects in a future specific tutorial.

✸ Enjoy your coding!

If you liked this post, don't forget to add your Subscribe to my newsletter!

The app that exposes the webhook is a client app. The client part is generally much simpler than the server part. In fact, the client basically has to worry about exposing an endpoint (i.e. the webhook) and managing incoming calls.

In reality, in a robust and efficient system, the client should respond immediately and without delay. For this purpose, it is necessary to queue the received notifications and subsequently manage them with a Job. By doing so, it is also possible to perform complex and/or time-consuming tasks, without blocking the caller unnecessarily.

Thankfully, to manage all of this we don't have to rewrite everything from scratch. We will use the package: 👉 Laravel Webhook Client

The package is developed and maintained by Spatie and we all know how much this is a guarantee!

Can I trust the caller?

One of the main issues to be addressed on the client side concerns the reliability of the caller, namely: is the application that contacts our webhook exactly the one authorized to do so or is there some funny guy pretending to be it?

The method that we will use in this tutorial is to verify that a signature is present among the headers of the requests received and that this has been affixed using a secret key. The package will do the checking for us. It will be enough for us to configure the correct Signature Secret Key.

By default, Laravel Webhook Client package uses the class DefaultSignatureValidator to validate signatures. This is how that class will compute the signature:

hash_hmac('sha256', $request->getContent(), $signatureSecretKey);

As you can see, the validation is very easy but, at the same time, very strong.

Steps

1. Install the Laravel Webhook Client package

2. Open the route and handle the job

3. Make some tests from server app

4. Prune WebhookCall models

1. Install the Laravel Webhook Client package

Install the package:

composer require spatie/laravel-webhook-client

Publish the config file config/webhook-client.php:

php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="webhook-client-config"

Publish the migration:

php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="webhook-client-migrations"

Migrate:

php artisan migrate

2. Open the route and handle the job

Add a route in routes/web.php.

// routes/web.php

Route::webhooks('/webhook');
// this will open a POST route `/webhook`

IMPORTANT: Of course, you can change /webhook with others, but the correct URL must be shared with the server app.

Now, if you run php artisan route:list you can check if there is the POST entry:

Because the app that sends webhooks to you has no way of getting a csrf-token, you must add that route to the except array of the VerifyCsrfToken middleware:

// app/Http/Middleware/VerifyCsrfToken.php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
    protected $except = [
        '/webhook', // <-- add this line
    ];
}

Now, it's time to set in the .env file the Signature Secret Key that your server application shared with you:

# .env
# ...

WEBHOOK_CLIENT_SECRET="paste-here-the-signature-secret-key-shared-with-server-app"

If you make a test request now, you get an Exception by the package informing you that there is no valid process webhook job class:

And that's what we're going to do now!

Make the job to handle calls:

php artisan make:job ProcessWebhookJob

For the purpose of the tutorial, we simply log the received data. We can find it in $this->webhookCall:

// app/Jobs/ProcessWebhookJob.php

namespace App\Jobs;

/* use ... */
use Spatie\WebhookClient\Jobs\ProcessWebhookJob as SpatieProcessWebhookJob;

class ProcessWebhookJob extends SpatieProcessWebhookJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function handle(): void
    {
        // `$this->webhookCall` contains an instance of:
        // `\Spatie\WebhookClient\Models\WebhookCall`

        $event = \Arr::get($this->webhookCall->payload, 'event');
        $data = \Arr::get($this->webhookCall->payload, 'data', []);

        // ...
        // [perform the work here] ...

        // simply log `event` and `data`:
        logger('ProcessWebhookJob', [
            'event' => $event,
            'data'  => $data,
        ]);

        // ...
    }
}

Finally, we set the process_webhook_job field to indicate the Job class we just created, in the config file at config/webhook-client.php:

// config/webhook-client.php
// ...
'process_webhook_job' => \App\Jobs\ProcessWebhookJob::class,

Now, if you re-launch the test request from earlier, you successfully get an invalid signature error:

3. Make some tests from server app

👉 From the server app we trigger a test event:

🎯 In the log of client app we have the correct data!

👉 Another event triggered from server app:

🎯 And in the client app log:

4. Prune WebhookCall models

With each call to our webhook, the package will add a record of the WebhookCall model. You can simply prune old records, by calling model:prune.

// app/Console/Kernel.php

namespace App\Console;

use Illuminate\Foundation\Console\Kernel as ConsoleKernel;
use Spatie\WebhookClient\Models\WebhookCall;

class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule)
    {
        $schedule->command('model:prune', [
            '--model' => [WebhookCall::class],
        ])->daily();

        // This will not work, as models in a package are not used by default
        // $schedule->command('model:prune')->daily();
    }
}

By default, records created more than 30 days ago will be removed.

You can customize this limit using the parameter delete_after_days in file config/webhook-client.php:

// config/webhook-client.php

return [
    'configs' => [
        // ...
    ],

    'delete_after_days' => 30,
];

✸ Enjoy your coding!

If you liked this post, don't forget to Subscribe to my newsletter!

In this tutorial, we will see how to make our Laravel application capable of sending notifications to external listening applications, using webhooks.

First, the basics: What is a Webhook?

Webhooks are HTTP callbacks that an external application (client) can subscribe to receive notifications from a main application (server).

Callbacks are therefore generally activated when an event occurs in the main application (server).

Why not just use API calls?

Our aim is to standardize outgoing calls. In other words, by exploiting the webhook mechanism, the server application does not need to adapt to the interface of each client, but it is the clients that must adapt and activate themselves based on the content of the standardized payload they will receive.

For example, think about Stripe: client applications sign up for new payment events. It is the clients that fit the Stripe specification and not the other way around.

The goal of the tutorial, in short

We will create a Laravel server app capable of storing client subscriptions in DB. Each client will have a different Signature Secret Key.

For simplicity, subscriptions will be handled with a console command.

To handle the calls, we will use a very nice package: 👉 Laravel Webhook Server

The package is developed and maintained by Spatie and we all know how much this is a guarantee!

Steps

1. Install the Laravel Webhook Server package

2. Make the model and migration for subscriptions

3. Create a console command to subscribe to webhooks

4. Add a general webhook event

5. Add the event listener that makes the calls

6. Example: how to dispatch the webhook event

1. Install the Laravel Webhook Server package

Install the package:

composer require spatie/laravel-webhook-server

Publish the config file in config/webhook-server.php:

php artisan vendor:publish --provider="Spatie\WebhookServer\WebhookServerServiceProvider"

Let's extend the timeout for the calls to:

// config/webhook-server.php

/*
 * If a call to a webhook takes longer that
 * this amount of seconds
 * the attempt will be considered failed.
 */
'timeout_in_seconds' => 10,

You can customize many parameters. To do that, you can follow the documentation of the package.

2. Make the model and migration for subscriptions

Make the model WebhookSubscription with --migration option:

php artisan make:model WebhookSubscription --migration

In the migration, let's add the following fields to the table webhook_subscriptions:

// database/migrations/XXXX_create_webhook_subscriptions_table

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('webhook_subscriptions', function (Blueprint $table) {
            $table->id();

            $table->string('url', 180)->unique()
                ->comment('the url of the webhook (external app)');

            $table->string('signature_secret_key', 128)
                ->comment('the secret key used to sign each call (to share with external app)');

            $table->boolean('is_active')
                ->index()
                ->default(1);

            $table->text('listen_events')
                ->default('*')
                ->comment('`*` for any event or comma separated values - for example: `order:new,order:updated`');

            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('webhook_subscriptions');
    }
};

php artisan migrate

💡 SMALL TIP For this tutorial, we just need to use a SQLite DB*, but of course you can use any other type of DB already used in your app.*

To use a SQLite DB:

# .env
# ...

DB_CONNECTION=sqlite
DB_HOST=
DB_PORT=
DB_DATABASE=tony_webhook.sqlite

The model:

// app/Models/WebhookSubscription.php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class WebhookSubscription extends Model
{
    use HasFactory;

    protected $fillable = [
        'url',
        'signature_secret_key',
        'is_active',
        'listen_events',
    ];

    protected $casts = [
        'is_active' => 'boolean',
    ];

    protected static function booted()
    {
        self::saving(function($model) {
            if (empty($model->signature_secret_key)) {
                $model->signature_secret_key = \Str::random(64);
            }
        });
    }

    protected function listenEvents(): Attribute
    {
        return Attribute::make(
            get: fn (?string $value) => is_string($value)
                ? array_map('trim', explode(',', $value))
                : [],
            set: fn (string|array|null $value) => is_array($value)
                ? implode(',', $value)
                : $value,
        );
    }

    public function isListenFor(string $event): bool
    {
        if ($this->isListenForAnyEvent()) {
            return true;
        }

        return in_array($event, $this->listen_events);
    }

    public function isListenForAnyEvent(): bool
    {
        return in_array('*', $this->listen_events);
    }

}

3. Create a console command to subscribe to webhooks

This is just a utility to add subscriptions via console, but you can add records via artisan tinker or build the UI for that.

php artisan make:command WebhookSubscribe

// app/Console/Commands/WebhookSubscribe.php

namespace App\Console\Commands;

use App\Models\WebhookSubscription;
use Illuminate\Console\Command;
use Illuminate\Contracts\Console\PromptsForMissingInput;

class WebhookSubscribe extends Command implements PromptsForMissingInput
{

    protected $signature = 'app:webhook-subscribe
        {url : The URL of the webhook (external app)}
        {events : The events that webhook may listen ("*" for any event or comma separated values - for example: "order:new,order:updated")}';

    protected $description = 'Add a subscribed external app to webhook';

    public function handle()
    {
        $url = trim($this->argument('url'));
        $events = trim($this->argument('events'));

        if (empty($url)) {
            $this->error('The URL is required!');
            return 1;
        }
        if (! \Str::of($url)->startsWith('https://')) {
            $this->error('The URL must start with `https://`!');
            return 1;
        }
        if (empty($events)) {
            $events = '*';
        }

        $alreadyExists = WebhookSubscription::where('url', $url)->exists();
        if ($alreadyExists) {
            $this->error("The URL [{$url}] is already subscribed!");
            return 1;
        }

        $WebhookSubscription = WebhookSubscription::create([
            'url' => $url,
            'listen_events' => $events,
            'is_active' => true,
        ]);

        $this->info('OK, Webhook Subscription created.');
        $this->newLine();
        $this->line('> The signature secret key is:');
        $this->line("> <bg=magenta;fg=black>{$WebhookSubscription->signature_secret_key}</>");
        $this->newLine();
        $this->warn('(You have to pass this key to external app for checking signature)');

        return 0;
    }
}

Now, we have a new command. If we call the artisan list, we get:

php artisan list

If we call the artisan help, we get:

php artisan help app:webhook-subscribe

Create some subscriptions

Now, let's create a subscription example:

php artisan app:webhook-subscribe https://tony-webhook-client-1.test/webhook "*"

(NOTE the signature secret key that you must copy and send or use in client app)

4. Add a general webhook event

Now, let's make a general event that we will use in our app to notify all webhook subscribers.

php artisan make:event WebhookEvent

// app/Events/WebhookEvent.php

namespace App\Events;

use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class WebhookEvent
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public string $name,
        public array $data,
    ) {}

}

5. Add the event listener that makes the calls

We have the WebhookEvent: now let's create the related listener:

php artisan MakeWebhookCalls --event=WebhookEvent

// app/Listeners/MakeWebhookCalls.php

namespace App\Listeners;

use App\Events\WebhookEvent;
use App\Models\WebhookSubscription;
use Spatie\WebhookServer\WebhookCall;

class MakeWebhookCalls
{

    public function handle(WebhookEvent $event): void
    {
        $subscriptions = WebhookSubscription::query()
            ->where('is_active', true)
            ->oldest()
            ->get();

        foreach ($subscriptions as $subscription) {
            if (! $subscription->isListenFor($event->name)) {
                continue;
            }

            WebhookCall::create()
                ->url($subscription->url)
                ->payload([
                    'event' => $event->name,
                    'data' => $event->data
                ])
                ->useSecret($subscription->signature_secret_key)
                ->dispatch();
        }
    }
}

Don't forget to bind the event and the listener in the EventServiceProvider class:

// app/Providers/EventServiceProvider.php

namespace App\Providers;

use App\Events\WebhookEvent;
use App\Listeners\MakeWebhookCalls;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        // ...

        WebhookEvent::class => [
            MakeWebhookCalls::class,
        ],
    ];

6. Example: how to dispatch the webhook event

Example 1: Customer new/updated

An example CustomerController with 2 event dispatches (customer:new and customer:updated):

// app/Http/Controllers/CustomerController.php

namespace App\Http\Controllers;

use App\Events\WebhookEvent;
use Illuminate\Http\Request;

class CustomerController extends Controller
{
    // ...

    public function store(Request $request)
    {
        // customer store logic...

        event(new WebhookEvent('customer:new', [
            // any payload data
        ]));
    }

    public function update(Request $request)
    {
        // customer update logic...

        event(new WebhookEvent('customer:updated', [
            // any payload data
        ]));
    }
}

Example 2: Order new/updated

Another example OrderController with 2 event dispatches (order:new and order:updated):

// app/Http/Controllers/CustomerController.php

namespace App\Http\Controllers;

use App\Events\WebhookEvent;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    // ...

    public function store(Request $request)
    {
        // order store logic...

        event(new WebhookEvent('order:new', [
            // any payload data
        ]));
    }

    public function update(Request $request)
    {
        // order update logic...

        event(new WebhookEvent('order:updated', [
            // any payload data
        ]));
    }
}

✸ Enjoy your coding!

If you liked this post, don't forget to Subscribe to my newsletter!

But here we are talking about an agile method that we can use in a project where, for example, we do not intend to use users or use Laravel Sanctum.

First, the basics: What is an API Key?

An API Key is a key or token to be used for authenticating one or more server-to-server calls.

In other words, it is a secret key and therefore must never be exposed in the frontend code (such as that of a SPA).

Steps

1. Create a key

2. Create a middleware that checks the API Key

3. Create an example route and controller

4. Test with Postman

5. Create a test class

1. Create a key

Add a variable in the .env file:

# .env
# ...

APP_FAST_API_KEY=paste_here_a_generated_api_key

The key must be in the .env file, because we don't want to keep it in repository.

💡 SMALL TIP to generate a key on the fly: Launch php artisan tinker and then simply \Str::random(64)

Then, add an array key that refer the variable in the .env file:

// config/app.php

return [
    // ...

    'fast_api_key' => env('APP_FAST_API_KEY'),

];

💡 SMALL TIP: In case, remember to launch php artisan cache:config

2. Create a middleware that checks the API Key

php artisan make:middleware VerifyFastApiKey

// app/Http/Middleware/VerifyFastApiKey.php

class VerifyFastApiKey
{
    public function handle(Request $request, Closure $next): Response
    {
        $apiKey = config('app.fast_api_key');

        $apiKeyIsValid = (
            filled($apiKey)
            && $request->header('x-api-key') === $apiKey
        );

        abort_if (! $apiKeyIsValid, 403, 'Access denied');

        return $next($request);
    }
}

Create an alias for this middleware:

// app/Http/Kernel.php

class Kernel extends HttpKernel
{
    // ...

    protected $middlewareAliases = [
        // ...

        'with_fast_api_key' => \App\Http\Middleware\VerifyFastApiKey::class,
    ];

}

3. Create an example route and controller

Add some routes in routes/api.php with the newly created with_fast_api_key middleware:

// routes/api.php

Route::group([
    'prefix' => 'v1',
    'middleware' => 'with_fast_api_key'
], function () {

    Route::post('/just/an/example', [SomethingController::class, 'justAnExample']);

    // ...
});

Create an example controller:

php artisan make:controller SomethingController

// app/Http/Controllers/SomethingController.php

class SomethingController extends Controller
{
    public function justAnExample()
    {
        return [
            'msg' => 'It works!'
        ];
    }
}

4. Test with Postman

First, call the endpoint /just/an/example without an API Key set in Headers, and check if it fails as expected:

Finally, call the endpoint /just/an/example with the correct API Key set in the Header X-API-Key, and check if it works as expected:

5. Create a test class

Make test class:

php artisan make:test FastApiKeyTest

Add some test methods:

// tests/Feature/FastApiKeyTest.php

class FastApiKeyTest extends TestCase
{
    public function test_fail_without_api_key(): void
    {
        $response = $this->postJson('/api/v1/just/an/example');

        $response->assertStatus(403);
    }

    public function test_fail_with_wrong_api_key(): void
    {
        $response = $this->postJson('/api/v1/just/an/example', [], [
            'X-API-Key' => 'a-wrong-key'
        ]);

        $response->assertStatus(403);
    }

    public function test_success_with_corrent_api_key(): void
    {
        $response = $this->postJson('/api/v1/just/an/example', [], [
            'X-API-Key' => config('app.fast_api_key')
        ]);

        $response->assertStatus(200);
    }
}

Finally, launch the tests:

php artisan test

✸ Enjoy your coding!

If you liked this post, don't forget to add your Subscribe to my newsletter!