README

这是官方Bing Ads PHP SDK的替代品。

它受到了Google AdWords PHP SDK的很大启发，并有一些官方Bing SDK缺少的功能。

1. 无需SoapVar
2. 自动刷新访问令牌

它利用 league/oauth2-client 来处理oauth流程。

核心概念

• 会话 对象用于存储所有请求前的配置（oauth凭据、开发者令牌、API环境等）。
• 使用会话实例化一个服务，它扩展了SoapClient。服务用于向API发送实际请求。

使用示例

use PMG\BingAds\BingSession;
use PMG\BingAds\BingServices;
use PMG\BingAds\CustomerManagement as cm;

$session = BingSession::builder()
    ->withEnvironment(BingSession::PROD) // or use BingSession::SANDBOX
    ->withOAuthClientId('changeme')
    ->withOAuthClientSecret('changeme')
    ->withOAuthRedirectUri('https://yourapp.com/oauth/microsoft')
    ->withRefreshToken('someRefreshToken')
    ->withDeveloperToken('someDeveloperToken')
    ->build()
    ;

$services = new BingServices();

$service = $services->create(cm\CustomerManagementService::class, $session);

$response = $service->getCustomersInfo(new cm\GetCustomersInfoRequest('a', 10));
print_r($response);

错误处理

如果发生SOAP故障，它将被包装在PMG\BingAds\Exception\ApiException中。此异常可能特定于某个服务，也可能是通用的PMG\BingAds\Exception\SoapFault。

要查看实际的HTTP请求和响应，请在SOAP客户端选项中将trace设置为true。

use PMG\BingAds\BingSession;
use PMG\BingAds\BingServices;
use PMG\BingAds\CustomerManagement as cm;

$session = BingSession::builder()
    /* build a session as above */
    ->build()
    ;

$services = new BingServices();

$service = $services->create(cm\CustomerManagementService::class, $session, [
    'trace' => true,
]);

try {
    $response = $service->getCustomersInfo(new cm\GetCustomersInfoRequest('a', 10));
} catch (cm\ApplicationFault $fault) {
    echo $fault->getTrackingId(), PHP_EOL; // a UUID to help the bing team debug

    /** @var Psr\Http\Message\RequestInterface $request */
    $request = $fault->getRequest();
    if ($request) {
        // request will be there if `trace => true` otherwise this will be null
        // show the SOAP XML request. The credentials here (access token,
        // developer token) will be redacted
        echo $request->getBody(), PHP_EOL;
    }

    /** @var Psr\Http\Message\ResponseInterface $response */
    $response = $fault->getResponse();
    if ($response) {
        // respone will be there if `trace => true` otherwise it's null
        // display the SOAP XML response
        echo $response->getBody(), PHP_EOL;
    }

    // show actual errors
    if ($fault instanceof cm\ApiFault) {
        print_r($fault->getOperationErrors());
    } elseif ($fault instanceof cm\AdApiFault) {
        print_r($fault->getErrors());
    }
}

或者，每个服务都提供lastRequest和lastResponse方法来查看HTTP请求/响应。

use PMG\BingAds\BingSession;
use PMG\BingAds\BingServices;
use PMG\BingAds\CustomerManagement as cm;

$session = BingSession::builder()
    /* build a session as above */
    ->build()
    ;

$services = new BingServices();

$service = $services->create(cm\CustomerManagementService::class, $session, [
    'trace' => true,
]);

$response = $service->getCustomersInfo(new cm\GetCustomersInfoRequest('a', 10));

print_r($service->lastRequest());
print_r($service->lastResponse());

身份验证

请参阅examples/auth中的示例。

实例化一个PMG\BingAds\Auth\MicrosoftProvider，并像使用任何其他oauth2-client提供者一样使用它。

use PMG\BingAds\Auth\MicrosoftProvider;

$provider = MicrosoftProvider::production([
    'clientId' => 'changeme',
    'clientSecret' => 'changeme',
    'redirectUri' => 'https://youramp.com/oauth/microsft',
]);

// get an authorization URL
$authurl = $provider->getAuthorizationUrl(['prompt' => 'login']);
// may want to $pvodier->getState() to save the state some place

// exchange a `code` for an access token
$token = $provider->getAccessToken('authorization_code', [
    'code' => $_GET['code'],
]);