README

civicrm-api is a Composer package that allows developers to interact with a CiviCRM instance using the REST API v4 functionality within CiviCRM.

This code is intended to be used outside of a CiviCRM deployment environment. As such, the codebase adheres to PSR-12 coding standards instead of Drupal/Wordpress/CiviCRM coding standards.

Installation

To install the library, run the following command:

composer require circle-interactive/civicrm-api

Requirements

The CiviCRM server must be running on v5.47 or later.

In this release, the /civicrm/ajax/* endpoints were exposed as web services as part of currently ongoing efforts to expose REST endpoints via the standard CiviCRM routing system. Click here to learn more.

Your application must use an HTTP client that is PSR-18 compliant.

If your application uses an HTTP client that is not compliant with PSR-18, it will be necessary to write a decorator class that implements a sendRequest method.

How to Use

NB: As you can see from the examples, this library does not deserialize responses. This is by design.

Calling code is responsible for response deserialization and handling the data from that response.

Guzzle Example

<?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 Client Example

<?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);

NB: Use correct, case-specific Entity names when interacting with the API (for example: "activity" will return an error, use "Activity" instead)

Available Functions

The examples make use of the get method exposed by this library. However, this is not the only available method. The list of available methods is as follows:

getActions
getFields
get
create
update
save
delete
replace

As well as the above, the library also exposes the request method. This allows for arbitrary combinations of Entity, action, and params. An example of usage of this method can be seen below:

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

This would be useful in the following (non-exhaustive list of) situations:

Your CiviCRM instance contains custom entities
You want to perform an entity-specific action (for example: MailSettings.testConnection, or Setting.set)

Available Authentication Methods

This library uses the X-Civi-Auth Header when making requests to CiviCRM instances. As such, the following authentication methods are available:

Type of Authentication	Library Mapping
Basic Authentication	Circle\CiviCRM\AuthenticationTypes::BASIC
API Key Authentication	Circle\CiviCRM\AuthenticationTypes::BEARER_API_KEY
JWT Authentication	Circle\CiviCRM\AuthenticationTypes::BEARER_JWT

Any other form of authentication is unsupported by this library.

NB: When creating a Client object, only pass the Authentication Key (ie: MYKEY).

Do not pass the Bearer or Basic keywords (ie: Bearer MYKEY or Basic MYKEY)as these are put in place by the library.

Note on Basic Authentication

When using Basic Authentication, the key is a base64 encoded string: B64(USER:PASSWORD). You will need to provide the Base64 encoded string as the $authKey parameter to the Circle\CiviCRM\Client constructor.

Contributing

If you find a bug or other issue within this library, please raise an issue in this Github repository.

To run tests, run composer test. The library uses Pest for automated testing, and adheres to PHPStan Level 6.

Resources

Support

The technical team at Circle Interactive are responsible for the maintenance of this library. Circle offer CiviCRM implementations for third-sector clients of any kind, no matter the size.

License

This package is licensed with AGPL-3.0, as is CiviCRM.

circle-interactive / civicrm-api

Maintainers

Details