Tutorial

On this page you can find a few samples of code using this toolkit.

Including Composer autoloader

Before you start using this library, you need to install it via Composer and include the generated autoloader into your application.

require_once 'vendor/autoload.php';

Creating the client instance

The library exposes a public API which includes an IOrganizationService-compatible Client. There are a few options to create a new instance of the client.

Use ClientFactory

ClientFactory provides a simple way to instantiate a new Client with all dependencies in place. As Dynamics 365 (online) is currently the only supported type of deployment, ClientFactory contains only one static method, ClientFactory::createOnlineClient. For IFD and On-Premises support please refer to Roadmap.

The minimal set of values you need to connect to Dynamics 365 Online is as follows:

• Organization URI, e.g. https://contoso.crm.dynamics.com
• Application ID - identifies the Azure AD application registration associated with your Dynamics 365 organization
• Application Secret - a password generated in Settings / API Access / Keys section of your Azure AD application registration

Read this article (archive) to understand how to register a new app in Azure Active Directory and associate it with an application user in Dynamics 365.

Once you have all three items, it's time to create a new client:

$client = \AlexaCRM\WebAPI\ClientFactory::createOnlineClient(
    'https://contoso.crm.dynamics.com',
    '00000000-0000-0000-0000-000000000000',
    'Application Secret'
);

The library follows the lazy initialization pattern and doesn't actually validate the connection at client initialization time. To see how to handle errors, see below.

Manual creation

Sometimes you may want to create all necessary objects yourself. The first step is to create a Settings object. For online deployments, use OnlineSettings.

$settings = new \AlexaCRM\WebAPI\OData\OnlineSettings();
$settings->instanceURI = 'https://contoso.crm.dynamics.com';
$settings->applicationID = '00000000-0000-0000-0000-000000000000';
$settings->applicationSecret = 'Application Secret';

You can optionally supply a PSR-3 compliant logger.

$settings->setLogger( $logger );

You can optionally supply a PSR-6 compliant cache adapter.

$settings->cachePool = $cacheAdapter;

By default, the HTTP client used by the library verifies SSL certificates against the local CA certificate bundle. If it is broken, like as what happens often on development environments in Windows and OS X, you can either supply a valid CA bundle or disable verification.

$settings->caBundle = false;
$settings->caBundle = '/path/to/ca-bundle.crt';

The default Web API version which the plugin connects to is 8.2. It is the minimal tested Web API version as well. (Although not tested, it might very well work with earlier versions, perhaps with some limitations.)

If you need to change the API version, it is also configured in the Settings object:

$settings->apiVersion = '9.0';