feat: add S3 usage guide and update setup documentation for remote sources

Author: ace-of-aces

docs/.vitepress/config.mts

@@ -54,6 +54,7 @@ export default defineConfig({
                     { text: 'Signed URLs', link: '/signed-urls' },
                     { text: 'Image Caching', link: '/image-caching' },
                     { text: 'Rate Limiting', link: '/rate-limiting' },
+                    { text: 'S3 Usage', link: '/s3-usage' },
                     { text: 'CDN Usage', link: '/cdn-usage' },
                     { text: 'Error Handling', link: '/error-handling' },
                 ]

docs/pages/s3-usage.md

@@ -0,0 +1,24 @@
+# Usage with S3
+
+This guide explains how to configure this package to work with S3-compatible storage services like AWS S3 or Cloudflare R2.
+This enables you to transform and serve images stored remotely without the need to store images on your local server.
+
+1. Set up your S3 disk in your [filesystems configuration](https://laravel.com/docs/filesystem#amazon-s3-compatible-filesystems), install the [S3 package](https://laravel.com/docs/filesystem#s3-driver-configuration) and ensure you have the necessary credentials and settings for your S3 bucket. Public bucket access is not required.
+
+2. Configure the package via `image-transform-url.php` to include your S3 disk in the `source_directories` as described in [the setup guide](/setup#configuring-remote-sources).
+
+3. If you are using the [Image Caching](/image-caching) feature and want to store transformed images back to your S3 bucket instead of your local filesystem, you may also set the `cache.disk` option in the `image-transform-url.php` configuration file to your S3 disk.
+
+```php
+'cache' => [
+    //...
+    'disk' => env('IMAGE_TRANSFORM_CACHE_DISK', 's3'),
+    //...
+],
+```
+
+::: warning
+Having the `cache.disk` set to your S3 disk may result in higher latency and costs due to the nature of remote storage. If you are concerned about performance, consider using a local disk for caching and only use S3 for the source directories.
+:::
+
+4. You can now use the [image transformation URLs](/getting-started) as usual, and the package will handle fetching images from your S3 bucket.

docs/pages/setup.md

@@ -22,6 +22,9 @@ An example source directory configuration might look like this:
 | Important: The public storage directory should be addressed directly via
 | storage('app/public') instead of the public_path('storage') link.
 |
+| You can also use any Laravel Filesystem disk (e.g. S3) by providing an
+| array configuration with 'disk' and an optional 'prefix'.
+|
 */
 'source_directories' => [
     'images' => public_path('images'),
@@ -40,3 +43,18 @@ An example source directory configuration might look like this:
 'default_source_directory' => env('IMAGE_TRANSFORM_DEFAULT_SOURCE_DIRECTORY', 'images'),
 // ...
 ```
+
+## Configuring Remote Sources
+If you want to use a remote source (like AWS S3 or Cloudflare R2) as a source directory, you can configure any [Laravel Filesystem disk](https://laravel.com/docs/filesystem#configuration) in your `config/filesystems.php` file and then reference it in the `source_directories` configuration.
+
+```php
+'source_directories' => [
+    // Other source directories...
+    'remote' => [
+        'disk' => 's3', // Any valid Laravel Filesystem disk
+        'prefix' => 'images', // Optional, if you want to specify a subdirectory
+    ],
+],
+```
+
+Read the [full guide on how to use this package with S3](/s3-usage.md).