README

randomhost/image

1. 目的
2. 使用方法
3. 许可证

1. 目的

此包封装了一些常见的GD库操作在PHP类中。它是作为randomhost/webcamoverlay包的一部分创建的，但作为独立的组件发布，因此可以在其他包中使用。

因为它作为randomhost/webcamoverlay包的依赖项创建，所以它只支持可用图像处理函数的一小部分。

2. 使用方法

使用此包的基本方法可能如下所示

<?php
namespace randomhost\Image;

require_once '/path/to/vendor/autoload.php';

// load base image
$image = Image::getInstanceByPath('image.png');

// load overlay image
$overlay = Image::getInstanceByPath('overlay.png');

// insert overlay image on top of base image at x 15, y 20
$image->merge($overlay, 15, 20);

// set up a red text overlay
$text = new Text\Generic($image);
$text
    ->setTextFont('vera.ttf')
    ->setTextSize(12)
    ->setTextColor(
        new Color(
            0xFF,
            0x00,
            0x00
        )
    );

// set up a white border for the previously defined text overlay
$text = new Text\Decorator\Border($text);
$text->setBorderColor(
    new Color(
        0xFF,
        0xFF,
        0xFF
    )
);

// render text overlay onto the image at x 20, y 10
$text->insertText(
    20,
    10,
    'Example text'
);

// render the image
$image->render();

这将使用来自文件系统的图像文件实例化两个图像对象，合并图像并在上面渲染叠加文本。

假设你将此文件命名为image.php，你现在应该能够通过http://example.com/image.php访问图像

2.1. Image对象

Image对象表示一个在(远程)文件系统中或在内存中创建的图像。它提供获取图像信息以及合并其他Image实例的方法。

2.1.1. 实例化

创建Image对象实例有两种方法

Image::getInstanceByPath($path, $cacheDir = '')
从现有的本地或远程图像文件创建实例。
- $path
  图像文件的路径或URL。
- $cacheDir
  可选：缓存图像文件的目录路径。当从远程位置检索图像时很有用，因为本地缓存可以减少必须执行的HTTP请求的数量。
Image::getInstanceByCreate($width, $height)
创建一个具有给定图像尺寸的空实例，可以将其用于合并(多个)其他Image实例。
- $width
  生成的图像宽度。
- $height
  生成的图像高度。

2.1.2. 获取图像数据

以下公开方法可用于获取图像相关数据

getMimetype()
返回图像的Mimetype。
getModified()
返回图像的最后修改时间戳。当使用getInstanceByCreate()创建实例时，这将是对象最初创建的时间。
getWidth()
返回图像的像素宽度。
getHeight()
返回图像的像素高度。

2.1.3. 合并图像

merge(Image $srcImage, $dstX, $dstY, $strategy = self::MERGE_SCALE_SRC)
使用给定的坐标和缩放策略，将给定Image实例的图像资源合并到活动Image实例的图像资源中。
mergeAlpha(Image $srcImage, $dstX, $dstY, $alpha = 127)
使用给定的坐标和透明度将指定Image实例的图像资源合并到活动Image实例的图像资源中。此方法不支持缩放。

2.1.4. 缩放策略

Image::MERGE_SCALE_SRC
此策略使用传递给merge()的Image实例的宽度和高度。如果要合并的图像超出了目标实例的尺寸，它将被裁剪以适应目标实例的尺寸。
Image::MERGE_SCALE_DST
此策略将传递给merge()的Image实例的大小调整为与目标实例的尺寸相匹配。但是，给merge()提供的x和y偏移量将不予考虑，因此要合并的图像仍可能被裁剪。
Image::MERGE_SCALE_DST_NO_UPSCALE
此策略与Image::MERGE_SCALE_DST类似，但如果要合并的图像小于目标实例，则不会放大图像。

2.1.5. 渲染图像

render()
将图像流输出到浏览器。目前，图像将始终以image/png格式渲染，以支持完整的透明度。未来版本可能添加对其他格式的支持。

2.2. Color对象

Color对象仅是一个数据容器，用于在PHP_Image包中定义要使用的颜色值。它提供了一系列设置器和获取器来设置和检索颜色和alpha通道数据。

2.2.1. 构造函数

构造函数接受4个参数，这些参数都是可选的

$red
红色分量（0-255或0x00-0xFF）。
$green
绿色分量（0-255或0x00-0xFF）。
$blue
蓝色分量（0-255或0x00-0xFF）。
$alpha
alpha值（0-127）

2.2.2. 配置颜色

setRed($red)
设置红色分量（0-255或0x00-0xFF）。
setGreen($green)
设置绿色分量（0-255或0x00-0xFF）。
setBlue($blue)
设置蓝色分量（0-255或0x00-0xFF）。
setAlpha($alpha)
设置alpha值（0-127）。0表示完全不透明，而127表示完全不透明。

2.2.3. 获取颜色数据

getRed()
返回红色分量（0-255或0x00-0xFF）。
getGreen()
返回绿色分量（0-255或0x00-0xFF）。
getBlue()
返回蓝色分量（0-255或0x00-0xFF）。
getAlpha()
返回alpha值（0-127）。0表示完全不透明，而127表示完全不透明。

2.2.4. 验证颜色数据

Color::validateColor($color)
验证颜色值。如果值无效，则抛出InvalidArgumentException。
Color::validateAlpha($alpha)
验证alpha值。如果值无效，则抛出InvalidArgumentException。

2.3. Image/Text/Generic对象

Image/Text/Generic对象是一个通用的文本渲染对象，可以使用装饰器扩展其功能。

2.3.1. 构造函数

构造函数接受1个可选参数

$image
要操作的Image实例。这也可以稍后使用setImage()方法设置。

2.3.2. 配置文本

setImage(Image\Image $image)
设置Image对象实例。
setTextColor(Image\Color $color)
设置用于渲染文本的Color。
setTextFont($path)
设置用于渲染的字体文件路径。
setTextSize($size)
设置用于渲染的文本大小。

2.3.3. 获取文本数据

getImage()
返回Image对象实例。
getTextColor()
返回用于渲染文本的Color。
getTextFont()
返回用于渲染的字体文件路径。
getTextSize()
返回用于渲染的文本大小。

2.3.4. 渲染文本

insertText($xPosition, $yPosition, $text)
使用给定的坐标在图像资源上渲染指定的文本。

2.4. Image/Text/Decorator对象家族

Image/Text/Decorator对象家族包含用于文本渲染对象的装饰器，这些装饰器可以向Image/Text/Generic对象或其他实现Image\Text\Text接口的对象添加额外功能。

由于它们可以包裹任何 Image\Text\Text 实现，这些实现也可以是另一个 Image/Text/Decorator 实例，因此它们共享被装饰对象的全部方法，并且也可以定义自己的方法。

2.4.1. 构造函数

构造函数依赖于特定的 Image/Text/Decorator 实现，但通常至少需要一个参数，即要装饰的对象。

$text
要装饰的 Image\Text\Text 实现。

2.4.2. 获取文本装饰器数据

providesMethod($name)
返回给定的方法是否由对象树中的任何一个装饰器实现，因为装饰器可以堆叠。

2.4.3. 使用装饰器渲染文本

由于所有装饰器都实现了与标准 Image/Text/Generic 对象相同的接口，因此使用装饰文本对象进行渲染的方式与使用非装饰对象进行渲染的方式相同。

insertText($xPosition, $yPosition, $text)
使用给定的坐标在图像资源上渲染指定的文本。

2.5. Image/Text/Decorator/Border对象

Image/Text/Decorator/Border 对象是文本渲染对象的装饰器，它为渲染的文本添加了一个简单的边框。

2.5.1. 配置边框

setBorderColor(Image\Color $color)
设置用于渲染边框的颜色。

2.5.2. 获取边框数据

getBorderColor()
返回用于渲染边框的颜色。

3. 许可证

有关完整的许可详情，请参阅 LICENSE.txt。

randomhost / image

维护者

详细信息