## 环境要求
1. Alipay Easy SDK for PHP 需要配合`PHP 7.0`或其以上版本。
2. 使用 Alipay Easy SDK for PHP 之前 ，您需要先前往[支付宝开发平台-开发者中心](https://openhome.alipay.com/platform/developerIndex.htm)完成开发者接入的一些准备工作，包括创建应用、为应用添加功能包、设置应用的接口加签方式等。
3. 准备工作完成后，注意保存如下信息，后续将作为使用SDK的输入。
* 加签模式为公钥证书模式时（推荐）
`AppId`、`应用的私钥`、`应用公钥证书文件`、`支付宝公钥证书文件`、`支付宝根证书文件`
* 加签模式为公钥模式时
`AppId`、`应用的私钥`、`支付宝公钥`
## [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E5%AE%89%E8%A3%85%E4%BE%9D%E8%B5%96)安装依赖
### [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E9%80%9A%E8%BF%87composer%E5%9C%A8%E7%BA%BF%E5%AE%89%E8%A3%85%E4%BE%9D%E8%B5%96%E6%8E%A8%E8%8D%90)通过[Composer](https://packagist.org/packages/alipaysdk/easysdk/)在线安装依赖（推荐）
`composer require alipaysdk/easysdk:^2.2`
### [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E6%9C%AC%E5%9C%B0%E6%89%8B%E5%8A%A8%E9%9B%86%E6%88%90%E4%BE%9D%E8%B5%96%E9%80%82%E7%94%A8%E4%BA%8E%E8%87%AA%E5%B7%B1%E4%BF%AE%E6%94%B9%E6%BA%90%E7%A0%81%E5%90%8E%E7%9A%84%E6%9C%AC%E5%9C%B0%E9%87%8D%E6%96%B0%E6%89%93%E5%8C%85%E5%AE%89%E8%A3%85)本地手动集成依赖（适用于自己修改源码后的本地重新打包安装）
1. 本机安装配置[Composer](https://getcomposer.org/)工具。
2. 在本`README.md`所在目录下，执行`composer install`，下载SDK依赖。
3. 依赖文件会下载到`vendor`目录下。
## [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E5%BF%AB%E9%80%9F%E4%BD%BF%E7%94%A8)快速使用
以下这段代码示例向您展示了使用Alipay Easy SDK for PHP调用一个API的3个主要步骤：
1. 设置参数（全局只需设置一次）。
2. 发起API调用。
3. 处理响应或异常。
~~~html
<?php
require 'vendor/autoload.php';
use Alipay\EasySDK\Kernel\Factory;
use Alipay\EasySDK\Kernel\Util\ResponseChecker;
use Alipay\EasySDK\Kernel\Config;
//1. 设置参数（全局只需设置一次）
Factory::setOptions(getOptions());
try {
//2. 发起API调用（以支付能力下的统一收单交易创建接口为例）
$result = Factory::payment()->common()->create("iPhone6 16G", "20200326235526001", "88.88", "2088002656718920");
$responseChecker = new ResponseChecker();
//3. 处理响应或异常
if ($responseChecker->success($result)) {
echo "调用成功". PHP_EOL;
} else {
echo "调用失败，原因：". $result->msg."，".$result->subMsg.PHP_EOL;
}
} catch (Exception $e) {
echo "调用失败，". $e->getMessage(). PHP_EOL;;
}
function getOptions()
{
$options = new Config();
$options->protocol = 'https';
$options->gatewayHost = 'openapi.alipay.com';
$options->signType = 'RSA2';
$options->appId = '<-- 请填写您的AppId，例如：2019022663440152 -->';
// 为避免私钥随源码泄露，推荐从文件中读取私钥字符串而不是写入源码中
$options->merchantPrivateKey = '<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->';
$options->alipayCertPath = '<-- 请填写您的支付宝公钥证书文件路径，例如：/foo/alipayCertPublicKey_RSA2.crt -->';
$options->alipayRootCertPath = '<-- 请填写您的支付宝根证书文件路径，例如：/foo/alipayRootCert.crt" -->';
$options->merchantCertPath = '<-- 请填写您的应用公钥证书文件路径，例如：/foo/appCertPublicKey_2019051064521003.crt -->';
//注：如果采用非证书模式，则无需赋值上面的三个证书路径，改为赋值如下的支付宝公钥字符串即可
// $options->alipayPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->';
//可设置异步通知接收服务地址（可选）
$options->notifyUrl = "<-- 请填写您的支付类接口异步通知接收服务地址，例如：https://www.test.com/callback -->";
//可设置AES密钥，调用AES加解密相关接口时需要（可选）
$options->encryptKey = "<-- 请填写您的AES密钥，例如：aa4BtZ4tspm2wnXLb1ThQA== -->";
return $options;
}
~~~
### [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E6%89%A9%E5%B1%95%E8%B0%83%E7%94%A8)扩展调用
#### [](https://github.com/alipay/alipay-easysdk/tree/master/php#isv%E4%BB%A3%E8%B0%83%E7%94%A8)ISV代调用
~~~html
Factory::payment()->faceToFace()
// 调用agent扩展方法，设置app_auth_token，完成ISV代调用
->agent("ca34ea491e7146cc87d25fca24c4cD11")
->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");
~~~
#### [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E8%AE%BE%E7%BD%AE%E7%8B%AC%E7%AB%8B%E7%9A%84%E5%BC%82%E6%AD%A5%E9%80%9A%E7%9F%A5%E5%9C%B0%E5%9D%80)设置独立的异步通知地址
~~~html
Factory::payment()->faceToFace()
// 调用asyncNotify扩展方法，可以为每此API调用，设置独立的异步通知地址
// 此处设置的异步通知地址的优先级高于全局Config中配置的异步通知地址
->asyncNotify("https://www.test.com/callback")
->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");
~~~
#### [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E8%AE%BE%E7%BD%AE%E5%8F%AF%E9%80%89%E4%B8%9A%E5%8A%A1%E5%8F%82%E6%95%B0)设置可选业务参数
~~~html
$goodDetail = array(
"goods_id" => "apple-01",
"goods_name" => "iPhone6 16G",
"quantity" => 1,
"price" => "5799"
);
$goodsDetail[0] = $goodDetail;
Factory::payment()->faceToFace()
// 调用optional扩展方法，完成可选业务参数（biz_content下的可选字段）的设置
->optional("seller_id", "2088102146225135")
->optional("discountable_amount", "8.88")
->optional("goods_detail", $goodsDetail)
->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");
$optionalArgs = array(
"timeout_express" => "10m",
"body" => "Iphone6 16G"
);
Factory::payment()->faceToFace()
// 也可以调用batchOptional扩展方法，批量设置可选业务参数（biz_content下的可选字段）
->batchOptional($optionalArgs)
->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");
~~~
#### [](https://github.com/alipay/alipay-easysdk/tree/master/php#%E5%A4%9A%E7%A7%8D%E6%89%A9%E5%B1%95%E7%81%B5%E6%B4%BB%E7%BB%84%E5%90%88)多种扩展灵活组合
~~~html
// 多种扩展方式可灵活组装（对扩展方法的调用顺序没有要求）
Factory::payment()->faceToFace()
->agent("ca34ea491e7146cc87d25fca24c4cD11")
->asyncNotify("https://www.test.com/callback")
->optional("seller_id", "2088102146225135")
->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");
~~~
## [](https://github.com/alipay/alipay-easysdk/tree/master/php#api%E7%BB%84%E7%BB%87%E8%A7%84%E8%8C%83)API组织规范
在Alipay Easy SDK中，API的引用路径与能力地图的组织层次一致，遵循如下规范
>[success] Factory::能力名称()->场景名称()->接口方法名称( ... )
比如，如果您想要使用[能力地图](https://opendocs.alipay.com/mini/00am3f)中`营销能力`下的`模板消息`场景中的`小程序发送模板消息`，只需按如下形式编写调用代码即可（不同编程语言的连接符号可能不同）。
`Factory::marketing()->templateMessage()->send( ... )`
其中，接口方法名称通常是对其依赖的OpenAPI功能的一个最简概况，接口方法的出入参与OpenAPI中同名参数含义一致，可参照OpenAPI相关参数的使用说明。
Alipay Easy SDK将致力于保持良好的API命名，以符合开发者的编程直觉。
