README

This library helps with integrating Userlist into PHP applications.

Installation

This library can be installed via Composer:

composer require userlist/userlist

Configuration

The only required configuration is the Push API key. You can get your Push API key via the Push API settings in your Userlist account.

Configuration values can be set when creating a new push client or via environment variables. The environment takes precedence over values provided during the initialization process.

Configuration via environment variables

USERLIST_PUSH_KEY=401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39

Configuration during initialization

$userlist = new \Userlist\Push(['push_key' => '401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39']);

Usage

Before tracking user or event data, create a new push client. If you configured your push key via environment variables there's nothing to add. Otherwise, see the example above.

$userlist = new \Userlist\Push();

Tracking Users

Creating & updating Users

$user = [
    'identifier' => 'user-1',
    'email' => 'user@example.com',
    'properties' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe'
    ]
];

$userlist->users->push($user);

$userlist->user($user); // Alias
$userlist->users->create($user); // Alias

Deleting Users

$userlist->users->delete('user-1');
$userlist->users->delete($user);

Tracking Companies

Creating & updating Companies

$company = [
    'identifier' => 'company-1',
    'name' => 'Example, Inc.',
    'properties' => [
        'industry' => 'Software Testing'
    ]
];

$userlist->companies->push($company);

$userlist->company($company); // Alias
$userlist->companies->create($company); // Alias

Deleting Companies

$userlist->companies->delete('company-1');
$userlist->companies->delete([ 'identifier' => 'company-1' ]);

Tracking Relationships

Creating & updating Relationships

$relationship = [
    'user' => 'user-1',
    'company' => 'company-1',
    'properties' => [
        'role' => 'admin'
    ]
];

$userlist->relationships->push($relationship);

$userlist->relationship($relationship); // Alias
$userlist->relationships->create($relationship); // Alias

This is equivalent to specifying the relationship on the user model.

$user = [
    'identifier' => 'user-1',
    'relationships' => [
        [
            'company' => 'company-1',
            'properties' => [
                'role' => 'admin'
            ]
        ]
    ],
];

$userlist->users->push($user);

It's also equivalent specifying the relationship on the company model.

$company = [
    'identifier' => 'company-1',
    'relationships' => [
        [
            'user' => 'user-1',
            'properties' => [
                'role' => 'admin'
            ]
        ]
    ],
];

$userlist->companies->push($company);

Deleting Relationships

$relationship = [
    'user' => 'user-1',
    'company' => 'company-1'
]

$userlist->relationships->delete($relationship);

Tracking Events

$event = [
    'name' => 'project_created',
    'user' => 'user-1',
    'properties' => [
        'name' => 'Example Project',
    ]
];

$userlist->events->push($event);

$userlist->event($event); // Alias
$userlist->events->create($event); // Alias

Sending Transactional Messages

$message = [
    'user' => 'user-1',
    'template' => 'welcome-email',
    'properties' => [
        'account_name' => 'Example, Inc.',
        'billing_plan' => 'Pro',
    ]
];

$userlist->messages->push($message);

$userlist->message($message); // Alias
$userlist->messages->create($message); // Alias

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/userlist/userlist-php. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The library is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Userlist project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

What is Userlist?

Userlist allows you to onboard and engage your SaaS users with targeted behavior-based campaigns using email or in-app messages.

Userlist was started in 2017 as an alternative to bulky enterprise messaging tools. We believe that running SaaS products should be more enjoyable. Learn more about us.

userlistio / userlist

Maintainers

Details