Download the PHP package migears/image without Composer

migears/image

A minimalist image processing toolkit based on PHP 8.1+ and the GD extension.

Background: miGears is the open-source successor of TinyGears, a self-developed PHP framework. It was renamed and open-sourced recently because the name TinyGears is already taken in the open-source community.

Features

• Zero required dependencies — GD extension is a suggested dependency, implementations can be replaced as needed
• Minimalist API — Chainable calls, intuitive and easy to use
• Type-safe — Full type declarations, readonly value objects, enums
• Lightweight — Core class within a few hundred lines, readable in one sitting
• High test coverage — Uses GD to generate test images, covering all core functionality

Boundaries

In scope

• GDImage (implements ImageInterface), a GD-backed layer doing resize (resize, resizeToWidth, resizeToHeight, resizeToMax), crop (crop, cropCenter, thumbnail), rotate/flip (rotate, flipHorizontal, flipVertical, flipBoth) and watermarks (imageWatermark, textWatermark, opacity 0-100).
• Reading from a file path or an existing \GdImage, detecting the type from the file content, and writing out with save() / output() in JPEG, PNG, GIF and WEBP (quality 0-100).
• The ImageType enum and the readonly ImageInfo value object; failures throw MiGears\Image\Exception\ImageException, except a write failure in save(), which is reported by its false return value.

Not in scope (by design)

• Sending the HTTP response — no output, no headers, no Response object; output() returns a binary string and save() writes a file, so emitting Content-Type and the body belongs to the caller or the framework.
• Generating captcha images — that is migears/captcha (random code, math mode, difficulty levels, noise and interference lines).
• Storing, caching or serving images, and handling uploads — no session/DB/filesystem storage and no $_FILES processing; caching belongs to migears/cache.
• Any dependency beyond PHP itself — ext-gd is only suggested, and no PSR interfaces are used.

Requirements

• PHP 8.1+
• ext-gd (suggested)

Installation

Quick Start

Rotate & Flip

Output Directly to Browser

Practical: User Upload Thumbnail Generator

API Overview

Construction

Information

Resizing

Cropping

Rotation & Flipping

Watermarks

Saving & Output

Other

Core Classes

ImageInfo (readonly value object)

ImageType Enum

Exceptions

All failures throw MiGears\Image\Exception\ImageException, including out-of-range parameters ($quality and $opacity must be between 0 and 100) and a declared type that contradicts the detected one. The one exception is save(): when the file cannot be written it returns false instead of throwing, so callers must check the return value.

Testing

License

MIT

migears/image

极简图像处理工具包，基于 PHP 8.1+ 和 GD 扩展。

特性

• 零强制依赖 — GD 扩展为建议依赖，可按需替换实现
• 极简 API — 链式调用，直观易用
• 类型安全 — 全量类型声明、readonly 值对象、枚举
• 轻量级 — 核心类控制在几百行以内，可一口气读完
• 高测试覆盖 — 使用 GD 生成测试图片，覆盖所有核心功能

边界

范围内

• GDImage（实现 ImageInterface）这一 GD 支撑层：缩放（resize、resizeToWidth、resizeToHeight、resizeToMax）、裁剪（crop、cropCenter、thumbnail）、旋转/翻转（rotate、flipHorizontal、flipVertical、flipBoth）与水印（imageWatermark、textWatermark，透明度 0-100）。
• 从文件路径或已有 \GdImage 读取，按文件内容检测类型，并用 save() / output() 写出 JPEG、PNG、GIF、WEBP（质量 0-100）。
• ImageType 枚举与 readonly 值对象 ImageInfo；失败均抛出 MiGears\Image\Exception\ImageException，唯 save() 的写入失败以其 false 返回值报告。

范围外（刻意不做）

• 发送 HTTP 响应 —— 不做输出、不发送响应头、不提供 Response 对象；output() 返回二进制字符串、save() 只写文件，因此设置 Content-Type 与响应体属于调用方或框架。
• 生成验证码图片 —— 那属于 migears/captcha（随机码、算术模式、难度等级、噪点与干扰线）。
• 存储、缓存或对外提供图片，以及处理上传 —— 不做 session/数据库/文件系统存储，也不处理 $_FILES；缓存属于 migears/cache。
• PHP 之外的任何依赖 —— ext-gd 仅为建议依赖，也不引入 PSR 接口。

要求

• PHP 8.1+
• ext-gd（建议）

安装

快速开始

旋转 & 翻转

直接输出到浏览器

实战：用户上传缩略图生成器

API 概览

构造

信息

缩放

裁剪

旋转 & 翻转

水印

保存 & 输出

其他

核心类

ImageInfo（readonly 值对象）

ImageType 枚举

异常

所有失败均抛出 MiGears\Image\Exception\ImageException，包括参数越界（$quality 与 $opacity 必须在 0-100 之间）以及声明类型与检测类型不一致。唯一例外是 save()：文件无法写入时它返回 false 而不抛异常，调用方必须检查返回值。

测试

License

MIT