README

此库抽象了与PBS会员金库API的交互。

安装

使用composer安装

composer require openpublicmedia/pbs-membership-vault-php

使用

此库提供的主要类是OpenPublicMedia\PbsMembershipVault\Client。可以使用Client实例以各种方式与会员数据交互。

响应数据结构

从Client类返回的响应在查询多个会员（例如使用getMemberships）时将返回生成器，在查询特定会员记录（例如使用getMembershipById($id)）时将返回单个stdClass对象。

示例

创建客户端

use OpenPublicMedia\PbsMembershipVault\Client;

$api_key = 'xxxxxxxxxxxxxx';
$api_secret = 'xxxxxxxxxxx';
$station_id = 'xxxxxxxxxxx';

$client = new Client($api_key, $api_secret, $station_id);

通过ID获取会员资格

$id = 'xxxxxxxxxxx';
$membership = $client->getMembershipById($id);
var_dump($membership);
class stdClass#34 (18) {
  public $grace_period => string
  public $update_date => string
  public $first_name => string
  public $last_name => string
  public $create_date => string
  public $offer => string
  public $notes => string
  public $current_state =>
  class stdClass#28 (2) {
    public $explanation =>
    class stdClass#35 (3) {
      public $status => string
      public $timing => string
      public $token_activated bool
    }
    public $has_access => bool
  }
  public $membership_id => string
  public $start_date => string
  public $status => string
  public $token => string
  public $additional_metadata => string
  public $activation_date => string
  public $provisional => bool
  public $expire_date => string
  public $pbs_profile =>
  class stdClass#24 (7) {
    public $first_name => string
    public $last_name => string
    public $UID => string
    public $birth_date => string
    public $retrieval_status =>
    class stdClass#23 (2) {
      public $status => int
      public $message => string
    }
    public $email => string
    public $login_provider => string
  }
  public $email => string
}

获取所有已激活的会员资格

$memberships = $client->getActivatedMemberships();
var_dump(count($memberships));
int(51763)
foreach ($memberships as $membership) {
    var_dump($membership);
    class stdClass#29 (18) {...}
}

添加新的会员资格

$start_date = new DateTime();
$expire_date = clone($start_date);
$expire_date->add(new DateInterval('P1Y'));

$membership = $client->addMembership(
    'membership_id',
    'first_name',
    'last_name',
    'offer',
    $start_date
    $expire_date
);

var_dump($membership);
class stdClass#29 (18) {...}

更新现有会员资格

$membership_id = 'xxxxxxxx';

$membership = $client->getMembershipById($membership_id);
var_dump($membership->notes);
string(0) ""

$result = $client->updateMembership($membership_id, ['notes' => 'Updated notes']);
var_dump($result);
bool(true)

$membership = $client->getMembershipById($membership_id);
var_dump($membership->notes);
string(13) "Updated notes"

处理异常

大多数Client方法可以抛出OpenPublicMedia\PbsMembershipVault\Exception\BadRequestException。此异常将包含一个JSON编码的消息，可用于确定后续操作。

$start_date = new DateTime();
$expire_date = clone($start_date);
$expire_date->add(new DateInterval('P1Y'));

try {
    $membership = $client->addMembership(
        'membership_id',
        '',
        '',
        'offer',
        $start_date,
        $end_date
    );
} catch (BadRequestException $e) {
    $errors = json_decode($e->getMessage());
    var_dump($errors);
    class stdClass#31 (2) {
      public $first_name =>
      array(1) {
        [0] =>
        string(23) "This field is required."
      }
      public $last_name =>
      array(1) {
        [0] =>
        string(23) "This field is required."
      }
    }
}

异常OpenPublicMedia\PbsMembershipVault\Exception\MembershipNotFoundException表示未找到具有提供的ID的会员资格。

$membership_id = 'does_not_exist';
try {
    $membership = $client->getMembershipById($membership_id);
} catch (MembershipNotFoundException $e) {
    $response = json_decode($e->getMessage());
    var_dump($response);
    class stdClass#29 (2) {
      public $type =>
      string(2) "id"
      public $value =>
      string(17) "does_not_exist"
    }
}

异常\OpenPublicMedia\PbsMembershipVault\Exception\MembershipActivatedException表示会员资格已被除请求的PBS账户以外的其他PBS账户激活。

$membership_id = 'ALREADY_ACTIVATED';
$uid = '11111111-2222-3333-4444-555555555555'
try {
    $membership = $client->activateMembership($membership_id, $uid);
} catch (MembershipActivatedException $e) {
    $response = json_decode($e->getMessage());
    var_dump($response);
    object(stdClass)#31 (3) {
      ["message"]=>
      string(101) "The membership ALREADY_ACTIVATED was already activated with UID 11111111-2222-3333-4444-555555555555"
      ["id"]=>
      string(18) "ALREADY_ACTIVATED"
      ["uid"]=>
      string(36) "11111111-2222-3333-4444-555555555555"
    }
    var_dump($e->getMembershipId());
    string(18) "ALREADY_ACTIVATED"
    var_dump($e->getPbsAccountUid());
    string(36) "11111111-2222-3333-4444-555555555555"

}

异常\OpenPublicMedia\PbsMembershipVault\Exception\AnotherMembershipActivatedException表示PBS账户已激活不同的会员资格。

$membership_id = '0123456789ABCDEF';
$uid = '11111111-2222-3333-4444-555555555555'
try {
    $membership = $client->activateMembership($membership_id, $uid);
} catch (MembershipActivatedException $e) {
    $response = json_decode($e->getMessage());
    var_dump($response);
    object(stdClass)#31 (3) {
      ["message"]=>
      string(96) "The UID 11111111-2222-3333-4444-555555555555 has already activated membership 0123456789ABCDEF"
      ["id"]=>
      string(18) "0123456789ABCDEF"
      ["uid"]=>
      string(36) "11111111-2222-3333-4444-555555555555"
    }
    var_dump($e->getMembershipId());
    string(18) "0123456789ABCDEF"
    var_dump($e->getPbsAccountUid());
    string(36) "11111111-2222-3333-4444-555555555555"

}

开发目标

有关向此项目贡献的信息，请参阅CONTRIBUTING。

v1

API身份验证（OpenPublicMedia\PbsMembershipVault\Client）
API直接查询（$client->request()）
结果/错误处理
透明分页响应处理（OpenPublicMedia\PbsMembershipVault\Response\PagedResponse）
会员资格
- 会员资格：get
- 会员资格：list_token（此“list”端点返回单个结果）
- 会员资格：put
- 会员资格：update（PATCH）
- 会员资格：delete
会员资格
- 会员资格：list
- 会员资格：last_updated_since
- 会员资格：active？
- 会员资格：email
- 会员资格：deleted
- 会员资格：deleted？since
- 会员资格：list_activated
- 会员资格：list_activated/?since
- 会员资格：list_provisional
- 会员资格：list_provisional/?since
- 会员资格：list_grace_period
- 会员资格：list_uid
示例/详细文档

v2

PHP 8支持

v3.x

会员实体（用于替换stdClass）
改进了API错误响应的处理
特别改进了激活的处理
通过MVault ID获取会员资格

openpublicmedia / pbs-membership-vault-php

维护者

详细信息