README

Webmarketer 的 PHP SDK

Webmarketer (app.webmarketer.io) 的官方 PHP SDK。

安装

要添加此包，您的项目必须满足几个要求

• PHP >= 5.6
• Composer (安装 composer)
• PHP 的 OpenSSL 扩展

此包是 核心 SDK，并且不随任何特定的 HTTP 库一起安装。它使用 PSR-7 实现 Httplug，可与任何 PSR-7 兼容的客户端一起使用。如果您不知道使用哪个，我们建议使用 Guzzle（您只需在项目中引入它）。

composer require webmarketer/webmarketer-php

用法

基本示例

try {
    // create an instance of the SDK with the desired configuration
    $client = new \Webmarketer\WebmarketerSdk([
        'default_project_id' => 'webmarketer-awesome-project'
    ]);
} catch (\Webmarketer\Exception\DependencyException $dep_ex) {
    // SDK init throw a dependency exception if requirements are not meet (see Install)
} catch (\Webmarketer\Exception\CredentialException $cred_ex) {
    // SDK automatically try to authenticate you agains API
    // A credential exception could be throw if credentials are invalid
}

// SDK exposes resources services, use them to manipulate your resources
$event_type_service = $client->getEventTypeService();
$field_service = $client->getFieldService();

认证

SDK 提供了认证提供程序，让您可以选择如何对 Webmarketer API 进行认证

服务帐户提供程序

如果没有手动指定提供程序，SDK 将使用默认的认证方法。
无 任何配置 的情况下，SDK 将尝试在名为 WEBMARKETER_APPLICATION_CREDENTIALS 的环境变量指定的位置检索服务帐户文件。

示例

• 我的 Webmarketer 服务帐户位于服务器上的以下路径： /secrets/webmarketer/sa.json
• 我在服务器上设置了环境变量： WEBMARKETER_APPLICATION_CREDENTIALS=/secrets/webmarketer/sa.json
• 我无需指定认证提供程序，因为 SDK 将自动使用我的服务帐户进行认证

还可以通过将 ServiceAccountAuthProvider 手动传递给 SDK 来指定字符串化的 JSON sa

try {
    $sa_auth_provider = new \Webmarketer\Auth\ServiceAccountAuthProvider([
       // stringified service account
       'credential' => '{ ...serviceAccount }',
       // desired scopes, space separated
       'scopes' => 'full_access'
    ]);
    // create an instance of the SDK with the custom auth provider
    $client = new \Webmarketer\WebmarketerSdk(
        [
            'default_project_id' => 'webmarketer-awesome-project'
        ],
        $sa_auth_provider
    );
} catch (\Webmarketer\Exception\DependencyException $dep_ex) {
    // SDK init throw a dependency exception if requirements are not meet (see Install)
} catch (\Webmarketer\Exception\CredentialException $cred_ex) {
    // SDK automatically try to authenticate you agains API
    // A credential exception could be throw if credentials are invalid
}

刷新令牌提供程序

刷新令牌认证提供程序允许您使用个人刷新令牌对 API 进行认证。您只需使用 RefreshTokenAuthProvider 实例化 Webmarketer SDK。

try {
    $refresh_token_auth_provider = new \Webmarketer\Auth\RefreshTokenAuthProvider([
       // oauth application client_id
       'client_id' => 'appclientid',
       // oauth application client_secret
       'client_secret' => 'appclientsecret',
       // refresh token
       'refresh_token' => 'myrefreshtoken'
    ]);
    // create an instance of the SDK with the custom auth provider (this time the refresh_token_auth_provider)
    $client = new \Webmarketer\WebmarketerSdk(
        [
            'default_project_id' => 'webmarketer-awesome-project'
        ],
        $refresh_token_auth_provider
    );
    // perform an exchange of the refresh flow to get an access token as well as a new refresh token
    $response = $client->getAuthProvider()->refreshToken();
    // new refresh token can be securely stored for future use
    $new_refresh_token = $response['refresh_token'];
} catch (\Webmarketer\Exception\DependencyException $dep_ex) {
    // SDK init throw a dependency exception if requirements are not meet (see Install)
} catch (\Webmarketer\Exception\CredentialException $cred_ex) {
    // SDK automatically try to authenticate you agains API
    // A credential exception could be throw if credentials are invalid
}

官方集成

以下集成是由 Webmarketer 团队开发和维护的，并基于此 SDK。

• WordPress 插件

贡献

所有 SDK 依赖项都通过 Composer 管理

composer install

使用提供的配置运行所有测试用 PHPUnit

composer tests

使用 PHPUnit 运行所有测试并检查代码覆盖率（必须 >= 80%）

composer tests-coverage

代码审查

composer phpcs

Docker

如果您想在容器中运行 SDK，它包含一些 Docker 配置

• Dockerfile（Linux Alpine with PHP 5.6 and composer）
• Dockerfile-8（Linux Alpine with PHP 8.0.10 and composer）
• docker-compose.yml 有一个名为 PHP 的服务来运行命令，使用所需的镜像（5.6 或 8.0.10）。更新使用的 Dockerfile 在两者之间，以运行 5.6 或 8.0.10

  docker-compose run php composer tests

请随时在此存储库中报告问题。

资源

• 应用
• 官方文档
• 官方网站