How EzyPlatform Reduces Image File Size
Updated at 1783089190000EzyPlatform reduces image size inside the media pipeline. This means an image can be optimized during upload, file replacement, saving from an external URL, or when a user explicitly requests size reduction for an existing media item.
The goal is not to compress every file type, but to reduce storage size for common image media, especially avatars and content images. The default strategy is practical: if an image exceeds the configured threshold, the system rewrites it with lower quality, then gradually reduces pixel dimensions until it finds the best smaller version.
Overall Architecture
The reduction step runs after the physical file is written and before final media metadata is saved. As a result, metadata such as file name, MIME type, and file size can be updated to match the optimized file.
flowchart TD
A[User uploads or replaces an image] --> B[Validate file and media type]
B --> C[Write file to media storage]
C --> D{Is size reduction enabled?}
D -- No --> E[Save metadata using original file]
D -- Yes --> F{External processor available?}
F -- Yes --> G[Delegate to media up/downloader]
F -- No --> H{Custom event handler available?}
H -- Yes --> I[Use handler result]
H -- No --> J[Reduce size with default image service]
G --> K[Update file name, MIME type, and size if changed]
I --> K
J --> K
K --> L[Save metadata and emit media event]
This design keeps the core system simple while allowing plugins or external modules to replace the reduction algorithm, for example with a CDN, object storage service, or dedicated image optimizer.
When Image Reduction Runs
Image size reduction can run in these main cases:
- Uploading new media.
- Replacing the file of an existing media item.
- Saving media from an external URL.
- Calling an API to reduce an existing media item by ID or name.
- Running the action from the admin UI, either for one image or multiple images.
Before running, the system checks whether media file size reduction is enabled. If the feature is disabled, the pipeline skips optimization and keeps the original file.
Size Threshold
EzyPlatform uses a target size threshold to decide whether an image should be reduced.
If the request provides
expectedFileSize, that value is used for the current operation. Otherwise, the system uses the platform configuration. In the current implementation, the default threshold is 1MB.
flowchart TD
A[Receive image file] --> B{File exists and is valid?}
B -- No --> X[Do not reduce]
B -- Yes --> C[Read original file size]
C --> D{expectedFileSize provided?}
D -- Yes --> E[Use expectedFileSize]
D -- No --> F[Use configured threshold]
E --> G{Original size <= threshold?}
F --> G
G -- Yes --> X
G -- No --> H[Start optimization]
If the file is already smaller than or equal to the threshold, no further processing is done.
Reduction Algorithm
The default algorithm works along two dimensions:
- Lowering image compression quality.
- Reducing image pixel dimensions.
For JPEG/JPG images, the system starts with the original dimensions, writes the image at about
85% quality, then lowers quality step by step. If the result is still above the threshold, it resizes the image smaller and repeats the quality loop.
flowchart TD
A[Image needs reduction] --> B[Scale = 100%]
B --> C[Resize using current scale]
C --> D[Quality = 85%]
D --> E[Write candidate file]
E --> F{Candidate smaller than best file?}
F -- Yes --> G[Save as best file]
F -- No --> H[Ignore candidate]
G --> I{Best file <= threshold?}
H --> I
I -- Yes --> Z[Use best file]
I -- No --> J{Can quality be reduced further?}
J -- Yes --> K[Lower quality]
K --> E
J -- No --> L[Reduce scale to 85%]
L --> M{Scale still large enough?}
M -- Yes --> C
M -- No --> Z
The system always tracks the “best file”, meaning the smallest valid candidate found so far. If it cannot reach the exact target size, but still produces a file smaller than the original, it can use that best result.
Supported Image Formats
The default mechanism supports formats that can be read and written through ImageIO and are accepted by the algorithm:
-
jpg -
jpeg -
png
For JPEG/JPG, the image is rewritten in the same format with adjusted compression quality.
For PNG, the system converts the image to JPEG when reduction succeeds. This is important: the optimization is lossy, not lossless PNG compression. The new file uses the
.jpg extension, and the MIME type is updated to image/jpeg.Because JPEG does not support transparency, transparent PNG areas are rendered over a white background. This is a common trade-off for stronger size reduction, but it should be considered for logos, icons, or images that require alpha transparency.
Preserving the Original File
EzyPlatform has an option to keep the original-size file. When enabled, the system creates a copy of the original file using the
original_ prefix before optimization.After successful reduction, the media metadata records this original file name. This gives the system a fallback path for restoring, comparing quality, or serving use cases that require the original image.
If reduction fails or no smaller version is produced, temporary files are cleaned up.
Metadata Updates
After successful optimization, EzyPlatform updates the media record according to the actual stored file:
- New file name, if the format changed, for example PNG to JPG.
- New MIME type, if changed.
- New file size.
- Original file name, if the original was preserved.
- Previous slug or alias, when needed to keep references working.
This keeps API responses aligned with the real file on disk.
Extension Points
Before using the default algorithm, EzyPlatform supports two extension layers:
- A custom media up/downloader: if an external adapter supports file size reduction, the system delegates to it.
- An event handler: a plugin or module can handle the reduction event and return its own result.
Only when neither extension handles the operation does the system fall back to the default image service.
Limitations
The default mechanism only applies to image-like media types, specifically content images and avatars. Videos, documents, and other file types are not reduced by the default image service.
Formats such as GIF, WebP, AVIF, and SVG are not optimized by the default flow. Supporting them should be done through a custom image processor or extension.
PNG-to-JPEG conversion can significantly reduce file size, but it may remove transparency and change image characteristics. For transparent logos, icons, or technical graphics, a custom processor or different configuration may be more appropriate.
Conclusion
EzyPlatform’s image size reduction mechanism is designed to balance automation and extensibility. By default, it reduces large images by trying multiple quality and size levels, selecting the best result, updating metadata, and optionally preserving the original file.
Its main strength is that it sits directly inside the media pipeline, so users do not need to manually optimize images before uploading. At the same time, adapter and event-based extension points make it flexible enough for projects that need CDN integration, object storage, or specialized image optimization services.