README

Charcoal Image 是一个 PHP 图像处理和转换库，提供跨不同图像驱动的一致 API。当前支持的驱动包括 Imagick（PHP 扩展）和 Imagemagick（使用 shell 命令）

• API 文档

如何安装

安装 charcoal-image 的首选（也是唯一支持）方式是使用 composer

$ composer require locomotivemtl/charcoal-image

依赖

• PHP 5.6+
• locomotivemtl/charcoal-factory
• ext-imagick（可选但推荐）或
• ImageMagick 二进制文件

👉 虽然这个模块是为 Charcoal 开发的，但它绝对不依赖于任何 Charcoal 模块，因此可以在任何 PHP 项目中使用。

为什么还需要另一个 PHP 图像库？

为什么不呢？ Charcoal-Image 已经开发和使用了近 10 年。最近它已经被重写为更现代的 PHP 风格，并作为开源许可（MIT）发布。

与现有的 PHP 库（如 Imagine 或 Intervention）的主要区别是

• 效果参数以数组形式发送。
  • 是 blur($sigma, $radius) 还是 blur($radius, $sigma)？
  • 使用 charcoal image 它是一致的： blur([ 'radius' => $radius, 'sigma' => $sigma ]);
• 它支持 ImageMagick 二进制文件
  • 似乎有一个相当常见的设置，即服务器上安装了 Imagemagick，但没有安装 Imagick PHP 库。charcoal-image 可以使用
• 除了微小的 charcoal-factory 外，没有外部依赖。

用法

通常，charcoal-image 用于加载图像，执行操作（称为 效果，例如模糊、调整大小、水印等）并将修改后的图像写入。

使用 setData()

所有效果可以一次性添加到一个数组中。

$img = new \Charcoal\Image\Imagick\ImagickImage();
$img->setData([
    'source'  => 'example.png',
    'target'  => 'example-modified.png',
    'effects' => [
        [
            'type'  => 'resize',
            'width' => 600
        ],
        [
            'type'  => 'blur',
            'mode'  => 'gaussian',
            'sigma' => 5
        ]
    ]
]);
$img->process();
$img->save();

setData() 对于效果来自 JSON 配置结构等场景非常适用。

使用魔法方法

所有效果也可以作为图像的方法使用（使用 __call() 魔法）。

use Charcoal\Image\Imagick\ImagickImage as Image;

$img = new Image();
$img->open('example.png');
$img->resize([
    'width' => 600
]);
$img->blur([
    'mode'  => 'gaussian',
    'sigma' => 5
]);
$img->save();

链式版本

同时展示：使用 ImageFactory 构造函数方法

use \Charcoal\Image\ImageFactory;

$factory = new ImageFactory();
$img = $factory->create('imagemagick');
$img->open('example.png')
    ->resize([
        'mode'   => 'best_fit',
        'width'  => 350
        'height' => 350
    ])
    ->rotate([
        'angle' => 90
    ])
    ->modulate([
        'luminance' => 50
    ])
    ->save('modified-target.png');

可用的效果和操作在 API 文档 中有说明。

可用的图像驱动程序

目前只有 2 个可用的驱动程序

• imagick
  • imagick 驱动程序使用 Imagick PHP 扩展，该扩展建立在 ImageMagick 之上。
• imagemagick
  • imagemagick 驱动程序直接使用 imagmagick 二进制文件，在单独的 shell 进程中运行操作，而不是直接在 PHP 中。
  • 系统上应安装并可以从 PHP 进程访问的命令 convert、mogrify 和 identify。

👉 即将推出，使用 PHP 内置图像能力的 gd 驱动程序。

如何选择驱动程序

有两种不同的方式为特定驱动程序实例化一个 Image 对象。

直接

$img = new \Charcoal\Image\Imagick\ImagickImage();
// or
$img = new \Charcoal\Image\Imagemagick\ImagemagickImage();

使用提供的 ImageFactory

use \Charcoal\Image\ImageFactory;
$factory = new ImageFactory();

$img = $factory->create('imagick');
// or
$img = $factory->create('imagemagick');

开发

安装开发环境

★ composer install --prefer-source

运行测试

★ composer test

编码风格

所有 Charcoal 模块都遵循相同的编码风格，charcoal-image 也不例外。对于 PHP

• PSR-1
• PSR-2
• PSR-4，因此自动加载由 Composer 提供
• phpDocumentor
• 数组应使用短表示法（使用 [] 而不是 array()）

使用 grunt phpcs（PHP Code Sniffer）强制执行编码风格。实际规则集可以在 phpcs.xml 中找到。

👉 要修复编码风格的轻微问题，请运行 grunt phpcbf（PHP Code Beautifier and Fixer）。此工具使用与 phpcs 相同的规则集来自动纠正编码标准违规。

主要的PHP结构遵循 PSR-4 标准。因此，自动加载由 Composer 提供。

为确保代码库干净，应在所有开发环境中安装预提交git钩子。

持续集成

• Travis
• Sensio Labs
• Scrutinizer

单元测试

每个类、方法和函数都应该由单元测试覆盖。PHP代码可以使用 PHPUnit 进行测试。

作者

• Mathieu Ducharme mat@locomotive.ca

变更日志

0.3

发布于 2016-03-11

• 以任何方式破坏BC。
• 转换为camelCase / 完全支持PSR-1 / PSR-2。

0.2

发布于 2015-09-15

• 添加新的“自动方向”效果（imagick + imagemagick）
• 为imagemagick添加水印效果
• 修复了锐化效果中的“非锐化蒙版”模式（imagick）
• 修复了水印效果的重力（imagick）
• 接受 ImageInterface 对象作为水印（全局）
• 添加对 locomotivemtl/charcoal-factory 的依赖关系，并相应地修复工厂。（全局）

0.1

发布于 2015-08-26

• 初始发布

待办事项

• 编写PHP的 gd 驱动程序的版本。
• 自定义异常。
• 将效果签名更改为可调用的（可调用的）而不是使用process()方法。
• 如果驱动程序不可用，则跳过单元测试而不是失败。