spiral-packages / signed-urls
Create and validate signed URLs in Spiral Framework
Requires
- php: ^8.1
- psr/http-message: ^1.0
- spiral/boot: ^3.0
- spiral/http: ^3.0
- spiral/router: ^3.0
Requires (Dev)
- spiral/framework: ^3.0
- spiral/testing: ^2.0
- vimeo/psalm: ^4.9
This package is auto-updated.
Last update: 2024-10-14 14:02:17 UTC
README
The package allows you to easily create "signed" URLs to named routes. These URLs have a "signature" hash appended to the query string which allows Spiral Framework to verify that the URL has not been modified since it was created.
Signed URLs are especially useful for routes that are publicly accessible yet need a layer of protection against URL manipulation.
Requirements
Make sure that your server is configured with following PHP version and extensions:
- PHP 8.1+
- Spiral framework 3.0+
Installation
You can install the package via composer:
composer require spiral-packages/signed-urls
After package install you need to register bootloader from the package.
protected const LOAD = [ // ... \Spiral\SignedUrls\Bootloader\SignedUrlsBootloader::class, ];
Note if you are using
spiral-packages/discoverer
, you don't need to register bootloader by yourself.
Specify env variables
# Secret key for generating the HMAC variant of the message digest. # REQUIRED SIGNED_URLS_KEY=secret # Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) # OPTIONAL (sha256 by default) SIGNED_URLS_ALGO=sha256
Usage
For example, you might use signed URLs to implement a public "email verification" link that is emailed to your customers:
class VerifyEmailNotification { public function __construct( private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls private readonly \Spiral\Views\ViewInterface $view ) {} public function buildView(): string { return $this->view->render([ 'signed_url' => $this->urls->signedRoute( route: 'verify-email', parameters: ['user_id' => 100] ) ]); } }
If you would like to generate a temporary signed route URL that expires after a specified amount of time, you may pass expiration date in method. When Spiral Framework validates a temporary signed route URL, it will ensure that the expiration timestamp that is encoded into the signed URL has not expired:
class VerifyEmailNotification { public function __construct( private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls private readonly \Spiral\Views\ViewInterface $view ) {} public function buildView(): string { return $this->view->render([ 'signed_url' => $this->urls->signedRoute( route: 'verify-email', parameters: ['user_id' => 100], expiration: new \DateTime('...') ) ]); } }
You may sign not only routes but also Urls:
class VerifyEmailNotification { public function __construct( private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls private readonly \Spiral\Views\ViewInterface $view ) {} public function buildView(): string { return $this->view->render([ 'signed_url' => $this->urls->signedUrl( uri: new \Nyholm\Psr7\Uri('http://site.com/verify-email/?user_id=1'), expiration: new \DateTime('...') ) ]); } }
Validating Signed Urls
To verify that a URL has a valid signature, you should call the hasValidSignature method:
class EmailVerificationController { public function __construct( private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls ) {} public function verify(\Psr\Http\Message\RequestInterface $request): string { if (!$this->urls->hasValidSignature($request->getUri())) { return 'ERROR'; } return 'OK'; } }
Instead of validating signed URLs using the incoming request instance, you may assign the
Spiral\SignedUrls\Middleware\ValidateSignature
middleware to the route:
class EmailVerificationController { public function __construct( private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls ) {} #[\Spiral\Router\Annotation\Route( name: 'verify-email', route: '...', middleware: \Spiral\SignedUrls\Middleware\ValidateSignature::class )] public function verify(\Psr\Http\Message\RequestInterface $request): string { return 'OK'; } }
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.