docs: document signed URLs, update error handling

Author: ace-of-aces

docs/.vitepress/config.mts

@@ -51,6 +51,7 @@ export default defineConfig({
             {
                 text: 'Advanced',
                 items: [
+                    { text: 'Signed URLs', link: '/signed-urls' },
                     { text: 'Image Caching', link: '/image-caching' },
                     { text: 'Rate Limiting', link: '/rate-limiting' },
                     { text: 'CDN Usage', link: '/cdn-usage' },

docs/pages/error-handling.md

@@ -2,13 +2,19 @@
 
 The route handler of this package is designed to be robust against invalid options, paths and file names, while also not exposing additional information of your applications public directory structure.
 
+## HTTP Status Codes
+
 This is why the route handler will return a plain `404` response if:
 
 -   a requested image does not exist at the specified path
 -   the requested image is not a valid image file
 -   the provided options are not in the correct format (`key=value`, no trailing comma, etc.)
 
-The only other HTTP error that can be returned is a `429` response, which indicates that the request was rate-limited.
+The only two other HTTP errors that can be returned are:
+- a `429` response, which indicates that the request was rate-limited
+- a `403` response, which indicates that the request was unauthorized (e.g. when using signed URLs and the signature is invalid or expired)
+
+## Invalid options
 
 If parts of the given route options are invalid, the route handler will ignore them and only apply the valid options.
 

docs/pages/signed-urls.md

@@ -0,0 +1,82 @@
+# Signed URLs
+
+This package provides the option to generate signed URLs for images from specific source directories powered by [Laravel's URL signing feature](https://laravel.com/docs/urls#signed-urls).
+
+This can be useful for securing access to images that should not be publicly accessible without proper authorization or only in a scaled down version.
+
+::: info
+Signed URLs also ensure that the provided options cannot be modified client-side.
+:::
+
+::: warning
+The Signed URL feature does not restrict access to public images.
+If you want to secure access to images, ensure that the source directories you want signed URLs for are not publicly accessible.
+:::
+
+## Setup
+
+To enable signed URLs, set the `signed_urls.enabled` option to `true` in your `image-transform-url.php` configuration.
+
+You then need to specify the source directories for which signed URLs should apply to in the `signed_urls.source_directories` array.
+
+For example:
+
+```php
+'source_directories' => [
+    'images' => public_path('images'),
+    'protected' => storage_path('app/private/protected-images'),
+],
+
+// ...
+
+'signed_urls' => [
+    'enabled' => env('IMAGE_TRANSFORM_SIGNED_URLS_ENABLED', false),
+    'for_source_directories' => env('IMAGE_TRANSFORM_SIGNED_URLS_FOR_SOURCE_DIRECTORIES', [
+        'protected-images',
+    ]),
+],
+```
+
+## Generating Signed URLs
+
+To generate a signed URL for an image, you can use the `ImageTransformUrl` facade:
+
+```php
+use AceOfAces\LaravelImageTransformUrl\Facades\ImageTransformUrl;
+
+$options = [
+    'blur' => 50,
+    'width' 500,
+];
+
+$blurredImage = ImageTransformUrl::signedUrl(
+    'example.jpg',
+    $options,
+    'protected'
+);
+```
+
+## Temporary Signed URLs
+
+If you would like to to generate a signed URL that expires after a certain time, you can use the `temporarySignedUrl` method:
+
+```php
+use AceOfAces\LaravelImageTransformUrl\Facades\ImageTransformUrl;
+
+$options = [
+    'blur' => 50,
+    'width' 500,
+];
+
+$temporarySignedUrl = ImageTransformUrl::temporarySignedUrl(
+    'example.jpg',
+    $options,
+    now()->addMinutes(60),
+    'protected'
+);
+```
+
+::: info
+You can also use the generic `signedUrl` method to generate temporary signed URLs.
+This method accepts an `$expiration` parameter, which defaults to `null`. If you provide a value, it will generate a temporary signed URL.
+:::