spatie/laravel-url-signer

Laravel implementation of spatie/signed-url

Create signed URLs with a limited lifetime in Laravel

, _(*1)

This package can create URLs with a limited lifetime. This is done by adding an expiration date and a signature to the URL., _(*2)

The difference with Laravel's native route signing is that using this package:, _(*3)

• you can easily use signed URLs between different apps
• the signing secret used is not tied to the app key
• you can easily sign any URL (and not only a route belonging to your app)

This is how you can create signed URL that's valid for 30 days:, _(*4)

use Spatie\UrlSigner\Laravel\Facades\UrlSigner;

UrlSigner::sign('https://myapp.com/protected-route', now()->addDays(30));

The output will look like this:, _(*5)

https://app.com/protected-route?expires=xxxxxx&signature=xxxxxx

The URL can be validated with the validate-function., _(*6)

// returns `true` if the signed URL is valid, `false` if not
UrlSigner::validate('https://app.com/protected-route?expires=xxxxxx&signature=xxxxxx');

The package also provides a middleware to protect routes., _(*7)

Support us

, _(*8)

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products., _(*9)

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall., _(*10)

Installation

As you would have guessed the package can be installed via composer:, _(*11)

composer require spatie/laravel-url-signer

You must set an environment variable called URL_SIGNER_SIGNATURE_KEY and set it to a long secret value. This value will be used to sign and validate signed URLs., _(*12)

php artisan generate:url-signer-signature-key
        {--s|show : Display the key instead of modifying files.}
        {--always-no : Skip generating key if it already exists.}
        {--f|force : Skip confirmation when overwriting an existing key.}

The configuration file can optionally be published via:, _(*13)

php artisan vendor:publish --tag="url-signer-config"

This is the content of the file:, _(*14)

return [
    /*
    * This string is used the to generate a signature. You should
    * keep this value secret.
    */
    'signature_key' => env('URL_SIGNER_SIGNATURE_KEY'),

    /*
     * The default expiration time of a URL in seconds.
     */
    'default_expiration_time_in_seconds' => 60 * 60 * 24,

    /*
     * These strings are used a parameter names in a signed url.
     */
    'parameters' => [
        'expires' => 'expires',
        'signature' => 'signature',
    ],
];

Usage

URL's can be signed with the sign-method:, _(*15)

use Spatie\UrlSigner\Laravel\Facades\UrlSigner;

UrlSigner::sign('https://myapp.com/protected-route');

By default, the lifetime of an URL is one day. This value can be change in the config file. If you want a custom lifetime, you can specify the number of days the URL should be valid:, _(*16)

use Spatie\UrlSigner\Laravel\Facades\UrlSigner;

// the generated URL will be valid for 5 minutes.
UrlSigner::sign('https://myapp.com/protected-route', now()->addMinutes(5));

// alternatively you could also pass the amount of seconds
UrlSigner::sign('https://myapp.com/protected-route', 60 * 5);

Validating URLs

To validate a signed URL, simply call the validate()-method. This method returns a boolean., _(*17)

use Spatie\UrlSigner\Laravel\Facades\UrlSigner;

UrlSigner::validate('https://app.com/protected-route?expires=xxxxxx&signature=xxxxxx');

Protecting routes with middleware

The package provides a middleware to protect routes., _(*18)

To use it you must first register the Spatie\UrlSigner\Laravel\Middleware\ValidateSignature as route middleware in your HTTP kernel., _(*19)

// in app/Http/Kernel.php

protected $routeMiddleware = [
    // ...
    'signed-url' => \Spatie\UrlSigner\Laravel\Middleware\ValidateSignature::class,
];

Next, you can apply it on any route you want., _(*20)

Route::get('protected-route', fn () => 'Hello secret world!')
    ->middleware('signed-url');

Your app will abort with a 403 status code if the route is called without a valid signature., _(*21)

Changelog

Please see CHANGELOG for more information what has changed recently., _(*22)

Testing

You can run the test using this command:, _(*23)

composer test

Usage outside Laravel

If you're working on a non-Laravel project, you can use the framework agnostic version., _(*24)

Contributing

Please see CONTRIBUTING for details., _(*25)

Security

If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker., _(*26)

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using., _(*27)

Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium., _(*28)

We publish all received postcards on our company website., _(*29)

Credits

• Freek Van der Herten
• Sebastian De Deyne
• All Contributors

License

The MIT License (MIT). Please see License File for more information., _(*30)