README

此包包含2个主要类，Image 和 ImageFilter，后者有8个子类可以用来对图像应用所需的过滤器。类 Image 依赖于服务器上已加载的 GD php 扩展。有关 GD 的更多信息，请参阅：https://php.ac.cn/manual/en/book.image.php

使用原始PHP和 GD image* 函数处理图像需要大量的模板代码。本包的目的是处理这些需求，并使开发者能够通过易于使用（且易于记忆）的方法轻松完成任务。

此包中的所有类都由自动加载器支持，因此可以在任何时间调用。

已弃用

joomla/image 包已弃用，没有计划进行未来更新。

构建

当创建一个新的 Image 对象时，构造函数将检查 gd 扩展是否已加载，如果没有加载，则抛出 RuntimeException。

构造函数接受一个可选的 $source 参数。此参数可以是以下两种情况之一

• 包含使用 imagecreate* 方法创建的现有、有效图像资源的变量。
• 包含有效、绝对路径的字符串

如果您选择第一种选项，类将设置受保护的属性 $handle 为提供的图像资源。如果您选择第二种选项，类将调用 loadFile 方法，并将 $source 参数传递给它。

use Joomla\Image\Image;

// Creating a new Image object, passing it an existing handle.
$resource = imagecreate(100, 100);
$image = new Image($resource);

// Creating a new Image object, passing it an image path
$image = new Image(JPATH_ROOT . '/media/com_foo/images/uploads/bar.png');

// Creating a new Image object then manually calling `loadFile`
$image = new Image;
$image->loadFile(JPATH_ROOT . '/media/com_foo/images/uploads/bar.png');

用法

请注意，大多数公共方法返回一个包含有效图像句柄的 Image 实例，以便于方法链。每个方法的示例将分别列出每个方法调用，以便能够注释代码正在做什么，但在生产代码中可以按如下方式链式调用（如果您喜欢）

use Joomla\Image\Image;

$image = new Image();
$image->loadFile(JPATH_ROOT . '/path/to/image.png')
	->crop(600, 250)
	->toFile(JPATH_ROOT . '/tmp/image.png');

自平台版本12.3起，有一个新的 destroy() 方法，该方法在类中的适当位置被调用，并运行 imagedestroy 函数来释放与图像句柄关联的内存。该方法在每次替换图像句柄之前（当 $createNew 设置为 false 时）以及类 __descruct 方法中作为最终清理时被调用。

resize 方法

接受参数

• $width：调整大小后的图像宽度，以像素或百分比为单位。
• $height：调整大小后的图像高度，以像素或百分比为单位。
• $createNew：如果为 true，则当前图像将被克隆、调整大小并返回；否则，当前图像将被调整大小并返回。
• $scaleMethod：用于缩放的方法

示例：使用 Image::resize() 生成调整大小的图像。

use Joomla\Image\Image;

// Create our image object
$image = new Image(JPATH_ROOT . '/media/com_foo/images/uploads/bar.png');

// Resize the image using the SCALE_INSIDE method
$image_resized = $image->resize(300, 150, true, Image::SCALE_INSIDE);

// Write it to disk
$image_resized->toFile(JPATH_ROOT . '/tmp/bar_resized.png');

crop 方法

接受参数

• $width：要裁剪的图像区域的宽度，以像素或百分比为单位。
• $height：要裁剪的图像区域的高度，以像素或百分比为单位。
• $left：从左侧开始裁剪的像素数。
• $top：从顶部开始裁剪的像素数。
• $createNew：如果为 true，则当前图像将被克隆、裁剪并返回；否则，当前图像将被裁剪并返回。

示例：使用 Image::crop() 生成裁剪后的图像。

use Joomla\Image\Image;

// Create our image object
$image = new Image(JPATH_ROOT . '/media/com_foo/images/uploads/bar.png');

// Crop the image to 150px square, starting 10 pixels from the left, and 20 pixels from the top
$image_resized = $image->crop(150, null, 10, 20);

// Write it to disk
$image_resized->toFile(JPATH_ROOT . '/tmp/bar_cropped.png');

在调整图像大小后保持比例裁剪图像，请使用具有熟悉参数 $width、$height 和 $createNew 的 cropResize 方法。

createThumbs 方法

接受参数

• $thumbSizes：字符串或字符串数组。示例：$thumbSizes = array('150x75','250x150');
• $creationMethod：请参阅下面的 调整大小方法。
• $thumbsFolder：缩略图的存放位置。传入 null 将在加载的图像所在文件夹中生成缩略图文件夹。

示例：使用 Image::createThumbs() 生成图像的缩略图。

use Joomla\Image\Image;

// Set the desired sizes for our thumbnails.
$sizes = array('300x300', '64x64', '250x125');

// Create our object
$image = new Image(JPATH_ROOT . '/media/com_foo/images/uploads/uploadedImage.jpg');

// Create the thumbnails
$image->createThumbs($sizes, Image::SCALE_INSIDE);

在此示例中，我们使用 Image 的 createThumbs 方法。该方法接受两个参数。第一个参数可以是一个包含单个大小的字符串，格式为 WIDTHxHEIGHT，也可以是一个包含大小的数组（如示例所示）。第二个参数指定了调整大小的方法。（请参阅调整大小方法下面的内容）

要获取不保存到磁盘的 Image 实例，请使用具有参数 $thumbSizes 和 $creationMethod 的 generateThumbs 方法。

调整大小方法

resize、createThumbs 和 generateThumbs 方法接受一个可选参数，用于定义在缩放图像时使用的方法。此参数可以是以下之一

• Image::SCALE_FILL - 提供一个精确大小的缩略图，拉伸或挤压以适应参数。
• Image::SCALE_INSIDE - 在给定参数内适应缩略图。它不会比传递的尺寸更高或更宽。
• Image::SCALE_OUTSIDE - 根据给定的参数适应缩略图。它将根据传递的尺寸等高或等宽，较小者为准。
• Image::SCALE_FIT - 保持宽高比适应给定边界。结果将在垂直方向上居中，水平方向上居中。
• Image::CROP - 提供一个精确大小的缩略图，从全尺寸图像的中心裁剪。
• Image::CROP_RESIZE - 如上所述，但提供从中心干净的调整大小和裁剪。

toFile 方法

接受参数

• $path：保存图像的文件系统路径。当为 null 时，将直接输出原始图像流。
• $type：保存文件作为图像类型（IMAGETYPE_GIF | IMAGETYPE_PNG | IMAGETYPE_JPEG）。
• $options：保存文件时使用的图像类型选项。使用 quality 键设置压缩级别（PNG 为 0..9，JPEG 为 0..100）。

示例：使用 Image::toFile() 将图像保存为具有 65 压缩级别的 JPEG。

use Joomla\Image\Image;

// Create our object
$image = new Image(JPATH_ROOT . '/media/com_foo/images/uploads/bar.png');

// Write to disk
$image->toFile(JPATH_ROOT . '/tmp/bar.jpg', IMAGETYPE_JPEG, array('options' => 65));

示例：使用 Image::toFile() 获取图像的数据块。

use Joomla\Image\Image;

// Create our object
$image = new Image(JPATH_ROOT . '/media/com_foo/images/uploads/bar.png');

// Enable output buffering
ob_start();

// Retrieve data blob
$image->toFile(null, IMAGETYPE_PNG);
$imageBlob = ob_get_clean();

通过 Composer 安装

将 "joomla/image": "2.0.*@dev" 添加到 composer.json 中的 require 块，然后运行 composer install。

{
	"require": {
		"joomla/image": "2.0.*@dev"
	}
}

或者，您可以直接从命令行运行以下命令

composer require joomla/image "2.0.*@dev"

如果您想包含测试源，请使用

composer require --prefer-source joomla/image "~1.0"