PHP SDK V1到V2迁移指南

完整迁移步骤

第一步：环境准备

1. 评估现有代码：

   • 梳理现有代码中使用OSS SDK的位置

   • 记录您使用了哪些OSS功能和接口

   • 确定依赖关系，避免迁移过程中出现意外问题

2. 更新PHP运行环境：

   • V2版本要求PHP的运行环境版本最低为7.4。

3. 保留V1版SDK以便逐步迁移，安装V2版SDK：

   1. 通过 composer 安装

      如果您通过composer管理您的项目依赖，可以在你的项目根目录运行：

      composer require alibabacloud/oss-v2

      或者在composer.json中声明对Alibaba Cloud OSS SDK for PHP v2的依赖：

      "require": {    "alibabacloud/oss-v2": "*"
      }

      然后通过composer install命令安装依赖

   2. 通过PHAR 文件安装

      require_once '/path/to/alibabacloud-oss-php-sdk-v2-{version}.phar'

4. 创建测试环境：

   • 建议创建独立的测试环境，而不是直接在生产环境修改

   • 配置测试数据和测试用例，用于验证迁移后的代码

第二步：修改导入语句

功能变更

PHP SDK V2版本启用了新的代码仓库（alibabacloud-oss-php-sdk-v2），并对代码结构进行了优化调整。此次调整按照功能模块对代码进行了重新组织，旨在提升代码的可读性和维护性。以下是各个模块的路径及其相应说明：

代码示例

# V1版
require_once 'vendor/autoload.php';
use OSS\OssClient;

# V2版
require_once  'vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;

第三步：修改创建客户端代码

功能变更

1. V2 版本简化了配置设置方式，全部迁移到 config下，并提供了以set为前缀的辅助函数，方便以编程方式覆盖缺省配置

2. V2版本默认采用V4签名算法，因此在配置客户端时必须指定阿里云通用Region ID作为发起请求地域的标识。

3. V2版本支持根据所选区域（Region）自动生成访问域名（Endpoint）。当您访问公网域名时，无需手动设置Endpoint，系统将自动依据您的区域信息进行构造。

代码示例

require_once 'vendor/autoload.php';
use OSS\OssClient;
...

// 环境变量中获取访问凭证
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();

// Endpoint
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";

$config = array(
       "provider" => $provider,
       "endpoint" => $endpoint,
       "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
       "region" => "cn-hangzhou"
   );
$ossClient = new OssClient($config);
// 不校验SSL证书校验
$ossClient->setUseSSL(false);

require_once 'vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;
...

// 环境变量中获取访问凭证
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
// 设置HTTP连接超时时间为20秒
$cfg->setConnectTimeout(20);
// HTTP读取或写入超时时间为60秒
$cfg->setReadWriteTimeout(60);
// 不校验SSL证书校验
$cfg->setDisableSSL(true);
// 设置区域
$cfg->setRegion('cn-hangzhou');
$client = new Oss\Client($cfg);

关于V2版配置客户端的更多详细示例，请参见配置客户端。

关于V2版配置访问凭证的更多详细示例，请参见配置访问凭证。

第四步：修改基础API调用方式

功能变更

1. SDK V2版本提供了与REST API对应的接口，把这类接口叫做基础接口或者低级别API。您可以通过这些接口访问OSS的服务，例如创建存储空间，上传文件和下载文件等。

2. 在V2版本中，各个基础API接口遵循一套标准化的命名规则。每个操作方法均命名为<OperationName>形式，其中，操作的请求参数类被定义为<OperationName>Request，而操作的结果返回值则定义为<OperationName>Result，如下所示。

   public function <operationName>(Models\<OperationName>Request $request, array $args = []): Models\<OperationName>Result
   public function <operationName>Async(Models\<OperationName>Request $request, array $args = []): \GuzzleHttp\Promise\Promise

关于基础API的更多详细说明，请参考开发者指南-基础接口。

代码示例

require_once 'vendor/autoload.php';
use OSS\OssClient;
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
$config = array(
    "provider" => $provider,
    "endpoint" => $endpoint,
    "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
    "region" => "cn-hangzhou"
);
$ossClient = new OssClient($config);
$ossClient->putObject('examplebucket','exampleobject.txt','example data');

require_once 'vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('cn-hangzhou');
$ossClient = new Oss\Client($cfg);

$client->putObject(
    new Oss\Models\PutObjectRequest(
        bucket: 'examplebucket',
        key: 'exampleobject.txt',
        body:  Oss\Utils::streamFor('example data'),
    ),
);

关于V2版基础API的更多示例代码，请参见对象/文件。

第五步：修改高级API调用方式（可选）

预签名接口

功能变更点

V2版本把预签名接口名称从sign_url修改为presign，接口形式如下：

public function presign(request: $request,args: $options): Models\PresignResult

对于request参数，其类型与API接口中的'<OperationName>Request' 一致。

对于返回结果，除了返回预签名URL外，还返回HTTP方法，过期时间和被签名的请求头，如下：

final class PresignResult
{
    public ?string $method;
    
    public ?string $url;
    
    public ?\DateTime $expiration;
    
    public ?array $signedHeaders;
}

关于V2版预签名接口的详细使用说明，请参考开发者指南-预签名接口。

代码示例

require_once 'vendor/autoload.php';
use OSS\OssClient;
$provider = new \OSS\Credentials\EnvironmentVariableCredentialsProvider();
$endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
$config = array(
    "provider" => $provider,
    "endpoint" => $endpoint,
    "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
    "region" => "cn-hangzhou"
);
$ossClient = new OssClient($config);
$url = $ossClient->signUrl('examplebucket','exampleobject.txt',60,OssClient::OSS_HTTP_GET);

printf("Sign Url:%s\n", $url);

require_once 'vendor/autoload.php';
use AlibabaCloud\Oss\V2 as Oss;

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('cn-hangzhou');
$ossClient = new Oss\Client($cfg);

$result = $ossClient->presign(
    new Oss\Models\GetObjectRequest(
        bucket: 'examplebucket',
        key: 'exampleobject.txt',
    ),
    args: ['expiration' => (new \DateTime('now', new \DateTimeZone('UTC')))->add(new DateInterval('PT60S'))],
);
print(
    'sign url:' . $result->url . PHP_EOL .
    'sign method :' . $result->method . PHP_EOL .
    'sign expiration:' . var_export($result->expiration, true) . PHP_EOL .
    'sign headers:' . var_export($result->signedHeaders, true) . PHP_EOL
);

关于V2版使用预签名URL上传文件的完整示例代码，请参见使用预签名URL上传。

关于V2版使用预签名URL下载文件的完整示例代码，请参见使用预签名URL下载。

文件传输管理器

变更点

V2版本使用传输管理器'Uploader'，'Downloader' 和'Copier'分别管理对象的上传，下载和拷贝。 关于V2版文件传输管理器的详细使用说明，请参考开发者指南-传输管理器。

代码示例

1. 文件上传管理器：

   ...
   $client = new Oss\Client($cfg);
   $u = $client->newUploader();
   $result = $u->uploadFile(
       new Oss\Models\PutObjectRequest(
           bucket: 'bucket',
           key: 'key'
       ),
       filepath: '/local/dir/example',
   );
   printf(
       'upload file status code:' . $result->statusCode . PHP_EOL .
       'upload file request id:' . $result->requestId . PHP_EOL .
       'upload file result:' . var_export($result, true) . PHP_EOL
   );

   关于V2版文件上传管理器的更多详细说明，请参见开发者指南-文件上传管理器。

   关于V2版文件上传管理器的完整示例代码，请参见文件上传管理器。

2. 文件下载管理器：

   ...
   $client = new Oss\Client($cfg);
   $d = $client->newDownloader();
   $d->downloadFile(
       new Oss\Models\GetObjectRequest(
           bucket: 'bucket',
           key: 'key'
       ),
       filepath: '/local/dir/example',
   );

   关于V2版文件下载管理器的更多详细说明，请参见开发者指南-文件下载管理器。

   关于V2版文件下载管理器的完整示例代码，请参见文件下载管理器。

3. 文件拷贝管理器：

   ...
   $client = new Oss\Client($cfg);
   $c = $client->newCopier();
   $result = $c->copy(
       new Oss\Models\CopyObjectRequest(
           bucket: 'bucket',
           key: 'key',
           sourceBucket: 'src-bucket',
           sourceKey: 'src-key',
       )
   );
   printf(
       'status code:' . $result->statusCode . PHP_EOL .
       'request id:' . $result->requestId . PHP_EOL .
       'result:' . var_export($result, true)
   );

   关于V2版文件拷贝管理器的更多详细说明，请参见开发者指南-文件拷贝管理器。

   关于V2版文件拷贝管理器的完整示例代码，请参见文件拷贝管理器。

第六步：测试和验证

1. 编写单元测试：

   为确保迁移后功能的正确性，您需要为每个迁移的功能编写详细的单元测试案例。这些测试应涵盖所有关键操作，并验证其行为与旧版SDK保持一致。重点包括：

   • 基础功能测试：如创建资源、查询状态、更新数据和删除资源等。

   • 边界条件测试：测试极端情况下的应用行为，例如处理极大或极小的数据集、异常输入等。

   • 错误处理测试：确保在出现错误时（如网络超时、无效输入），应用能够正确处理并给出合适的反馈。

2. 增量测试：

   采用增量式的方法进行迁移和测试，可以有效降低风险：

   • 选择一个小模块开始：先从一个相对独立且不复杂的小模块开始迁移，并为其编写完整的测试案例。

   • 进行全面测试：在确认该模块迁移成功且所有测试通过后，再逐步迁移到其他部分。这种方法有助于及时发现并解决问题，避免大规模回滚。

3. 兼容性测试：

   确保新版本SDK与您的整个技术栈及其他依赖项兼容至关重要：

   • 内部系统兼容性：验证新版本是否与现有的内部系统和架构兼容。

   • 第三方服务兼容性：如果您的应用依赖于第三方服务或API，请确保这些接口与V2 SDK兼容，并按照预期工作。

   • 环境兼容性：在不同的操作系统和运行环境中测试您的应用，确保V2 SDK在各种环境下都能正常运行。

4. 性能测试：

   在完成代码迁移后，必须对应用的性能进行全面评估：

   • 基准测试：建立性能基准，记录当前应用的响应时间、吞吐量等关键指标。

   • 对比分析：迁移完成后，使用相同的负载进行测试，比较新旧版本之间的性能差异，确保性能没有显著下降。

   • 调优：如果发现性能有所退步，可以通过调整配置参数、优化代码逻辑等方式进行改进。

V1与V2版本差异汇总

composer require aliyuncs/oss-sdk-php

composer require alibabacloud/oss-v2

相关文档

关于PHP SDK V1迁移到V2的更多详细内容，请参见开发者指南-迁移指南。