chartmogul/chartmogul-php

ChartMogul API PHP 客户端

维护者

详细信息

github.com/chartmogul/chartmogul-php

源代码

问题

安装: 974 225

依赖项: 0

建议者: 0

安全: 0

星标: 18

关注者: 35

分支: 19

开放性问题: 3

v6.3.2 2024-07-03 07:44 UTC

Requires

Requires (Dev)

MIT fd0f48924a3ef46b815509053152d5fadb3d1229

  • ChartMogul Ltd. <support.woop@chartmogul.com>
  • Mahmudul Hassan <hassan.woop@chartmogul.com>

This package is auto-updated.

Last update: 2024-09-03 08:07:30 UTC

README

官方 ChartMogul API PHP 客户端

chartmogul-php 为 ChartMogul 的 API 提供便捷的 PHP 绑定。

Build Status

安装 | 配置 | 使用 | 开发 | 贡献 | 许可证


安装

此库需要 php 5.5 或更高版本。

对于旧版本的 php（< 7.4），使用此库的 1.x.x 版本。

对于 php 版本 >=7.4，使用库的最新版本（5.x.x）。

该库不依赖于任何具体的 HTTP 客户端库。请参阅此处的说明，了解如何包含 HTTP 客户端。

以下是一个使用 Guzzle HTTP 客户端 的示例

composer require chartmogul/chartmogul-php:^5.0 php-http/guzzle6-adapter:^2.0.1 http-interop/http-factory-guzzle:^1.0

配置

使用您的 ChartMogul API 密钥设置默认配置

require('./vendor/autoload.php');

ChartMogul\Configuration::getDefaultConfiguration()
    ->setApiKey('<YOUR_API_KEY>');

测试您的身份验证

print_r(ChartMogul\Ping::ping()->data);

使用

try {
  $dataSources = ChartMogul\DataSource::all();
} catch(\ChartMogul\Exceptions\ForbiddenException $e){
  // handle authentication exception
} catch(\ChartMogul\Exceptions\ChartMogulException $e){
    echo $e->getResponse();
    echo $e->getStatusCode();
}

$ds = $dataSources->first();
var_dump($ds->uuid); // access Datasource properties
$dsAsArray = $ds->toArray(); // convert to array
$ds->destroy();

所有数组结果都通过 Doctrine\Common\Collections\ArrayCollection 包装，以便于访问。请参阅异常，了解此库抛出的异常列表。

导入 API 中的可用方法

数据源

创建数据源

$ds = ChartMogul\DataSource::create([
  'name' => 'In-house Billing'
]);

获取一个数据源

ChartMogul\DataSource::retrieve($uuid);

列出数据源

ChartMogul\DataSource::all();

删除一个数据源

$dataSources = ChartMogul\DataSource::all();
$ds = $dataSources->last();
$ds->destroy();

客户

导入客户

ChartMogul\Customer::create([
    "data_source_uuid" => $ds->uuid,
    "external_id" => "cus_0003",
    "name" => "Adam Smith",
    "email" => "adam@smith.com",
    "country" => "US",
    "city" => "New York",
    "lead_created_at" => "2016-10-01T00:00:00.000Z",
    "free_trial_started_at" => "2016-11-02T00:00:00.000Z"
]);

列出客户

ChartMogul\Customer::all([
  'page' => 1,
  'data_source_uuid' => $ds->uuid
]);

通过外部 ID 查找客户

ChartMogul\Customer::findByExternalId([
    "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id" => "cus_0001"
]);

删除客户

$cus = ChartMogul\Customer::all()->last();
$cus->destroy();

获取客户

ChartMogul\Customer::retrieve($uuid);

搜索客户

ChartMogul\Customer::search('adam@smith.com');

合并客户

ChartMogul\Customer::merge([
    'customer_uuid' => $cus1->uuid
], [
    'customer_uuid' => $cus2->uuid
]);

// alternatively:
ChartMogul\Customer::merge([
    'external_id' => $cus1->external_id,
    'data_source_uuid' => $ds->uuid
        ], [
    'external_id' => $cus2->external_id,
    'data_source_uuid' => $ds->uuid
]);

更新客户

$result = ChartMogul\Customer::update([
    'customer_uuid' => $cus1->uuid
        ], [
    'name' => 'New Name'
]);

连接订阅

ChartMogul\Customer::connectSubscriptions("cus_5915ee5a-babd-406b-b8ce-d207133fb4cb", [
    "subscriptions" => [
        [
            "data_source_uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
            "external_id" => "d1c0c885-add0-48db-8fa9-0bdf5017d6b0",
        ],
        [
            "data_source_uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
            "external_id" => "9db5f4a1-1695-44c0-8bd4-de7ce4d0f1d4",
        ],
    ]
]);

或

$subscription1->connect("cus_5915ee5a-babd-406b-b8ce-d207133fb4cb", $subscriptions);

客户属性

检索客户的属性

$customer = ChartMogul\Customer::retrieve($cus->uuid);
$customer->attributes;

标签

向客户添加标签

$customer = ChartMogul\Customer::retrieve($cus->uuid);
$tags = $customer->addTags("important", "Prio1");

向具有电子邮件的客户添加标签

$customers = ChartMogul\Customer::search('adam@smith.com');

foreach ($customers->entries as $customer) {
    $customer->addTags('foo', 'bar', 'baz');
}

从客户中删除标签

$customer = ChartMogul\Customer::retrieve($cus->uuid);
$tags = $customer->removeTags("important", "Prio1");

自定义属性

向客户添加自定义属性

$customer = ChartMogul\Customer::retrieve($cus->uuid);
$custom = $customer->addCustomAttributes(
    ['type' => 'String', 'key' => 'channel', 'value' => 'Facebook'],
    ['type' => 'Integer', 'key' => 'age', 'value' => 8 ]
);

向具有电子邮件的客户添加自定义属性

$customers = ChartMogul\Customer::search('adam@smith.com');

foreach ($customers->entries as $customer) {
    $customer->addCustomAttributes(
        ['type' => 'String', 'key' => 'channel', 'value' => 'Facebook'],
        ['type' => 'Integer', 'key' => 'age', 'value' => 8 ]
    );
}

更新客户的自定义属性

$customer = ChartMogul\Customer::retrieve($cus->uuid);
$custom = $customer->updateCustomAttributes(
    ['channel' => 'Twitter'],
    ['age' => 18]
);

从客户中删除自定义属性

$customer = ChartMogul\Customer::retrieve($cus->uuid);
$tags = $customer->removeCustomAttributes("age", "channel");

从客户中列出联系人

$customer = ChartMogul\Customer::retrieve($uuid);
$contacts = $customer->contacts([
  'cursor' => 'aabbccdd...'
]);

从客户中创建联系人

$customer = ChartMogul\Customer::retrieve($uuid);
$new_customer = $customer->createContact([
  "data_source_uuid" => "ds_00000000-0000-0000-0000-000000000000",
  "first_name" => "Adam",
  "last_name" => "Smith",
]);

从客户中列出客户备注

$customer = ChartMogul\Customer::retrieve($uuid);
$customer_notes = $customer->notes([
  'cursor' => 'aabbccdd...'
]);

从客户中创建客户备注

$customer = ChartMogul\Customer::retrieve($uuid);
$new_customer_note = $customer->createNote([
  'type' => 'note',
  'text' => 'This is a note'
]);

从客户中列出机会

$customer = ChartMogul\Customer::retrieve($uuid);
$opportunities = $customer->opportunities([
  'cursor' => 'aabbccdd...'
]);

从客户中创建机会

$customer = ChartMogul\Customer::retrieve($uuid);
$new_opportunity = $customer->createOpportunity([
  'owner' => 'owner@example.com',
  'pipeline' => 'Sales',
  'pipeline_stage' => 'Qualified',
  'estimated_close_date' => '2022-03-30',
  'currency' => 'USD',
  'amount_in_cents' => 10000,
  'type' => 'one-time',
  'forecast_category' => 'Best Case',
  'win_likelihood' => 80,
  'custom' => [{key: 'custom_key', value: 'custom_value'}]
]);

客户备注

列出客户备注

$customer_notes = ChartMogul\CustomerNote::all([
    'customer_uuid' => $uuid,
    'cursor' => 'aabbccdd...'
])

创建客户备注

$customer_note = ChartMogul\CustomerNote::create([
    'customer_uuid': $uuid,
    'type' => 'note',
    'text' => 'This is a note'
])

获取客户备注

$customer_note = ChartMogul\CustomerNote::retrieve($note_uuid)

更新客户备注

$updated_customer_note = ChartMogul\CustomerNote::update($note_uuid, [
  'text' => 'This is a new note'
]);

删除客户备注

$customer_note = ChartMogul\CustomerNote::retrieve($note_uuid)
$customer_note->destroy();

联系人

列出联系人

$contacts = ChartMogul\Contacts::all([
  'cursor' => 'aabbccdd...'
]);

创建联系人

$new_contact = ChartMogul\Contact::create([
  "customer_uuid" => "cus_00000000-0000-0000-0000-000000000000",
  "data_source_uuid" => "ds_00000000-0000-0000-0000-000000000000",
  "first_name" => "Adam",
  "last_name" => "Smith",
]);

获取联系人

$contact = ChartMogul\Contact::retrieve($uuid);

删除联系人

$contact = ChartMogul\Contact::retrieve($uuid);
$contact->destroy();

更新联系人

$updated_contact = ChartMogul\Contact::update([
    'contact_uuid' => $uuid
        ], [
    'first_name' => 'New Name'
]);

合并联系人

$merged_contact = ChartMogul\Contact::merge($into_contact_uuid, $from_contact_uuid);

机会

列出机会

$opportunities = ChartMogul\Opportunity::all([
    'cursor' => 'aabbccdd...'
])

创建机会

$opportunity = ChartMogul\Opportunity::create([
    'customer_uuid' => $uuid,
    'owner' => 'test1@example.org',
    'pipeline' => 'New business 1',
    'pipeline_stage' => 'Discovery',
    'estimated_close_date' => '2023-12-22',
    'currency' => 'USD',
    'amount_in_cents' => 100,
    'type' => 'recurring',
    'forecast_category' => 'pipeline',
    'win_likelihood' => 3,
    'custom' => [{ 'key': 'from_campaign', 'value': true }]
])

获取机会

$opportunity = ChartMogul\Opportunity::retrieve($opportunity_uuid)

更新机会

$updated_opportunity = ChartMogul\Opportunity::update($opportunity_uuid, [
  'estimated_close_date' => '2024-12-22',
]);

删除机会

$opportunity = ChartMogul\Opportunity::retrieve($opportunity_uuid)
$opportunity->destroy();

计划

导入计划

ChartMogul\Plan::create([
    "data_source_uuid" => $ds->uuid,
    "name" => "Bronze Plan",
    "interval_count" => 1,
    "interval_unit" => "month",
    "external_id" => "plan_0001"
]);

通过 UUID 获取计划

ChartMogul\Plan::retrieve($uuid);

列出计划

$plans = ChartMogul\Plan::all([
  'page' => 1
]);

删除计划

$plan = ChartMogul\Plan::all()->last();
$plan->destroy();

更新计划

$plan = ChartMogul\Plan::update(["plan_uuid" => $plan->uuid], [
            "name" => "Bronze Monthly Plan",
            "interval_count" => 1,
            "interval_unit" => "month"
]);

订阅事件

列出订阅事件

$subscription_events = ChartMogul\SubscriptionEvent::all();

创建订阅事件

ChartMogul\SubscriptionEvent::create(['subscription_event' => [
    "external_id" => "evnt_026",
    "customer_external_id" => "cus_0003",
    "data_source_uuid" => $ds->uuid,
    "event_type" => "subscription_start_scheduled",
    "event_date" => "2022-03-30",
    "effective_date" => "2022-04-01",
    "subscription_external_id" => "sub_0001",
    "plan_external_id" => "plan_0001",
    "currency" => "USD",
    "amount_in_cents" => 1000
    "quantity" => 1
]]);

删除订阅事件

ChartMogul\SubscriptionEvent::destroyWithParams(['subscription_event' => [
    "id" => "some_event_id"
]]);

更新订阅事件

ChartMogul\SubscriptionEvent::updateWithParams(['subscription_event' => [
    "id" => "some_event_id",
    "currency" => "EUR",
    "amount_in_cents" => "100"
]]);

计划分组

创建计划分组

ChartMogul\PlanGroup::create([
    "name" => "Bronze Plan",
    "plans" => [$plan_uuid_1, $plan_uuid_2],
]);

通过UUID获取计划分组

ChartMogul\PlanGroup::retrieve($uuid);

列出计划分组

$plan_groups = ChartMogul\PlanGroup::all([
  'page' => 1
]);

删除计划分组

$plan_group = ChartMogul\PlanGroup::all()->last();
$plan_group->destroy();

更新计划分组

$plan_group = ChartMogul\PlanGroup::update(
  ["plan_group_uuid" => $plan_group->uuid],
  [
  "name" => "A new plan group name",
  "plans" => [$plan_uuid_1, $plan_uuid_2]
]);

列出计划分组内的计划

$plan_group_plans = ChartMogul\PlanGroups\Plan::all(
  ["plan_group_uuid" => $plan_group->uuid]
);

发票

导入发票

$plan = ChartMogul\Plan::all()->first();
$cus = ChartMogul\Customer::all()->first();

$line_item_1 = new ChartMogul\LineItems\Subscription([
    'subscription_external_id' => "sub_0001",
    'subscription_set_external_id' => 'set_0001',
    'plan_uuid' =>  $plan->uuid,
    'service_period_start' =>  "2015-11-01 00:00:00",
    'service_period_end' =>  "2015-12-01 00:00:00",
    'amount_in_cents' => 5000,
    'quantity' => 1,
    'discount_code' => "PSO86",
    'discount_amount_in_cents' => 1000,
    'tax_amount_in_cents' => 900,
    'transaction_fees_currency' => "EUR",
    'discount_description' => "5 EUR"
]);

$line_item_2 = new ChartMogul\LineItems\OneTime([
    "description" => "Setup Fees",
    "amount_in_cents" => 2500,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 500,
    "tax_amount_in_cents" => 450,
    "transaction_fees_currency" => "EUR",
    "discount_description" => "2 EUR"
]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2015-11-05T00:14:23.000Z",
    "result" => "successful"
]);

$invoice = new ChartMogul\Invoice([
    'external_id' => 'INV0001',
    'date' =>  "2015-11-01 00:00:00",
    'currency' => 'USD',
    'due_date' => "2015-11-15 00:00:00",
    'line_items' => [$line_item_1, $line_item_2],
    'transactions' => [$transaction]
]);

$ci = ChartMogul\CustomerInvoices::create([
    'customer_uuid' => $cus->uuid,
    'invoices' => [$invoice]
]);

列出客户发票

$ci = ChartMogul\CustomerInvoices::all([
    'customer_uuid' => $cus->uuid,
    'page' => 1,
    'per_page' => 200
]);

列出发票

$invoices = ChartMogul\Invoice::all([
    'external_id' => 'my_invoice',
    'page' => 1,
    'per_page' => 200
]);

检索发票

$invoice = ChartMogul\Invoice::retrieve('inv_uuid');

交易

创建交易

ChartMogul\Transactions\Refund::create([
    "invoice_uuid" => $ci->invoices[0]->uuid,
    "date" => "2015-12-25 18:10:00",
    "result" => "successful"
]);

这也可以通过Payment类来完成。

订阅

列出客户订阅

$subscriptions = $cus->subscriptions();

取消客户订阅

$subscription = new ChartMogul\Subscription(["uuid" => $subsUUID])
// or use some existing instance of subsctiption, eg. fetched from Customer->subscriptions
$canceldate = '2016-01-01T10:00:00.000Z';
$subscription->cancel($canceldate);

或设置取消日期

$subscription = new ChartMogul\Subscription(["uuid" => $subsUUID])
$cancellationDates = ['2016-01-01T10:00:00.000Z', '2017-01-01T10:00:00.000Z']
$subscription->setCancellationDates($cancellationDates)

指标API

检索所有关键指标

ChartMogul\Metrics::all([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
    'interval' => 'month',
    'geo' => 'GB',
    'plans' => $plan->name
]);

检索MRR

ChartMogul\Metrics::mrr([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
    'interval' => 'month',
    'geo' => 'GB',
    'plans' => $plan->name
]);

检索ARR

ChartMogul\Metrics::arr([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
    'interval' => 'month'
]);

检索平均收入账户（ARPA）

ChartMogul\Metrics::arpa([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
    'interval' => 'month'
]);

检索平均销售价格（ASP）

ChartMogul\Metrics::asp([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
    'interval' => 'month',
]);

检索客户数量

ChartMogul\Metrics::customerCount([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
    'interval' => 'month',
]);

检索客户流失率

ChartMogul\Metrics::customerChurnRate([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
]);

检索MRR流失率

ChartMogul\Metrics::mrrChurnRate([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
]);

检索LTV

ChartMogul\Metrics::ltv([
    'start-date' => '2015-01-01',
    'end-date' => '2015-11-24',
]);

列出客户订阅

ChartMogul\Metrics\Customers\Subscriptions::all([
    "customer_uuid" => $cus->uuid
]);

列出客户活动

ChartMogul\Metrics\Customers\Activities::all([
    "customer_uuid" => $cus->uuid
]);

列出活动

ChartMogul\Metrics\Activities::all([
    'start-date' => '2020-06-02T00:00:00Z',
    'per-page' => 100
]);

**Create an Activities Export**

```php
ChartMogul\Metrics\ActivitiesExport::create([
    'start-date' => '2020-06-02T00:00:00Z',
    'end-date' =>  '2021-06-02T00:00:00Z'
    'type' => 'churn'
]);

检索活动导出

$id = '7f554dba-4a41-4cb2-9790-2045e4c3a5b1';
ChartMogul\Metrics\ActivitiesExport::retrieve($id);

账户

检索账户详情

ChartMogul\Account::retrieve();

异常

库会抛出以下异常

  • ChartMogul\Exceptions\ChartMogulException
  • ChartMogul\Exceptions\ConfigurationException
  • ChartMogul\Exceptions\ForbiddenException
  • ChartMogul\Exceptions\NotFoundException
  • ChartMogul\Exceptions\ResourceInvalidException
  • ChartMogul\Exceptions\SchemaInvalidException

以下表格描述了错误对象的公共方法。

速率限制与指数退避

如果请求超过速率限制或出现任何网络相关错误，库将不断重试。默认情况下，请求将在20次（约15分钟）重试后放弃。

您可以使用Configuration对象更改重试次数

ChartMogul\Configuration::getDefaultConfiguration()
    ->setApiKey('<YOUR_API_KEY>')
    ->setRetries(15); //0 disables retrying

开发

您需要本地安装Docker才能使用我们的Makefile工作流程。

  • 分叉它。
  • 创建您的功能分支（git checkout -b my-new-feature）。
  • 安装依赖项：make build。
  • 使用make composer install安装Composer供应商依赖项
  • 为您的新功能编写测试。运行测试并使用make test检查测试覆盖率。
  • 要运行任何Composer命令或PHP脚本，请使用make composer <commands>或make php <script>。
  • 如果所有测试都通过，请推送到分支（git push origin my-new-feature）。
  • 创建一个新的Pull Request。

贡献

欢迎在GitHub上提交错误报告和Pull Request：https://github.com/chartmogul/chartmogul-php。

许可

该库根据MIT许可条款作为开源软件提供。

MIT许可（MIT）

版权所有 (c) 2019 ChartMogul Ltd。

特此授予任何获得此软件及其相关文档副本（“软件”）的人免费使用权，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许获得软件的人进行上述操作，前提是受以下条件的约束

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

本软件按照“现状”提供，不提供任何形式的质量保证，无论是明确的还是隐含的，包括但不限于关于适用性、特定目的的适用性和非侵权的保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该责任源于合同行为、侵权行为或其他原因，以及与软件、软件的使用或其他与软件相关的行为有关。