GitHub - platina-jewelry/image: Обработка и сохранение изображений

Пакет image

Лицензия

Этот проект лицензирован в соответствии с MIT License.

Requirements (Требования):

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

Supported Image Libraries (Поддерживаемые библиотеки):

Imagick PHP extension (>= 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 (Патч): Исправление ошибок, совместимое с предыдущей версией.

Если у вас остались вопросы, вы можете задать их в телеграм

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
config		config
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
changelog.md		changelog.md
composer.json		composer.json
contributing.md		contributing.md
license.md		license.md
phpunit.xml		phpunit.xml

License

Licenses found

platina-jewelry/image

Folders and files

Latest commit

History

Repository files navigation