README

A PHP client to interact with Braze API

Braze offers a cloud-based customer engagement platform for multichannel marketing. This SDK allows you to integrate its REST API into a PHP application.

Features
Install
Usage
Compatibility
Requirements
Powered Apps
Contributing
Changelog
License

Features

Explicit representation of the API contract to write requests easily using the IDE autocomplete
Formal validation (strict and non-strict) of requests
Dry-run mode to simulate requests and validate them without actually performing calls
Ability to use any http client via an adapter. For PSR-18 compatible clients and the Symfony client, adapters are included in the SDK
Parallel API calls supported if the http client allows it (for example the Symfony one)

Install

Add the SDK as a dependency running:

composer require immobiliarelabs/braze-sdk

If not already included in your project, to make http requests, you need to install any combination of packages that implements:

for example by installing symfony/http-client and nyholm/psr7 you are ready to use the SDK, also with parallel requests.

Alternatively, it is also possible to use any http client by creating the appropriate adapter.

Usage

Example

Before instantiating the SDK it is necessary to create the http client and its adapter.

use ImmobiliareLabs\BrazeSDK\ClientAdapter\SymfonyAdapter;
use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create();
$adapter = new SymfonyAdapter($client);

This example is for the Symfony http client, but the flow is the same whether you are using a PSR-18 client or a custom one. Then you can create the SDK instance.

use ImmobiliareLabs\BrazeSDK\Braze;
use ImmobiliareLabs\BrazeSDK\Region;

$braze = new Braze($adapter, 'my-api-key', Region::EU01);

Now you can start making requests by creating one and passing it to the appropriate endpoint.

use ImmobiliareLabs\BrazeSDK\Object\Event;
use ImmobiliareLabs\BrazeSDK\Request\Users\TrackRequest;

$event = new Event();
$event->external_id = 'user-id';
$event->app_id = 'app-id';
$event->name = 'event-name';
$event->time = new \DateTimeImmutable();
$event->properties = ['property' => 'property-value'];

$request = new TrackRequest();
$request->events = [$event];

$response = $braze->users()->track($request, false);

You can also set connection and overall timeout.

$braze->setConnectionTimeout(2.0);
$braze->setOverallTimeout(3.0);

Currently, SymfonyAdapter supports them, while Psr18Adapter does not.

You can see a few complete examples in the repository.

Custom user attributes

To set custom User attributes use the setCustomAttribute or setCustomAttributes methods available in the UserAttributes class.

use ImmobiliareLabs\BrazeSDK\Object\UserAttributes;

$userAttributes = new UserAttributes();
$userAttributes->external_id = 'user-id';
$userAttributes->first_name = 'Name';

$userAttributes->setCustomAttribute('custom_int_property', 47);

$userAttributes->setCustomAttributes([
    'custom_string_property' => 'properyValue',
    'custom_bool_property' => false,
]);

$request = new TrackRequest();
$request->attributes = [$userAttributes];

$response = $braze->users()->track($request, false);

Endpoints

Endpoints are organized by url prefix. The SDK supports all the Braze endpoints:

users
campaigns
canvas
messages
content_blocks
templates
email
events
feed
purchases
sessions
sends
transactional
subscription

Validation and dry-run

The SDK does a formal validation of the request before executing it. It is however possible to disable it completely:

$braze->setValidation(false);

or just the strict one, since Braze partially executes requests when possible:

$braze->setValidation(true, false);

By default, the SDK performs strict validation.

If you want to validate your requests without sending them to Braze you can enable dry-run mode:

$braze->setDryRun(true);

HTTP client adapter

If, in your project, you already have a http client which does not implement one of the two supported interfaces (Symfony and PSR18), and you don't want to install another one, just define an adapter that implements the ImmobiliareLabs\BrazeSDK\ClientAdapter\ClientAdapterInterface interface, and use it when instantiate the SDK.

Parallel requests

If the chosen http client supports asynchronous calls, you can exploit that to make parallel requests to Braze in this way:

$response1 = $braze->users()->track($request1, true);
$response2 = $braze->users()->track($request2, true);

$braze->flush();

The response objects will be filled with the values obtained only after the call to flush.

Compatibility

Requirements

ext-json

Powered Apps

Braze PHP SDK was created by the PHP team at ImmobiliareLabs, the Tech dept of Immobiliare.it, the #1 real estate company in Italy.

We are currently using this SDK to stay in touch with our users.

If you are using Braze PHP SDK in production drop us a message.

Contributing

Any questions, bug reports or suggestions for improvement are very welcome. See the contributing file for details on how to contribute.

Changelog

Please refer to the changelog notes.

License

Braze PHP SDK is licensed under the MIT license.
See the LICENSE file for more information.

immobiliarelabs / braze-sdk

Maintainers

Details