README

civicrm-api是一个Composer包，允许开发者通过CiviCRM中的REST API v4功能与CiviCRM实例交互。

此代码旨在在CiviCRM部署环境之外使用。因此，代码库遵循PSR-12编码标准，而不是Drupal/Wordpress/CiviCRM编码标准。

安装

要安装库，请运行以下命令

composer require circle-interactive/civicrm-api

要求

CiviCRM服务器必须运行在v5.47或更高版本。

在本版本中，/civicrm/ajax/*端点被作为Web服务公开，这是目前正在进行的工作的一部分，旨在通过标准CiviCRM路由系统公开REST端点。点击这里了解更多信息。

您的应用程序必须使用符合PSR-18的HTTP客户端。

如果您的应用程序使用不符合PSR-18的HTTP客户端，则需要编写一个实现sendRequest方法的装饰器类。

如何使用

注意：如您从示例中看到的，此库不会反序列化响应。这是设计上的。

调用代码负责响应反序列化和处理响应中的数据。

Guzzle示例

<?php

declare(strict_types=1);

// Require Composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Define the desired type of authentication and key
$authType = \Circle\CiviCRM\AuthenticationTypes::BEARER_API_KEY;
$authKey = 'MYKEYGOESHERE'; // best practices dictate using an environment variable here!

// Configure Guzzle to point at the root URL for the CiviCRM site
// note we DO NOT include the /civicrm section of the URI in the base_uri field
$guzzleOptions = ['base_uri' => 'https://my.civicrm.site']; 
// Instantiate a new Guzzle client
$guzzleClient = new GuzzleHttp\Client($guzzleOptions);

// Instantiate a new CiviCRM API client, passing the Guzzle client as a parameter
$civicrm = new \Circle\CiviCRM\Client($guzzleClient, $authType, $authKey);

// Make request to retrieve all Contacts
$contactsResponse = $civicrm->get('Contact');
// Note that the full API response object is returned to the caller
$contactsJson = $contactsResponse->getBody()->getContents();
// Decode the response
$contacts = json_decode($contactsJson, TRUE);
$contactsArray = $contacts['values'];

var_dump($contactsArray);

Symfony HTTP客户端示例

<?php

declare(strict_types=1);

// Require Composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Define the desired type of authentication and key
$authType = \Circle\CiviCRM\AuthenticationTypes::BEARER_API_KEY;
$authKey = 'MYKEYGOESHERE'; // best practices dictate using an environment variable here!

// Instantiate a new Symfony HTTP client
$symfonyClient = \Symfony\Component\HttpClient\HttpClient::createForBaseUri('https://my.civicrm.site');
$psr18client = new \Symfony\Component\HttpClient\Psr18Client($symfonyClient);

// Instantiate a new CiviCRM API client, passing the PSR18-compatible Symfony HTTP client as a parameter
$civicrm = new \Circle\CiviCRM\Client($psr18client, $authType, $authKey);

// Make request to retrieve all Activities
$activityResponse = $civicrm->get('Activity');
// Note that the full API response object is returned to the caller
$activityJson = $activityResponse->getBody()->getContents();
// Decode the response
$activities = json_decode($activityJson, TRUE);
$activitiesArray = $activities['values'];

var_dump($activitiesArray);

注意：在与API交互时，请使用正确的、大小写特定的实体名称（例如：“activity”将返回错误，请使用“Activity”代替）

可用函数

示例使用此库公开的get方法。然而，这并不是唯一可用的方法。可用方法列表如下

getActions
getFields
get
create
update
save
delete
replace

此外，库还公开了request方法。这允许任意组合的Entity、action和params。以下是一个使用此方法的示例

$civicrm = new \Circle\CiviCRM\Client($psr18client, $authType, $authKey);
$myCustomResponse = $civicrm->request('CustomEntity', 'customaction', ['my' => 'custom', 'params']);

以下是一些（非穷举）情况会有所帮助：

您的CiviCRM实例包含自定义实体
您想执行特定于实体的操作（例如：MailSettings.testConnection或Setting.set）

可用的身份验证方法

此库在向CiviCRM实例发出请求时使用X-Civi-Auth标题。因此，以下身份验证方法可用

此库不支持任何其他形式的身份验证。

注意：创建客户端对象时，仅传递身份验证密钥（即：MYKEY）。

不要传递Bearer或Basic关键字（即：Bearer MYKEY或Basic MYKEY），因为这些由库设置。

关于基本身份验证的说明

当使用基本身份验证时，密钥是base64编码的字符串：B64(USER:PASSWORD)。您需要将Base64编码的字符串作为$authKey参数提供给Circle\CiviCRM\Client构造函数。

贡献

如果您在此库中发现错误或其他问题，请在GitHub存储库中提出问题。

要运行测试，请运行composer test。该库使用 Pest 进行自动化测试，并遵循 PHPStan Level 6。

资源

支持

Circle Interactive 的技术团队负责维护此库，其网址为Circle Interactive。Circle 为各类第三部门的客户提供 CiviCRM 实施，无论规模大小。

许可证

此软件包采用与 CiviCRM 相同的许可证，即AGPL-3.0。

circle-interactive / civicrm-api

维护者

详细信息