Skip to content

Commit d5a5a17

Browse files
ace-of-acesace-of-aces
authored
Merge pull request #6 from ace-of-aces/feat/new-docs
[Feature]: New Documentation 💅🏻
2 parents 74985af + 4b71d9c commit d5a5a17

18 files changed

+2133
-1
lines changed

‎.github/workflows/deploy.yml

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Deploy Docs to GH Pages
2+
3+
on:
4+
# Runs on pushes targeting the `main` branch. Change this to `master` if you're
5+
# using the `master` branch as the default branch.
6+
push:
7+
branches: [main]
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
# Build job
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
33+
- uses: pnpm/action-setup@v3
34+
with:
35+
version: 9 # Not needed if you've set "packageManager" in package.json
36+
- name: Setup Node
37+
uses: actions/setup-node@v4
38+
with:
39+
node-version: 22
40+
cache: pnpm
41+
- name: Setup Pages
42+
uses: actions/configure-pages@v4
43+
- name: Install dependencies
44+
run: pnpm ci # or pnpm install / yarn install / bun install
45+
- name: Build with VitePress
46+
run: pnpm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
47+
- name: Upload artifact
48+
uses: actions/upload-pages-artifact@v3
49+
with:
50+
path: docs/.vitepress/dist
51+
52+
# Deployment job
53+
deploy:
54+
environment:
55+
name: github-pages
56+
url: ${{ steps.deployment.outputs.page_url }}
57+
needs: build
58+
runs-on: ubuntu-latest
59+
name: Deploy
60+
steps:
61+
- name: Deploy to GitHub Pages
62+
id: deployment
63+
uses: actions/deploy-pages@v4

‎.gitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,5 +27,4 @@ _ide_helper_models.php
2727
# Misc
2828
phpunit.xml
2929
phpstan.neon
30-
/docs
3130
/coverage

‎docs/.gitignore

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
*.log
2+
*.tgz
3+
.DS_Store
4+
.idea
5+
.temp
6+
.vite_opt_cache
7+
.vscode
8+
dist
9+
cache
10+
temp
11+
node_modules

‎docs/.vitepress/config.mts

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import { defineConfig } from 'vitepress'
2+
import pkg from '../package.json'
3+
4+
// https://vitepress.dev/reference/site-config
5+
export default defineConfig({
6+
title: "Laravel Image Transform URL",
7+
description: "Easy, URL-based image transformations for Laravel inspired by Cloudflare Images.",
8+
srcDir: './pages',
9+
markdown: {
10+
theme: {
11+
light: 'github-light',
12+
dark: 'github-dark'
13+
}
14+
},
15+
themeConfig: {
16+
// https://vitepress.dev/reference/default-theme-config
17+
nav: [
18+
{ text: 'Home', link: '/' },
19+
{
20+
text: pkg.version,
21+
items: [
22+
{
23+
text: 'Changelog',
24+
link: 'https://github.com/ace-of-aces/laravel-image-transform-url/blob/main/CHANGELOG.md'
25+
},
26+
{
27+
text: 'Contributing',
28+
link: 'https://github.com/ace-of-aces/laravel-image-transform-url/blob/main/CONTRIBUTING.md'
29+
}
30+
]
31+
}
32+
],
33+
34+
sidebar: [
35+
{
36+
text: 'Basics',
37+
items: [
38+
{ text: 'Installation', link: '/installation' },
39+
{ text: 'Setup', link: '/setup' },
40+
{ text: 'Getting Started', link: '/getting-started' },
41+
]
42+
},
43+
{
44+
text: 'Options',
45+
items: [
46+
{ text: 'Configuring Options', link: '/configuring-options' },
47+
{ text: 'Available Options', link: '/available-options' },
48+
]
49+
},
50+
{
51+
text: 'Advanced',
52+
items: [
53+
{ text: 'Image Caching', link: '/image-caching' },
54+
{ text: 'Rate Limiting', link: '/rate-limiting' },
55+
{ text: 'CDN Usage', link: '/cdn-usage' },
56+
{ text: 'Error Handling', link: '/error-handling' },
57+
]
58+
}
59+
],
60+
61+
socialLinks: [
62+
{ icon: 'github', link: 'https://github.com/ace-of-aces/laravel-image-transform-url' },
63+
],
64+
65+
footer: {
66+
message: 'Released under the MIT License.',
67+
copyright: 'Copyright © 2025-present Julian Schramm'
68+
},
69+
70+
search: {
71+
provider: 'local',
72+
}
73+
}
74+
})

‎docs/.vitepress/theme/custom.css

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/* .vitepress/theme/custom.css */
2+
:root {
3+
--vp-c-brand-1: #000000;
4+
--vp-c-brand-2: #3d3b3b;
5+
--vp-c-brand-3: #8b8585;
6+
--vp-c-brand-soft: rgba(114, 109, 109, 0.14);
7+
}
8+
9+
.dark {
10+
--vp-c-brand-1: #ffffff;
11+
--vp-c-brand-2: #cbc4c4;
12+
--vp-c-brand-3: #8a8585;
13+
--vp-c-brand-soft: rgba(115, 110, 110, 0.14);
14+
}

‎docs/.vitepress/theme/index.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import './custom.css'
3+
4+
export default DefaultTheme

‎docs/package.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "v0.5.0",
3+
"devDependencies": {
4+
"vitepress": "^1.6.3"
5+
},
6+
"scripts": {
7+
"docs:dev": "vitepress dev",
8+
"docs:build": "vitepress build",
9+
"docs:preview": "vitepress preview"
10+
}
11+
}

‎docs/pages/available-options.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Available Options
2+
3+
These are the options that can be used to transform images with this package.
4+
5+
## `background`
6+
7+
`string`
8+
9+
Set the background color of the image.
10+
Any valid HEX color value (without a leading `#`).
11+
12+
Example:
13+
14+
```
15+
background=ff0000
16+
```
17+
18+
> [!IMPORTANT]
19+
> Only supported for the `png` format.
20+
21+
## `blur`
22+
23+
`integer`
24+
25+
Set the blur level of the image.
26+
Possible values: `0` to `100`.
27+
28+
Example:
29+
30+
```
31+
blur=50
32+
```
33+
34+
> [!CAUTION]
35+
> 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 and test beforehand, or disable it in the config.
36+
37+
## `contrast`
38+
39+
`integer`
40+
41+
Set the contrast level of the image.
42+
Possible values: `-100` to `100`.
43+
44+
Example:
45+
46+
```
47+
contrast=50
48+
```
49+
50+
## `flip`
51+
52+
`string`
53+
54+
Flip the image.
55+
Possible values: `h` (horizontal), `v` (vertical), `hv` (horizontal and vertical).
56+
57+
Example:
58+
59+
```
60+
flip=h
61+
```
62+
63+
## `format`
64+
65+
`string`
66+
67+
Set the format of the image.
68+
Supported formats: `jpg`, `jpeg`, `png`, `gif`, `webp`.
69+
70+
Example:
71+
72+
```
73+
format=webp
74+
```
75+
76+
## `height`
77+
78+
`integer`
79+
80+
Set the height of the image.
81+
Values greater than the original height will be ignored.
82+
83+
Example:
84+
85+
```
86+
height=250
87+
```
88+
89+
## `quality`
90+
91+
`integer`
92+
93+
Set the quality of the image.
94+
Possible values: `0` to `100`.
95+
96+
Example:
97+
98+
```
99+
quality=80
100+
```
101+
102+
## `version`
103+
104+
`integer`
105+
106+
Version number of the image.
107+
Any positive integer. More info in the [Image Caching](/image-caching) section.
108+
109+
Example:
110+
111+
```
112+
version=2
113+
```
114+
115+
## `width`
116+
117+
`integer`
118+
119+
Set the width of the image.
120+
Values greater than the original width will be ignored.
121+
122+
Example:
123+
124+
```
125+
width=250
126+
```

‎docs/pages/cdn-usage.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Usage with CDNs
2+
3+
The package is designed to work seamlessly with CDNs like Cloudflare, BunnyCDN, and others.
4+
5+
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.
6+
7+
```php
8+
/*
9+
|--------------------------------------------------------------------------
10+
| Response Headers
11+
|--------------------------------------------------------------------------
12+
|
13+
| Below you may configure the response headers which are added to the
14+
| response. This is especially useful for controlling caching behavior
15+
| of CDNs.
16+
|
17+
*/
18+
19+
'headers' => [
20+
'Cache-Control' => env('IMAGE_TRANSFORM_HEADER_CACHE_CONTROL', 'immutable, public, max-age=2592000, s-maxage=2592000'),
21+
// more headers can be added here
22+
],
23+
```

‎docs/pages/configuring-options.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Configuring Options
2+
3+
This package supports a variety of options, but you may not need or want to use all of them. You can configure which options are enabled in the `image-transform-url.php` configuration file.
4+
5+
```php
6+
/*
7+
|--------------------------------------------------------------------------
8+
| Enabled Options
9+
|--------------------------------------------------------------------------
10+
|
11+
| Here you may configure the options which are enabled for the image
12+
| transformer.
13+
|
14+
*/
15+
16+
'enabled_options' => env('IMAGE_TRANSFORM_ENABLED_OPTIONS', [
17+
'width',
18+
'height',
19+
'format',
20+
'quality',
21+
// 'flip',
22+
// 'contrast',
23+
// 'version',
24+
// 'background',
25+
// 'blur'
26+
]),
27+
```

‎docs/pages/error-handling.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Error Handling
2+
3+
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.
4+
5+
This is why the route handler will return a plain `404` response if:
6+
7+
- a requested image does not exist at the specified path
8+
- the requested image is not a valid image file
9+
- the provided options are not in the correct format (`key=value`, no trailing comma, etc.)
10+
11+
The only other HTTP error that can be returned is a `429` response, which indicates that the request was rate-limited.
12+
13+
If parts of the given route options are invalid, the route handler will ignore them and only apply the valid options.
14+
15+
Example:
16+
17+
```ansi
18+
http://localhost:8000/image-transform/width=250,quality=foo,format=webp/example.jpg
19+
```
20+
21+
will be processed as:
22+
23+
```ansi
24+
http://localhost:8000/image-transform/width=250,format=webp/example.jpg
25+
```

0 commit comments

Comments
 (0)