README

这是官方Kraken.io PHP库，可以帮助用户非常快速地将我们的图片优化集成到PHP项目中。Kraken.io图片优化器。

安装
入门指南
下载图片
如何使用
等待和回调URL
- 等待选项
- 回调URL
身份验证
使用 - 图片URL
使用 - 图片上传
有损优化
图片缩放
WebP压缩
图片类型转换
保留元数据
外部存储

安装

Composer

如果你使用Composer，你可以在项目的composer.json文件中添加对kraken-io/kraken-php的依赖。以下是一个对版本1.2的依赖示例

{
    "require": {
        "kraken-io/kraken-php": "^1.2"
    }
}

或者你还可以在项目的根目录中执行以下命令

composer require kraken-io/kraken-php

Git

如果你已经安装了git，下载Kraken-PHP库最简单的方法是使用git命令

git clone git://github.com/kraken-io/kraken-php.git /path/to/include/kraken

手动操作

或者，你可以从GitHub下载PHP文件并将它们放置在你的PHP项目中

https://github.com/kraken-io/kraken-php/archive/master.zip

入门指南

首先，你需要注册Kraken.io API并获取你的唯一API密钥和API密钥。你可以在API凭证下找到它们。一旦设置好账户，你就可以开始在应用程序中使用Kraken.io API了。

下载图片

记住 - 永远不要链接到提供的下载优化图像。你必须先下载它们，然后替换你网站或应用程序中的图像。由于安全原因，优化图像仅在服务器上可用一小时。

如何使用

你可以通过提供要优化的图片的URL或直接上传图片文件到Kraken.io API来优化图片的两种方式。

第一种选项（图片URL）非常适合已经在生产或任何其他互联网位置上的图片。第二种（直接上传）非常适合你的部署过程、构建脚本或用户上传的即时处理，在这种情况下，你还没有在线图片。

等待和回调URL

Kraken.io提供了两种方法来获取优化结果。当设置wait选项时，结果将立即在响应中返回。当设置callback_url选项时，结果将被发送到请求中指定的URL。

等待选项

当API的每个请求都开启wait选项时，连接将保持打开状态，直到图片被优化。一旦完成，你将立即收到一个包含优化结果的JSON对象的响应。要使用此选项，只需在请求中设置"wait": true即可。

请求

{
    "auth": {
        "api_key": "your-api-key",
        "api_secret": "your-api-secret"
    },
    "url": "http://image-url.com/file.jpg",
    "wait": true
}

响应

{
    "success": true,
    "file_name": "file.jpg",
    "original_size": 324520,
    "kraked_size": 165358,
    "saved_bytes": 159162,
    "kraked_url": "http://dl.kraken.io/d1aacd2a2280c2ffc7b4906a09f78f46/file.jpg"
}

回调URL

使用回调URL，HTTPS连接将立即终止，并在响应正文中返回一个唯一的id。优化完成后，Kraken.io将向请求中指定的callback_url发送一条消息。响应中的ID将反映在回调URL中发布的ID。

我们推荐使用RequestBin作为捕捉优化结果进行初步测试的便捷方式。

请求

{
    "auth": {
        "api_key": "your-api-key",
        "api_secret": "your-api-secret"
    },
    "url": "http://image-url.com/file.jpg",
    "callback_url": "http://awesome-website.com/kraken_results"
}

响应

{
    "id": "18fede37617a787649c3f60b9f1f280d"
}

将结果发布到回调URL

{
    "id": "18fede37617a787649c3f60b9f1f280d"
    "success": true,
    "file_name": "file.jpg",
    "original_size": 324520,
    "kraked_size": 165358,
    "saved_bytes": 159162,
    "kraked_url": "http://dl.kraken.io/18fede37617a787649c3f60b9f1f280d/file.jpg"
}

身份验证

第一步是在创建新的Kraken.io实例时，通过提供唯一的API密钥和API密钥进行认证。

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

使用 - 图片URL

要通过提供图像URL来优化图像，请使用kraken.url()方法。您需要在一个数组中提供两个必需的参数 - 图像的url和wait或callback_url。

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "url" => "http://url-to-image.com/file.jpg",
    "wait" => true
);

$data = $kraken->url($params);

根据在data数组中选择响应选项（等待或回调URL），您将找到优化ID或包含success属性、文件名、原始文件大小、Kraked文件大小、节省量和优化图像URL的优化结果。

array(6) {
    'success' =>
    bool(true)
    'file_name' =>
    string(8) "file.jpg"
    'original_size' =>
    int(62422)
    'kraked_size' =>
    int(52783)
    'saved_bytes' =>
    int(9639)
    'kraked_url' =>
    string(65) "http://dl.kraken.io/d1aacd2a2280c2ffc7b4906a09f78f46/file.jpg"
}

使用 - 图片上传

如果您想直接将图像上传到Kraken.io API，请使用kraken->upload()方法。您需要在一个数组中提供两个必需的参数 - 文件的绝对路径的file和wait或callback_url。

在$data数组中，您将找到与上述url选项相同的优化属性。

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true
);

$data = $kraken->upload($params);

有损优化

当您决定牺牲一点图像质量（通常对人眼不可见）时，您可以将初始文件重量节省高达90%。有损优化将以仅损失少量图像质量的结果脱颖而出。

要使用有损优化，只需在请求中设置"lossy" => true

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "lossy" => true
);

$data = $kraken->upload($params);

PNG图像

PNG图像将从24位转换为具有完整alpha通道的调色板8位。这个过程称为RGBA格式的PNG量化，意味着图像中使用的颜色数量将减少到256，同时保持所有关于alpha透明度的信息。

JPEG图像

对于有损JPEG优化，Kraken.io将为输入图像生成多个具有不同质量设置的副本。然后，它将智能地选择具有最佳质量与文件大小比率的副本。这确保了您的JPEG图像将以可能的最大质量在最小的尺寸下，无需人工选择最佳图像。

图片缩放

图像调整大小选项非常适合在应用程序中创建缩略图或预览图像。Kraken.io首先调整给定图像的大小，然后使用其丰富的优化算法对其进行优化。resize选项需要传递一些参数，例如所需的width和/或height以及一个强制性的strategy属性。例如

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "resize" => array(
        "width" => 100,
        "height" => 75,
        "strategy" => "crop"
    )
);

$data = $kraken->upload($params);

strategy属性可以有以下值之一

exact - 按精确的宽度和高度调整大小。不会保持纵横比。
portrait - 设置精确宽度，高度将根据纵横比进行调整。
landscape - 设置精确高度，宽度将根据纵横比进行调整。
auto - 根据纵横比为给定图像选择最佳策略（肖像或风景）。
fit - 此选项将裁剪和调整您的图像以适应所需的宽度和高度。
square - 此策略将首先通过其较短的维度裁剪图像以使其成为正方形，然后将其调整到指定的大小。
crop - 此选项将以无失真的方式裁剪您的图像到您指定的确切大小。
fill - 这种策略允许您调整图像大小以适应指定的边界，同时保持宽高比（类似于自动策略）。可选的背景属性允许您指定一个颜色，用于填充先前指定的边界中未使用的部分。背景属性可以使用十六进制表示法 #f60 或 #ff6600，RGB rgb(255, 0, 0) 或 RGBA rgba(91, 126, 156, 0.7) 格式化。默认背景颜色为白色。

有关图像调整大小和裁剪的更多信息，请参阅 Kraken.io API 参考文档

WebP压缩

WebP 是 Google 在 2010 年推出的一种新的图像格式，支持有损和无损压缩。根据 Google 的信息，WebP 无损图像比 PNG 小 26%，WebP 有损图像比 JPEG 图像小 25-34%。

要将 PNG 或 JPEG 文件重新压缩为 WebP 格式，只需在您的请求 JSON 中设置 "webp": true 标志即可。您还可以可选地设置 "lossy": true 标志以利用 WebP 的有损压缩

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "webp" => true,
    "lossy" => true
);

$data = $kraken->upload($params);

图片类型转换

Kraken.io API 允许您轻松地将不同类型的图像从一个格式转换为另一个格式。例如，如果您想将透明的 PNG 文件转换为具有灰色背景的 JPEG，Kraken.io API 可以满足您的需求。

为了在不同图像类型之间进行转换，您需要在请求 JSON 中添加一个额外的 convert 对象。该对象包含三个属性

format，用于指定您希望将图像转换为的文件类型。
一个可选的 background 属性，其中您可以指定在将透明文件格式（如 PNG 和 GIF）转换为全不透明格式（如 JPEG）时的背景颜色。
一个可选的 keep_extension 属性，允许您在输出图像格式的情况下保持原始文件扩展名不变。

必选参数

format - 您希望将图像转换为的图像格式。此参数可以接受以下值之一：jpeg、png 或 gif。

可选参数

background - 将透明文件格式（如 PNG 或 GIF）转换为全不透明格式（如 JPEG）时的背景图像。背景属性可以通过十六进制表示法 "#f60" 或 "#ff6600"、RGB "rgb(255, 0, 0)" 或 RGBA "rgba(91, 126, 156, 0.7)" 传递。默认背景颜色为白色。
keep_extension - 一个布尔值（true 或 false），指示 Kraken.io API 是否应在输出文件名中保留原始扩展名。例如，当将 "image.jpg" 转换为 PNG 格式且此标志打开时，输出图像名称仍将是 "image.jpg"，尽管图像已被转换为 PNG。默认值为 false，表示始终设置正确的扩展名。

保留元数据

默认情况下，Kraken.io API 将 删除图像中找到的所有元数据，以使图像文件尽可能小，并在有损和无损模式下进行。如 EXIF、XMP 和 IPTC 标签、颜色配置文件信息等条目将全部删除。

{
    "preserve_meta": ["date", "copyright", "geotag", "orientation", "profile"]
}

profile - 将保留ICC颜色配置文件。ICC颜色配置文件信息会给图像添加不必要的冗余。然而，在极其罕见的情况下，保留它可能是必要的，因为删除此信息可能会导致输出文件亮度或饱和度的变化。
date - 将保留图像创建日期。
copyright - 将保留版权信息。
geotag - 将保留位置特定信息。
orientation - 将保留方向（旋转）标记。

示例集成

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "preserve_meta" => array("profile", "geotag")
);

$data = $kraken->upload($params);

外部存储

Kraken.io API 允许您将优化后的图像直接存储到您的 S3 桶、Cloud Files 容器、Azure 容器或 SoftLayer 对象存储容器中。只需几个额外的参数，您的优化图像就可以立即推送到您的外部存储。

Amazon S3

必选参数

key - 您唯一的 Amazon "访问密钥 ID"。
secret - 您唯一的 Amazon "秘密访问密钥"。
bucket - 您 Amazon S3 账户中目标容器的名称。
region - 您 S3 桶所在区域的名称。如果区域不是默认的（us-east-1），则此字段为必填项。S3 区域的完整列表可以在此处找到。

可选参数

path - 您 S3 桶中的目标路径（例如 "images/layout/header.jpg"）。默认为根目录 "/"。
acl - 目标对象的权限。这可以是 "public_read" 或 "private"。默认为 "public_read"。

上述参数必须通过 s3_store 键传递

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "s3_store" => array(
        "key" => "your-amazon-access-key",
        "secret" => "your-amazon-secret-key",
        "bucket" => "destination-bucket"
    )
);

$data = $kraken->upload($params);

$data 数组将包含一个指向您 Amazon S3 账户中优化文件的 kraked_url 键。

"kraked_url" => "http://s3.amazonaws.com/YOUR_CONTAINER/path/to/file.jpg"

Rackspace Cloud Files

必选参数

user - 您的 Rackspace 用户名。
key - 您唯一的 Cloud Files API 密钥。
container - 您 Cloud Files 账户中目标容器的名称。

可选参数

path - 您容器中的目标路径（例如 "images/layout/header.jpg"）。默认为根目录 "/"。
ssl - 一个布尔值（true 或 false），指示 Kraken.io API 从 Rackspace CloudFiles 获取 SSL 或非 SSL URL。默认为 false，表示将返回非 SSL URL。

上述参数必须通过 cf_store 键传递

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "cf_store" => array(
        "user" => "your-rackspace-username",
        "key" => "your-rackspace-api-key",
        "container" => "destination-container",
        "ssl" => true
    )
);

$data = $kraken->upload($params);

如果您的容器启用了 CDN，优化结果将包含指向您 Cloud Files 账户中优化文件位置的 kraked_url。

kraked_url => "http://e9ffc04970a269a54eeb-cc00fdd2d4f11dffd931005c9e8de53a.r2.cf1.rackcdn.com/path/to/file.jpg"

如果您的容器未启用 CDN，优化文件仍然将存储在您的 CloudFiles 账户中，但 kraked_url 将指向 Kraken.io API 存储中的优化图像 URL。

kraked_url => "http://dl.kraken.io/ecdfa5c55d5668b1b5fe9e420554c4ee/file.jpg"

Microsoft Azure

必选参数

account - 您的 Azure 存储账户。
key - 您唯一的 Azure 存储访问密钥。
container - 您 Azure 账户中目标容器的名称。

可选参数

path - 您容器中的目标路径（例如 "images/layout/header.jpg"）。默认为根目录 "/"。

上述参数必须通过 azure_store 键传递

<?php

require_once("Kraken.php");

$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "azure_store" => array(
        "account" => "your-azure-account",
        "key" => "your-azure-storage-access-key",
        "container" => "destination-container"
    )
);

$data = $kraken->upload($params);

SoftLayer对象存储

必选参数

user - 您的 SoftLayer 用户名。
key - 您的 SoftLayer API 密钥。
container - 您 SoftLayer 账户中目标容器的名称。
region - 您容器所在区域的简称。这可以是以下之一：syd01 lon02 mon01 dal05 tok02 tor01 hkg02 mex01 par01 fra02 mil01 sjc01 sng01 mel01 ams01

可选参数

path - 您容器中的目标路径（例如 "images/layout/header.jpg"）。默认为根目录 "/"
cdn_url - 一个布尔值 true 或 false，指示 Kraken.io API 返回优化文件的公共 CDN URL。默认为 false，表示将返回非 CDN URL。

上述参数必须通过 sl_store 对象传递

<?php

require_once("Kraken.php");
$kraken = new Kraken("your-api-key", "your-api-secret");

// Minimal request, providing only the mandatory parameters */
$params = array(
    "file" => "/path/to/image/file.jpg",
    "wait" => true,
    "sl_store" => array(
        "user" => "your-softlayer-account",
        "key" => "your-softlayer-key",
        "container" => "destination-container",
        "region" => "your-container-location"
    )
);

$data = $kraken->upload($params);

以下是一个使用 sl_store 将优化后的图片推送到您的SoftLayer对象存储容器的完整JSON请求示例。我们将使用URL选项为API提供要优化的图片的URL。

<?php

require_once("Kraken.php");
$kraken = new Kraken("your-api-key", "your-api-secret");

$params = array(
    "url" => "http://awesome-website.com/images/header.jpg",
    "wait" => true,
    "sl_store" => array(
        "user" => "your-softlayer-account",
        "key" => "your-softlayer-key",
        "container" => "destination-container",
        "region" => "your-container-location",
        "cdn_url" => true,
        "path" => "images/layout/header.jpg"
    )
);

$data = $kraken->upload($params);

如果您的SoftLayer容器已启用CDN，并且您在JSON请求中传递了"cdn_url": true参数，则优化结果将包含kraked_url，该URL直接指向您的SoftLayer CDN中优化文件的存储位置，例如：

kraked_url => "http://1c231.http.fra02.cdn.softlayer.net/images/layout/header.jpg"

如果您的容器未启用CDN，kraked_url将指向Kraken.io API中的优化图片URL。

kraked_url => "http://dl.kraken.io/api/ecdfa5c55d5668b1b5fe9e420554c4ee/header.jpg"

授权协议 - MIT

在此特此授予任何获得此软件及其相关文档副本（以下简称“软件”）的人免费使用的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向获得软件的人提供这些权利，但须遵守以下条件：

kraken-io / kraken-php

维护者

详情

README

安装

Composer

Git

手动操作

入门指南

下载图片

如何使用

等待和回调URL

等待选项

回调URL

身份验证

使用 - 图片URL

使用 - 图片上传

有损优化

PNG图像

JPEG图像

图片缩放

WebP压缩

图片类型转换

保留元数据

外部存储

Amazon S3

Rackspace Cloud Files

Microsoft Azure

SoftLayer对象存储

授权协议 - MIT