README

许可

本项目按照 MIT 许可证授权。

要求 (要求)

• PHP >= 8.1
• phpunit/phpunit: ~9.0
• illuminate/support: ~9
• orchestra/testbench: ~7

支持的图像库 (支持的图像库)

• Imagick PHP 扩展 (>= 3.7.0)

描述

image 项目是一个现代且强大的 Laravel 图像处理库。它集成了各种组件和接口，提供了灵活的架构以高效处理图像。与 Imagick 库的交互允许进行各种图像操作。该项目为 Laravel 开发者提供了强大的工具来管理图像，并允许在项目中创建定制的图像处理解决方案。

安装

使用 Composer 安装库

composer require platinajewelry/image

# Конфигурация
return [
    // Базовая директория для сохранения файлов.
    'base_path' => 'app/public',
    // Качество сохранения изображения по умолчанию.
    'default_quality' => 90,
    // Следует ли применять Str::slug к имени файла.
    'use_slug' => true,
    // Оставит только буквы, цифры, символы тире и нижнее подчеркивание.
    'filename_filter' => '/[^a-zA-ZА-я\d\-_]/u', // Если пусто, то не применяется
];

功能

• make() - 创建图像对象。
• save() - 保存图像。
• destroy() - 清理资源，并销毁图像对象。
• resize() - 改变图像大小，保持比例。
• crop() - 根据指定尺寸裁剪图像。
• encode() - 将图像编码为特定格式。
• orientate() - 改变图像方向。
• rotate() - 将图像旋转到指定角度。
• mirror() - 将图像水平或垂直镜像。
• blur() - 将模糊效果应用于图像。
• brightness() - 调节图像亮度。
• contrast() - 调整图像的对比度。
• grayscale() - 将图像转换为黑白（灰度）。
• sharpen() - 应用锐化效果到图像。
• textOverlay() - 在图像上添加文字覆盖。
• watermark() - 在图像上添加水印。
• backup() - 创建图像的备份。
• reset() - 从备份恢复图像。
• response() - 根据图像创建HTTP响应。
• stream() - 以流的形式输出图像。
• 创建用户自定义命令 - 创建自己的命令并按自己的意愿处理图像。

make() - 创建图像对象。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Создает объект изображения.
 *
 * @param mixed $data Данные для создания изображения (локальный файл, UploadedFile, URL-адрес).
 * 
 * @return Image Возвращает объект изображения.
 */
@method make(mixed $data): Image

// Создание объекта изображения на основе локального файла.
$img = PLImage::make('C:/file.jpg');
// Создание объекта изображения на основе данных, полученных по URL-адресу.
$img = PLImage::make('https://file.jpg');
// Создание объекта изображения на основе данных, предоставленных UploadedFile.
$img = PLImage::make($request->file('file'));

/**
* Свойства объекта изображения
 */
// **MIME-тип изображения**
    - Геттер: $img->getMime()
    - Сеттер: $img->setMime($newMime)

// **Директория, в которой находится изображение**
    - Геттер: $img->getDirname()
    - Сеттер: $img->setDirname($newDirname)

// **Имя файла изображения**
    - Геттер: $img->getFilename()
    - Сеттер: $img->setFilename($newFilename)

// **Имя файла без расширения**
    - Геттер: $img->getBasename()
    - Сеттер: $img->setBasename($newBasename)

// **Расширение файла**
    - Геттер: $img->getExtension()
    - Сеттер: $img->setExtension($newExtension)

// **Путь**
    - Геттер: $img->getSavePath()
    - Сеттер: $img->setSavePath($newSavePath)

save() - 保存图像。

use Smetaniny\LaravelImage\Facades\PLImage;

/**
 * Выполняет сохранение изображения по указанному пути и с заданным качеством.
 *
 * @param string $path Путь для сохранения изображения
 * @param int|null $quality Качество сохранения изображения
 * 
 * @return Image Возвращает объект изображения.
 */
@method save(string $path = "", int $quality = null): Image

// Создание объекта изображения на основе данных, предоставленных UploadedFile.
$img = PLImage::make($request->file('file'));
// Сохранить изображение по указанному пути test/file.jpg с качеством 90.
$img->save('test/file.jpg', 90);
// Сохранить изображение по указанному пути test/file.jpg с максимальным качеством (по умолчанию 100).
$img->save('test/file.jpg');
// Сохранить изображение в соответствии с настройками конфигурации.
$img->save();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->save('file.jpg');

destroy() - 清理资源并销毁图像对象。

/**
 * Очищает ресурсы, и уничтожает объект изображения.
 *
 * После вызова этого метода объект изображения больше не может быть использован для манипуляций.
 * Требуется создание нового объекта изображения для проведения дополнительных операций.
 */
@method destroy(): void

resize() - 保持比例改变图像大小。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Изменяет размер изображения сохраняя пропорции.
 *
 * @param int|null $width Новая ширина изображения.
 * @param int|null $height Новая высота изображения.
 * 
 * @return Image Возвращает объект изображения.
 */
@method resize(?int $width, ?int $height): Image

// Создание объекта изображения на основе данных, предоставленных UploadedFile.
$img = PLImage::make($request->file('file'));
// Изменение размера изображения на ширину 500 и высоту 400 пикселей.
$img->resize(500, 400);
// Изменение размера изображения по ширине на 400 пикселей, сохраняя пропорции.
$img->resize(null, 400);
// Изменение размера изображения по высоте на 500 пикселей, сохраняя пропорции.
$img->resize(500, null);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath()
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->resize(500, null)
    ->save()
    ->destroy();

crop() - 按指定尺寸裁剪图像。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Обрезает изображение по заданным размерам.
 *
 * @param int $width Ширина обрезанного изображения.
 * @param int $height Высота обрезанного изображения.
 * @param int|null $x X-координата верхнего левого угла обрезки.
 * @param int|null $y Y-координата верхнего левого угла обрезки.
 * 
 * @return Image Возвращает объект изображения.
 */
@method crop(int $width, int $height, ?int $x = null, ?int $y = null): Image

// Создание объекта изображения на основе данных, предоставленных UploadedFile.
$img = PLImage::make($request->file('file'));
// Вызываем метод обрезки с указанными параметрами.
$img->crop(500, 500, 25, 50);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath()
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->crop(500, 500, 25, 50)
    ->save()
    ->destroy();

encode() - 将图像编码为特定格式。

use Smetaniny\LaravelImage\Facades\PLImage;
use Imagick;

/**
 * Кодирует изображение в определенный формат.
 *
 * @param string $format Формат, в который нужно закодировать изображение.
 * 
 * @return Image Возвращает объект изображения.
 */
@method encode(string $format): Image

// Получаем список форматов с которыми можем работать.
$imagickFormats = Imagick::queryFormats();

$img = PLImage::make($request->file('file'));
// Сохраняем оригинальный размер.
$img->save();

// Или более краткий вариант
PLImage::make($request->file('file'))->save();

// Кодирование в формат JPEG.
$img->encode('JPEG');
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();

// Кодирование в формат PNG.
$img->encode('PNG');
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();

// Кодирование в формат WebP.
$img->encode('WebP');
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();

// Кодирование в формат SVG.
$img->encode('SVG');
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

orientate() - 改变图像方向。

use Smetaniny\LaravelImage\Facades\PLImage;

/**
 * Изменяет ориентацию изображения. Автоматически повернет изображение.
 * 
 * @return Image Возвращает объект изображения.
 */
@method orientate(): Image Изменяет ориентацию изображения.
Автоматически повернет изображение так, чтобы оно было правильно отображено.

// Создаем объект изображения.
$img = PLImage::make($img);
// Изменяет ориентацию изображения
$img->orientate();
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->orientate()
    ->save()
    ->getSavePath()
    ->destroy();

rotate() - 将图像旋转特定角度。

use Smetaniny\LaravelImage\Facades\PLImage;

/**
 * Поворачивает изображение на заданный угол.
 *
 * @param int $angle Угол поворота в градусах.
 * 
 * @return Image Возвращает объект изображения.
 */
@method rotate(int $angle): Image

// Создаем объект изображения.
$img = PLImage::make($img);
// Поворачиваем изображение.
$img->rotate(45);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->rotate(45)
    ->save()
    ->getSavePath()
    ->destroy();

mirror() - 水平或垂直镜像图像。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Зеркально отражает изображение по горизонтали или вертикали.
 *
 * @param string $mode Режим отражения: 'h' для горизонтального, 'v' для вертикального.
 * 
 * @return Image Возвращает объект изображения.
 */
@method mirror(string $mode = 'h'): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Зеркально отражаем изображение.
$img->mirror();
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->mirror()
    ->save()
    ->getSavePath()
    ->destroy();

blur() - 对图像应用模糊效果。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Применяет размытие к изображению.
 *
 * @param float $radius Радиус размытия (чем больше, тем сильнее размытие).
 * @param float $sigma Стандартное отклонение для гауссова размытия.
 */
@method blur(float $radius = 5, float $sigma = 1): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Размываем изображение.
$img->blur();
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->blur()
    ->save()
    ->getSavePath()
    ->destroy();

brightness() - 调整图像亮度。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Регулирует яркость изображения.
 *
 * @param float $brightness Уровень яркости (0 - оригинал, > 0 - увеличить, < 0 - уменьшить).
 */
@method brightness(float $brightness): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Регулируем яркость
$img->brightness(-25);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->brightness(-25)
    ->save()
    ->getSavePath()
    ->destroy();

contrast() - 调整图像对比度。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Регулирует контраст изображения.
 *
 * @param float $contrast Уровень контраста (0 - оригинал, > 0 - увеличить, < 0 - уменьшить).
 * 
 * @return Image Возвращает объект изображения.
 */
@method contrast(float $contrast): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Регулируем контраст
$img->contrast(25);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->contrast(25)
    ->save()
    ->getSavePath()
    ->destroy();

grayscale() - 将图像转换为黑白（灰度）。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Преобразует изображение в черно-белый (оттенки серого).
 * 
 * @return Image Возвращает объект изображения.
 */
@method grayscale(float $contrast): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Регулируем контраст
$img->grayscale();
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->grayscale()
    ->save()
    ->getSavePath()
    ->destroy();

sharpen() - 应用锐化效果到图像。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Применяет эффект заточки к изображению.
 *
 * @param float $amount Уровень заточки (чем больше, тем сильнее резкость).
 * @param float $radius Радиус заточки.
 * @param float $sigma Стандартное отклонение для гауссова заточки.
 * 
 * @return Image Возвращает объект изображения.
 */
@method sharpen(float $amount = 2, float $radius = 1, float $sigma = 0.5): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Регулируем контраст
$img->sharpen(50, 25, 20.5);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make(
    $request->file('file'))
    ->sharpen(50, 25, 20.5)
    ->save()
    ->getSavePath()
    ->destroy();

textoverlay() - 在图像上添加文字覆盖。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Добавляет текстовое наложение на изображение.
 *
 * @param string $text Текст для наложения.
 * @param int $x Положение по оси X.
 * @param int $y Положение по оси Y.
 * @param string $font Путь к файлу шрифта.
 * @param int $fontSize Размер шрифта.
 * @param string $color Цвет текста в формате "#RRGGBB".
 * 
 * @return Image Возвращает объект изображения.
 */
@method textOverlay(
    string $text, 
    int $x, 
    int $y,
    string $font, 
    int $fontSize, 
    string $color = '#000000'
): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
$text = 'Пример текста';
$text2 = 'Пример текста 2';
// Путь до шрифта
$font = public_path('/ArialRegular.ttf');
// Устанавливаем текст
$img->textOverlay($text, 300, 300, $font, 44, '#FF0000');
// Устанавливаем текст 2
$img->textOverlay($text2, 300, 350, $font, 44, '#FF0000');
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->textOverlay($text, 300, 300, $font, 44, '#FF0000')
    ->textOverlay($text2, 300, 350, $font, 44, '#FF0000')
    ->save()
    ->getSavePath()
    ->destroy();

watermark() - 在图像上添加水印。

use Smetaniny\LaravelImage\Facades\PLImage;

/**
 * Добавляет водяной знак на изображение.
 *
 * @param string $watermarkPath Путь к файлу изображения водяного знака.
 * @param int $x Положение по оси X.
 * @param int $y Положение по оси Y.
 * @param int $opacity Прозрачность водяного знака (от 0 до 100).
 * 
 * @return Image Возвращает объект изображения.
 */
@method watermark(string $watermarkPath, int $x, int $y, int $opacity = 50): Image
    
// Создаем объект изображения.
$img = PLImage::make($img);
// Путь к файлу водяного знака
$watermarkPath = public_path('/watermark.png');
// Добавление водяного знака
$img->watermark($watermarkPath, 50, 100, 90);
// Сохраняем.
$img->save();
// Получаем путь.
$img->getSavePath();
// Очищаем.
$img->destroy();

// Или более краткий вариант
PLImage::make($request->file('file'))
    ->watermark($watermarkPath, 50, 100, 90)
    ->save()
    ->getSavePath()
    ->destroy();

backup() - 创建图像备份。

 /**
 * Создает резервную копию изображения.
 */
@method backup(): void

reset() - 从备份恢复图像。

/**
 * Восстанавливает изображение из резервной копии.
 */
@method reset(): void

backup() 和 reset() 命令示例

use Smetaniny\LaravelImage\Facades\PLImage;

$img = PLImage::make($request->file('file'));
// Создаем резервную копию.
$img->backup();
// Теперь проводим какие-то изменения.
$img->resize(300, null);
// Меняем имя файла.
$img->setFilename("thumb_300");
// Сохраняем
$img->save();
// Получаем путь
$img->getSavePath()
// Восстанавливаем изображение из резервной копии.
$img->reset();
// Меняем имя файла.
$img->setFilename("all");
// Сохраняем оригинальный размер.
$img->save();
// Получаем путь.
$img->getSavePath()
// Очищаем.
$img->destroy();

response() - 根据图像创建HTTP响应。

use Smetaniny\LaravelImage\Facades\PLImage;

/**
 * Создает HTTP-ответ на основе изображения. Полезно, когда нужно вернуть изображение как ответ на запрос.
 *
 * @param array $headers Заголовки ответа.
 * 
 * @return Response HTTP-ответ.
 */
@method response(array $headers= []): Response

// Создаем объект изображения.
$img = PLImage::make($img);
// Создаем HTTP-ответ с использованием метода response.
$response = $img->response(['Content-Type' => 'image/jpeg']);

stream() - 以流的形式输出图像。

use Smetaniny\LaravelImage\Facades\PLImage;

 /**
 * Выводит изображение в виде потока. 
 * Полезен, когда нужно передать большие файлы клиенту минимизируя использование памяти.
 *
 * @param array $headers Заголовки ответа.
 * 
 * @return StreamedResponse Потоковый HTTP-ответ.
 */
@method stream(array $headers = []): StreamedResponse

// Создаем объект изображения.
$img = PLImage::make($img);
// Создаем HTTP-ответ с использованием метода stream.
$response = $img->stream(['Content-Type' => 'image/jpeg']);

创建用户自定义命令

// Создаем класс команды. Данная команда реализована в пакете и несет информационный характер.
namespace App\Http\Controllers;

use ImagickException;
use Smetaniny\LaravelImage\Contracts\Image;
use Smetaniny\LaravelImage\Image;
use Smetaniny\LaravelImage\Facades\PLImage;

class FlipCommand extends Image implements Image
{
    /**
     * Обрабатывает отражение изображения по горизонтали или вертикали.
     *
     * @param string $mode Режим отражения: 'h' для горизонтального, 'v' для вертикального.
     *
     * @return Image Возвращает объект изображения после отражения.
     * @throws ImagickException Исключение, если произошла ошибка Imagick при кодировании изображения.
     */
    public function execute(string $mode = 'h'): Image
    {
        // Получаем ресурс изображения.
        $imagick = $image->getImageResource();

        // Отражаем изображение в зависимости от режима.
        if ($mode === 'h') {
            $imagick->flopImage();
        } elseif ($mode === 'v') {
            $imagick->flipImage();
        }

        // Обновляем ресурс изображения в текущем объекте $image.
        $image->setImageResource($imagick);

        return $image;
    }
}

# Применение пользовательской команды.
namespace App\Http\Controllers;
use Smetaniny\LaravelImage\Facades\PLImage;

class MainController
{
    public function index()
    {
        # Создание объекта изображения на основе данных, предоставленных UploadedFile.
        $img = PLImage::make($request->file('file'));
        # Регистрируем команду.
        $img->registerCommand('flip', '\App\Http\Controllers\FlipCommand');
        # Применяем команду.
        $img->flip();
       // Сохраняем.
        $img->save();
        // Получаем путь.
        $img->getSavePath();
        // Очищаем.
        $img->destroy();
    }
}

语义版本控制

项目版本格式为 X.Y.Z，其中

• X (主版本): 主版本在引入可能破坏向后兼容性的更改时增加。

• Y (次版本): 次版本在添加具有向后兼容性的新功能时增加。

• Z (补丁): 补丁版本在引入不影响向后兼容性的修复时增加。

版本 1.2.3 的更改示例

• 1 (主版本): 主要更改，可能不兼容先前版本。

• 2 (次版本): 添加新功能，与先前版本兼容。

• 3 (补丁): 修复错误，与先前版本兼容。

如果您还有任何问题，您可以在 Telegram 上提问