README

提供与FileJet API通信的PHP包装器。

要集成到Symfony项目中，请访问filejet/filejet-bundle仓库。

安装

您可以通过Composer轻松安装FileJet PHP库。

composer require filejet/filejet-php ^2.3

使用

您需要存储ID和API密钥才能与FileJet API通信。您可以在注册后通过filejet.io找到这些信息。

FileJet PHP库内部通过HttpClient调用FileJet API。我们在实现中使用了HTTPlug项目，因此您可以使用任何HTTP客户端。您可以通过安装它（见下文）并使用php-http/guzzle6-adapter轻松地使用它，或者您可以遵循HTTPlug教程来注册您选择的任何HTTP客户端。

composer require php-http/guzzle6-adapter ^1.1
composer require php-http/message ^1.6

设置您的服务

$apiKey = 'your api key';
$storageId = 'your storage id';
$signatureSecret = 'your signature secret';
$autoMode = true;

$fileJet = new FileJet\FileJet(
    new FileJet\HttpClient(),
    new FileJet\Config($apiKey, $storageId, $signatureSecret, $autoMode),
    new FileJet\Mutation()
);

FileJet\FileJet类提供了一些公共方法，可用于生成公共文件的URL（支持图像的即时修改），获取私有文件的签名URL，通过提供文件标识符生成上传文件到FileJet的签名指令，以及通过提供文件标识符从FileJet中删除文件。

uploadFile(UploadRequest $request): UploadInstruction

此方法生成将文件上传到FileJet的指令。FileJet\UploadInstructions包含将上传的文件的文件标识符 - 您应存储此信息以供以后使用（例如，用于生成链接或删除文件）。该对象还包含带有上传文件签名URL的上传格式对象，需要使用的HTTP方法和上传请求中需要使用的适当头。

您可以通过某些PHP HTTP客户端（由于FileJet API通信而已设置）上传文件，或者按照建议通过JavaScript异步上传文件。您将使用上传格式对象中的URL、头和HTTP方法，而主体将包含您想要上传的文件。

在FileJet\Messages\UploadRequest中，您需要指定要上传文件的MIME类型，文件的可访问性（公共或私有），例如，如果您希望文件通过FileJet CDN公开访问（适用于图像）或上传包含敏感信息的私有文件（适用于文档），该文件只能由具有正确存储ID和API密钥的用户访问。最后一个参数是可选的，它告诉FileJet上传链接应有效多长时间。默认值为60秒。

use FileJet\Messages\UploadRequest;

// get the upload instructions
$uploadInstruction = $fileJet->uploadFile(
    new UploadRequest('image/jpeg', UploadRequest::PUBLIC_ACCESS, 60)
);

// you should persist this string for later usage
$fileIdentifier = $uploadInstruction->getFileIdentifier();
$uploadFormat = $uploadInstruction->getUploadFormat();

$httpClient = new FileJet\HttpClient();
$httpClient->sendRequest(
    $uploadFormat->getRequestMethod(),
    $uploadFormat->getUri(),
    $uploadFormat->getHeaders(),
    $fileContent
);

为了更好的性能，我们建议通过JavaScript上传文件，通过您的后端从FileJet API获取上传格式，并将这些信息提供给前端。然后，您可以使用fetch。

<form action="#" id="form">
    <input type="file" name="file" id="file">
    <button type="submit">Upload</button>
</form>

const form = document.getElementById('form');
const input = document.getElementById('file');

form.addEventListener('submit', event => {
    event.preventDefault();

    const uploadFormat = fetch('path/to/your/endpoint');
    fetch(uploadFormat.uri, {
        method: uploadFormat.requestMethod,
        headers: uploadFormat.headers,
        body: input.files[0]
    })
});

bulkUploadFiles(UploadRequest[] $requests): UploadInstruction[]

当您想上传多个文件时，此方法很有用。它的工作方式与uploadFile()相同，但比多次调用uploadFile()更高效。

结果UploadInstruction[]的顺序与输入UploadRequest[]的顺序相同。默认使用php数组键。

use FileJet\Messages\UploadRequest;

// get the upload instructions
$uploadInstructions = $fileJet->bulkUploadFiles(
    [
        new UploadRequest('image/jpeg', UploadRequest::PUBLIC_ACCESS, 60),
        new UploadRequest('image/jpeg', UploadRequest::PUBLIC_ACCESS, 60),
        new UploadRequest('image/jpeg', UploadRequest::PUBLIC_ACCESS, 60),
    ]
);

foreach ($uploadInstructions as $uploadInstruction) {
    // you should persist this string for later usage
    $fileIdentifier = $uploadInstruction->getFileIdentifier();
    $uploadFormat = $uploadInstruction->getUploadFormat();
    
    $httpClient = new FileJet\HttpClient();
    $httpClient->sendRequest(
        $uploadFormat->getRequestMethod(),
        $uploadFormat->getUri(),
        $uploadFormat->getHeaders(),
        $fileContent
    );
}

getUrl(FileInterface $file): string

当您上传具有公共访问权限的文件时，例如，在获取上传格式时，您将使用FileJet\Messages\UploadRequest::PUBLIC_ACCESS，您可以通过FileJet CDN访问您的文件。此方法将根据您的配置生成文件的公开访问链接。

此方法仅接受一个参数，即描述您的文件的对象。您可以使用实现FileJet\FileInterface的FileJet\File对象来使用此方法。该对象包含由uploadFile()方法提供的文件标识符。如果您正在尝试获取图像的链接，您可以提供可选的突变字符串（见文档）。出于SEO目的，您可以提供可选的第三个参数，该参数将文件URL附加到您的自定义名称。

$reportUrl = $fileJet->getUrl(
    new FileJet\File(
        'fileIdentifierContainingOnlyCharactersAndDigits', 
        null, 
        'report.pdf'
    )
);

// $reportUrl will contain 'https://yourStorageId.5gcdn.net/fileIdentifierContainingOnlyCharactersAndDigits/report.pdf'

$imageUrl = $fileJet->getUrl(
    new FileJet\File(
        'fileIdentifierContainingOnlyCharactersAndDigits',
        'sz_100_100'
    )
);

// $imageUrl will contain 'https://yourStorageId.5gcdn.net/fileIdentifierContainingOnlyCharactersAndDigits/sz_100_100'

getPrivateUrl(string $fileId, int $expires): DownloadInstruction

将文件上传到私有存储后，您可以通过此方法检索下载链接。您只需要提供作为第一个参数的文件标识符。第二个参数指定链接有效的时间（例如，其过期时间）。

$downloadInstruction = $fileJet->getPrivateUrl('fileIdentifierContainingOnlyCharactersAndDigits', 60);

// $url will contain the download link valid for 60 seconds
$url = $downloadInstruction->getUrl();

getExternalUrl(string $url, string $mutation)

您无需通过FileJet服务上传文件即可使用其全部功能。您可以使用所有突变与您自己的图像。

只需使用此方法公开您使用FileJet突变的图像。为了使此方法工作，您需要添加您提供图像的域到白名单，或者您可以向您的配置提供signatureSecret。

您可以在https://app.filejet.io管理白名单和您的signatureSecret。

deleteFile(string $fileId): void

此方法将从FileJet删除文件。唯一的参数是从uploadFile()方法获得的文件标识符。

自动优化模式

您可以通过全局激活它，只需设置FileJet\Config的第三个参数为true，来使用我们的智能自动优化模式。这将向每个公开URL附加auto突变，负责向您的客户提供最优化版本的图像。

如果您不想全局使用自动模式，您可以通过简单地提供auto突变字符串来随时向您的图像附加它。

如果您正在全局使用自动优化模式，并且出于任何原因想要为特定图像禁用它，您可以通过提供auto=false突变来逐个图像禁用它。