README

Tip

Need help? Join our Discord or email jesse@bentonow.com for personalized support.

The Bento PHP SDK makes it quick and easy to build an excellent analytics experience in your PHP application. We provide powerful and customizable APIs that can be used out-of-the-box to track your users' behavior, manage subscribers, and send emails. We also expose low-level APIs so that you can build fully custom experiences.

Get started with our 📚 integration guides, or 📘 browse the SDK reference.

❤️ Thank you @cavel (in Discord) from GuitarCreative for your contribution to the Laravel documentation (which lead to the creation of our new official Laravel SDK).

Table of contents

• Features
• Requirements
• Getting started
  • Installation
  • Configuration
• Modules
• Type Reference
• Things to Know
• Contributing
• License

Features

• Simple event tracking: We make it easy for you to track user events and behavior in your application.
• Subscriber management: Easily add, update, and remove subscribers from your Bento account.
• Custom fields: Track and update custom fields for your subscribers to store additional data.
• Purchase tracking: Monitor customer purchases and calculate lifetime value (LTV) for your subscribers.
• Batch operations: Perform bulk imports of subscribers and events for efficient data management.
• Email validation: Validate email addresses to ensure data quality.

Requirements

The Bento PHP SDK requires PHP 7.4+ and Composer.

Bento Account for a valid SITE_UUID, BENTO_PUBLISHABLE_KEY & BENTO_SECRET_KEY.

Getting started

Installation

Install the Bento SDK using Composer:

composer require bentonow/bento-php-sdk

Configuration

Initialize the Bento client:

use bentonow\Bento\BentoAnalytics;

$bento = new BentoAnalytics([
  'authentication' => [
    'secretKey' => 'bento-secret-key',
    'publishableKey' => 'bento-publishable-key'
  ],
  'siteUuid' => 'bento-site-uuid'
]);

Modules

Analytics (Base Module)

Track events and manage subscribers.

Tag a Subscriber

$bento->V1->tagSubscriber([
  'email' => 'user@example.com',
  'tagName' => 'New Customer',
]);

Add a Subscriber

$bento->V1->addSubscriber([
  'email' => 'user@example.com',
  'fields' => [
    'firstName' => 'John',
    'lastName' => 'Doe',
  ],
]);

Remove a Subscriber

$bento->V1->removeSubscriber([
  'email' => 'user@example.com',
]);

Update Fields

$bento->V1->updateFields([
  'email' => 'user@example.com',
  'fields' => [
    'firstName' => 'John',
  ],
]);

Track Purchase

$bento->V1->trackPurchase([
  'email' => 'user@example.com',
  'purchaseDetails' => [
    'unique' => [
      'key' => 1234,
    ],
    'value' => [
      'amount' => 100,
      'currency' => 'USD',
    ],
  ],
]);

Track Event

$bento->V1->track([
  'email' => 'user@example.com',
  'type' => '$custom.event',
  'details' => [
    'fromCustomEvent' => true,
  ],
]);

Batch

Import Subscribers

$bento->V1->Batch->importSubscribers([
  'subscribers' => [
    ['email' => 'user1@example.com', 'age' => 25],
    ['email' => 'user2@example.com', 'name' => 'Jane Doe'],
  ]
]);

Import Events

use bentonow\Bento\SDK\Batch\BentoEvents;

$bento->V1->Batch->importEvents([
  'events' => [
    ['email' => 'user@example.com', 'type' => BentoEvents::SUBSCRIBE],
    ['email' => 'user@example.com', 'type' => BentoEvents::UNSUBSCRIBE],
    [
      'email' => 'user@example.com',
      'details' => [
        'customData' => 'Used internally.'
      ],
      'type' => '$custom.myEvent'
    ]
  ]
]);

Commands

Add Tag

$bento->V1->Commands->addTag([
  'email' => 'user@example.com',
  'tagName' => 'VIP',
]);

Remove Tag

$bento->V1->Commands->removeTag([
  'email' => 'user@example.com',
  'tagName' => 'VIP',
]);

Add Field

$bento->V1->Commands->addField([
  'email' => 'user@example.com',
  'field' => [
    'key' => 'favoriteColor',
    'value' => 'blue',
  ],
]);

Remove Field

$bento->V1->Commands->removeField([
  'email' => 'user@example.com',
  'fieldName' => 'favoriteColor',
]);

Subscribe

$bento->V1->Commands->subscribe([
  'email' => 'user@example.com',
]);

Unsubscribe

$bento->V1->Commands->unsubscribe([
  'email' => 'user@example.com',
]);

Events

Create Event

$bento->V1->Events->createEvent([
  'type' => '$completed_onboarding',
  'email' => 'user@example.com',
]);

Experimental

Validate Email

$bento->V1->Experimental->validateEmail([
  'email' => 'user@example.com',
]);

Guess Gender

$bento->V1->Experimental->guessGender([
  'name' => 'Alex',
]);

Geolocate

$bento->V1->Experimental->geolocate([
  'ip' => '127.0.0.1',
]);

Check Blacklist

$bento->V1->Experimental->checkBlacklist([
  'domain' => 'example.com',
]);

Fields

Get Fields

$fields = $bento->V1->Fields->getFields();

Create Field

$bento->V1->Fields->createField([
  'key' => 'favoriteColor',
]);

Forms

Get Form Responses

$responses = $bento->V1->Forms->getResponses('form-id-123');

Subscribers

Get Subscriber

$subscriber = $bento->V1->Subscribers->getSubscribers([
  'email' => 'user@example.com',
]);

Create Subscriber

$bento->V1->Subscribers->createSubscriber([
  'email' => 'newuser@example.com',
]);

Tags

Get Tags

$tags = $bento->V1->Tags->getTags();

Create Tag

$bento->V1->Tags->createTag([
  'name' => 'Premium',
]);

Types Reference

For a detailed reference of the types used in the Bento PHP SDK, please refer to the Types Reference section in the full documentation.

Things to Know

1. All events must be identified with an email address.
2. Most events are indexed within seconds in your Bento account.
3. Batch operations are available for importing subscribers and events efficiently.
4. The SDK provides seamless integration with Laravel applications.
5. Email validation and experimental features are available for advanced use cases.

Contributing

We welcome contributions! Please see our contributing guidelines for details on how to submit pull requests, report issues, and suggest improvements.

License

The Bento SDK for PHP is available as open source under the terms of the MIT License.