Skip to content

Commit b763569

Browse files
ace-of-acesace-of-aces
committed
chore: link new documentation website, remove old README docs
1 parent c0e0ea5 commit b763569

File tree

1 file changed

+2
-136
lines changed

1 file changed

+2
-136
lines changed

‎README.md

Lines changed: 2 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -14,143 +14,9 @@ Easy, URL-based image transformations inspired by [Cloudflare Images](https://de
1414
- ⚡ Automatic caching of transformed images for faster loading times
1515
- 🌍 Easy integration with CDNs for even faster global delivery
1616

17-
## Requirements
17+
## Documentation
1818

19-
- PHP \>= 8.4
20-
- Laravel 12.x
21-
- [GD PHP Library](https://www.php.net/manual/en/book.image.php)
22-
23-
If you want to use the file caching feature (highly recommended), a configured `Storage` disk and a `Cache` driver is required. More info in the [Image Caching](#image-caching) section.
24-
25-
### Important `php.ini` settings❗
26-
1. The underlying image processing library (GD) can use alot more RAM than regular web requests. It's highly recommended to set your memory limit to *at least* 256MB.
27-
```
28-
memory_limit=512M
29-
```
30-
2. If you have the [Swoole extension](https://laravel.com/docs/octane#swoole) installed, make sure you have the following setting to [avoid conflicts](https://github.com/ace-of-aces/laravel-image-transform-url/issues/4) with Laravel's `defer` helper which this package uses.
31-
```
32-
swoole.use_shortname=off
33-
```
34-
35-
## Installation
36-
37-
Install the package via composer:
38-
39-
```bash
40-
composer require ace-of-aces/laravel-image-transform-url
41-
```
42-
43-
Publish the config file with:
44-
45-
```bash
46-
php artisan vendor:publish --tag="image-transform-url-config"
47-
```
48-
49-
## Getting Started
50-
51-
1. Configure the package via `image-transform-url.php` to set your `source_directories`, from where you want to transform the images. By default, the package will look for `images` directories in your `public` folder and in the `storage/app/public` directory.
52-
It is recommended to use a dedicated subdirectory for your images in order to avoid conflicts with other files.
53-
54-
2. Choose a default source directory by setting the `default_source_directory` option in the `image-transform-url.php` configuration file. This will be used if no source directory is specified in the URL.
55-
56-
3. Test your first image transformation:
57-
58-
Use the following URL format to transform your images:
59-
60-
```
61-
http://<domain>/<route-prefix>/<source-directory>/<options>/<path-to-your-image.<jpg|jpeg|png|gif|webp>>
62-
```
63-
64-
>[!NOTE]
65-
> You can omit the `<source-directory>` part if you have set a default source directory in the configuration file.
66-
67-
for example:
68-
69-
```
70-
http://localhost:8000/image-transform/width=250,quality=80,format=webp/foo/bar/example.jpg
71-
```
72-
73-
## Options
74-
75-
> [!NOTE]
76-
> The options are separated by commas and their values are appended with equal signs. The order of options does not matter.
77-
78-
| Option | Description | Type | Description / Possible Values |
79-
| ------------ | ------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
80-
| `width` | Set the width of the image. | integer | Values greater than the original width will be ignored. |
81-
| `height` | Set the height of the image. | integer | Values greater than the original height will be ignored. |
82-
| `quality` | Set the quality of the image. | integer | `0` to `100` |
83-
| `format` | Set the format of the image. | string | Supported formats: `jpg`, `jpeg`, `png`, `gif`, `webp`. |
84-
| `blur` | Set the blur level of the image. | integer | `0` to `100` |
85-
| `contrast` | Set the contrast level of the image. | integer | `-100` to `100` |
86-
| `background` | Set the background color of the image | string | Any valid HEX color value (without a leading `#`). Only supported for the `png` format. |
87-
| `flip` | Flip the image. | string | `h`(horizontal), `v`(vertical), `hv`(horizontal and vertical) |
88-
| `version` | Version number of the image. | integer | Any positive integer. More info in the [Image Caching](#image-caching) section. |
89-
90-
> [!CAUTION]
91-
> The `blur` option is a resource-intensive operation and may cause memory issues if the image is too large. It is recommended to use this option with caution, or disable it in the config.
92-
93-
## Image Caching
94-
95-
This package comes with the default option to automatically store and serve images statically for the requested options within the caching lifetime.
96-
97-
> [!NOTE]
98-
> Having this feature enabled (default behavior) will help to reduce the load on your server and speed up image delivery.
99-
100-
The processed images are stored in the `storage/app/private/_cache/image-transform-url` directory by default. You can change the disk configuration in the `image-transform-url.php` configuration file.
101-
102-
> [!CAUTION]
103-
> When using this option, there is one caveat to be aware of:
104-
105-
Source images are considered to be stale content by their file name and path.
106-
107-
If the content of an original source image changes, but the file name stays the same, the cached images will not be updated automatically until the cache expires.
108-
To force a revalidation, you can either:
109-
110-
1. change the image's file name
111-
2. move it into another subdirectory, which will change its path
112-
3. change the version number (integer) in the options (e.g. `version=2`)
113-
4. or flush the entire cache of your application using the `php artisan cache:clear` command.
114-
115-
## Rate Limiting
116-
117-
Another feature of this package is the ability to limit the number of transformations that the image transformation route should process per path and IP address within a given time frame.
118-
119-
The rate limit will come into effect for new transformation requests only, and will not affect previously cached images.
120-
121-
By default, rate limiting is disabled for the `local` and `testing` app environements to not distract you when developing your app. You can configure the rate limit settings in the `image-transform-url.php` configuration file.
122-
123-
## Usage with CDNs
124-
125-
The package is designed to work seamlessly with CDNs like Cloudflare, BunnyCDN, and others.
126-
127-
The most important configuration is the [`Cache-Control`](https://developer.mozilla.org/de/docs/Web/HTTP/Reference/Headers/Cache-Control) header, which you can customize to your liking in the `image-transform-url.php` configuration file.
128-
129-
## Error Handling
130-
131-
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.
132-
133-
This is why the route handler will return a `404` response if:
134-
135-
- a requested image does not exist at the specified path
136-
- the requested image is not a valid image file
137-
- the provided options are not in the correct format (`key=value`, no trailing comma, etc.)
138-
139-
The only other HTTP error that can be returned is a `429` response, which indicates that the request was rate-limited.
140-
141-
If parts of the given route options are invalid, the route handler will ignore them and only apply the valid options.
142-
143-
Example:
144-
145-
```
146-
http://localhost:8000/image-transform/width=250,quality=foo,format=webp/example.jpg
147-
```
148-
149-
will be processed as:
150-
151-
```
152-
http://localhost:8000/image-transform/width=250,format=webp/example.jpg
153-
```
19+
Check out the [official documentation website](https://image-transform-url.julian.center).
15420

15521
## Roadmap
15622

0 commit comments

Comments
 (0)