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.