Library Reference

Sometimes you'll need a more fine-grained control over your data at Belltastic. For this, you can utilize common operations on the Belltastic models that you can interact with in a familiar manner.

By default, any operations will use the API key provided in the belltastic.api_key configuration value. If you would like to use a different API key, you can set it like so:

// Set the API key globally, so you can then interact with all objects as described below.
\Belltastic\Belltastic::setApiKey('user_YVBpHfvUh...md5Iq');

// Or provide the API key on each request within the last $options param.
\Belltastic\Project::find(1, ['api_key' => 'user_YVBpHfvUh...md5Iq']);
\Belltastic\Project::all(['api_key' => 'user_YVBpHfvUh...md5Iq']);
// etc...

Projects

// Returns a Collection of all projects accessible with your API key
\Belltastic\Project::all();

// Returns a single project
\Belltastic\Project::find($id);

// Creates a new project
\Belltastic\Project::create([
    'team_id' => 1,         // REQUIRED, we must know which Belltastic team this project belongs to
    'name' => 'Test project',
]);

// Update a project, either update() or save()
$project->update(['name' => 'New name']);
$project->name = 'New name';
$project->save();

// Archiving/Deleting a project
$project->archive();    // archives (soft-deletes). Can be restored later.
$project->destroy();    // permanently delete. No way to restore it.

// Project has many users relation
$project->users()->all();
$project->users()->find($user_id);
$project->users()->create([
    'id' => $user_id,       // REQUIRED, must match your system's user ID
    'name' => 'Test User'
]);

Users

// returns a LazyCollection of all users for the given project ID
\Belltastic\User::all($project_id);

// returns a single user from the provided project ID
\Belltastic\User::find($project_id, $id);

// Notice how you must provide the ID yourself when creating a user,
// because it should match the user ID in your system:
\Belltastic\User::create($project_id, [
    'id' => $user_id,       // REQUIRED, must match your system's user ID
    'name' => 'Test User'
]);

// Updating a user instance, use either update() or save()
$user->update(['name' => 'New user name']);
$user->name = 'New user name';
$user->save();

// Archiving/Deleting a user
$user->archive();   // archives (soft-deletes). Can be restored later.
$user->destroy();   // permanently delete. No way to restore it.

// Return the HMAC authorization string for this user.
// Read more about HMAC here: https://belltastic.com/docs/component/hmac.html
$hmac_value = $user->hmac();
// Or, preferrably without loading a user instance via HTTP call, for speed:
$hmac_value = \Belltastic\User::hmac($project_id, $user_id);

// User has many notifications relation:
$user->notifications()->all();
$user->notifications()->find($id);
$user->notifications()->create(['title' => 'Here\'s a notification']);

Notifications

NOTE: One major difference from other entities is that Notifications cannot be updated after being created, so make sure your title, body and other attributes are correct when creating it.

The only state changes possible after the notification has already been created - marking it as seen, read, unread and deleting it.

// returns a LazyCollection of all notifications from the given project and user
\Belltastic\Notification::all($project_id, $user_id);

// returns a single notification from the given project and user
\Belltastic\Notification::find($project_id, $user_id, $id);

// creates a new notification
\Belltastic\Notification::create($project_id, $user_id, [
    // [required|string]
    // title of the notification, displayed in bolder text: 
    'title' => 'New comment on your post "Laravel Basics"',
    
    // [nullable|string]
    // body of the notification, smaller text:
    'body' => 'Joe Belltastic has left a comment on your post. Click here to see more.',
    
    // [nullable|string]
    // link to an icon/avatar to display next to notification:
    'icon' => null,
    
    // [nullable|string]
    // link to visit when the user clicks a notification:
    'action_url' => 'https://example-blog.com/posts/1234?comments',
    
    // [nullable|string]
    // category of the notification, used for segments in the future
    'category' => 'comments',
]);

// notification state changes
$notification->markAsSeen();
$notification->markAsRead();
$notification->markAsUnread();

// Archive/Delete a notification
$notification->archive();   // archives (soft-deletes). Can be restored later.
$notification->destroy();   // permanently delete. No way to restore it.