itul / bugherdapi
Laravel package for using the bugherd API
Requires
- php: ^7.4|^8.0
- illuminate/support: >=8.0
Requires (Dev)
- orchestra/testbench: ^6.0
- phpunit/phpunit: ^9.0
README
The BugherdAPI Laravel package provides a convenient interface for interacting with the Bugherd API. It includes methods for managing projects, users, tasks, comments, and their associations, while handling API rate limits and caching.
Table of Contents
Getting Started
Requirements
Before using this package, ensure your system meets the following requirements:
- PHP: Version 8.0 or higher.
- Laravel: Version 9.x or higher.
- Bugherd API Key: Obtain an API key from your Bugherd account.
Installation
Install the package via Composer:
composer require itul/bugherdapi
Environment Variables
Set the following environment variables in your .env file:
BUGHERD_API_KEY=your_api_key
BUGHERD_BASE_URL=https://www.bugherd.com/api_v2/
Caching
The package uses Laravel's caching mechanism to store project and user data for improved performance. Cached data is refreshed automatically after 28000 seconds.
Class Overview
BugherdAPI Class
Description:
The BugherdAPI class serves as the main entry point for interacting with the Bugherd API. It provides methods for sending API requests (GET, POST, PUT, DELETE) and includes caching and rate limit management.
Properties
| Property Name | Type | Description |
|---|---|---|
$projectCache | static | Stores cached project data. |
$userCache | static | Stores cached user data. |
$requests | static | Tracks API requests to manage rate limits. |
Methods
| Method Name | Parameters | Return Type | Description |
|---|---|---|---|
sendRequest | $type, $endpoint, $data | object | Sends a request to the Bugherd API with rate limit management. |
sendGet | $endpoint, $data | object | Sends a GET request to the Bugherd API. |
sendPost | $endpoint, $data | object | Sends a POST request to the Bugherd API. |
sendPut | $endpoint, $data | object | Sends a PUT request to the Bugherd API. |
sendDelete | $endpoint, $data | object | Sends a DELETE request to the Bugherd API. |
getProjects | None | object | Retrieves and caches Bugherd projects. |
getUserProjects | None | object | Retrieves projects with their associated members. |
getUsers | None | object | Retrieves and caches Bugherd users. |
BugherdModel Class
Description:
The BugherdModel class serves as a base model for interacting with the Bugherd API. It provides methods to handle relationships, API URLs, and model names, mimicking Laravel's Eloquent ORM functionality.
Properties
| Property Name | Type | Description |
|---|---|---|
$apiUrl | string | The API URL for the model. |
$modelName | string | The name of the model. |
$relations | array | An array of model relationships. |
$instance | static | A static instance of the model. |
Methods
| Method Name | Parameters | Return Type | Description |
|---|---|---|---|
__construct | $data | void | Initializes the model with the provided data. |
getApiUrl | None | string | Retrieves the API URL for the model. |
setApiUrl | $url | self | Sets the API URL for the model. |
hasMany | $model, ...$args | Collection | Mimics the Laravel hasMany relationship to retrieve related models. |
belongsTo | $model, $id | BugherdModel|null | Mimics the Laravel belongsTo relationship to retrieve a related model. |
getModelName | None | string | Retrieves the model name. |
generateApiUrl | None | string | Generates the API URL for the model. |
generateModelName | $plural | string | Generates the model name, singular or plural based on the parameter. |
list | ...$args | Collection | Lists all instances of the model with optional filters and pagination. |
details | None | BugherdModel|null | Retrieves the details of the model instance. |
find | $id | BugherdModel | Finds a model instance by its ID. |
BugherdUser Class
Description:
The BugherdUser class represents a user in the Bugherd API. It provides methods to retrieve the projects the user is a member of and tasks assigned to the user across all projects.
Properties
| Property Name | Type | Description |
|---|---|---|
$apiUrl | string | The API URL for the users. |
$modelName | string | The name of the model, which is user. |
Methods
| Method Name | Parameters | Return Type | Description |
|---|---|---|---|
projects | None | Collection | Retrieves the projects the user is a member of. |
tasks | ...$args | Collection | Retrieves all tasks assigned to the user across all projects. |
BugherdProject Class
Description:
The BugherdProject class represents a project in the Bugherd API. It provides methods to retrieve tasks associated with the project.
Properties
| Property Name | Type | Description |
|---|---|---|
$apiUrl | string | The API URL for the project. |
$modelName | string | The name of the project model. |
Methods
| Method Name | Parameters | Return Type | Description |
|---|---|---|---|
tasks | ...$args | Collection | Retrieves all tasks associated with the project, enriched with the project name. |
BugherdProjectTask Class
Description:
The BugherdProjectTask class represents a task within a Bugherd project. It provides methods to archive the task, retrieve the associated project, and get comments for the task.
Properties
| Property Name | Type | Description |
|---|---|---|
$apiUrl | string | The API URL for the tasks in a project. |
$modelName | string | The name of the model, which is task. |
Methods
| Method Name | Parameters | Return Type | Description |
|---|---|---|---|
archive | None | object | Archives the task by changing its status to closed. |
project | None | BugherdProject | Retrieves the project associated with this task. |
comments | None | Collection | Retrieves all comments associated with this task. |
BugherdProjectTaskComment Class
Description:
The BugherdProjectTaskComment class represents a comment on a task within a Bugherd project. It provides methods to retrieve the task associated with the comment.
Properties
| Property Name | Type | Description |
|---|---|---|
$apiUrl | string | The API URL for task comments. |
$modelName | string | The name of the model, which is comment. |
Methods
| Method Name | Parameters | Return Type | Description |
|---|---|---|---|
task | None | BugherdProjectTask | Retrieves the task associated with this comment. |
Usage
Sending API Requests
The BugherdAPI class provides methods for sending requests to the Bugherd API:
use Itul\BugherdAPI\BugherdAPI;
// Send a GET request
$response = BugherdAPI::sendGet('projects', ['status' => 'active']);
// Send a POST request
$response = BugherdAPI::sendPost('projects', ['name' => 'New Project']);
// Send a PUT request
$response = BugherdAPI::sendPut('projects/1', ['name' => 'Updated Project']);
// Send a DELETE request
$response = BugherdAPI::sendDelete('projects/1');
Managing Projects
Retrieve tasks and users for projects:
use Itul\BugherdAPI\BugherdAPI;
use Itul\BugherdAPI\BugherdProject;
// Get the project by ID
$project = BugherdProject::find($id);
// Get the tasks
$tasks = $project->tasks();
// Get the users for a specific project
$users = $project->members;
// Get all projects
$projects = BugherdAPI::getProjects();
// Get projects with members
$userProjects = BugherdAPI::getUserProjects();
Managing Users
Retrieve and cache Bugherd users:
use Itul\BugherdAPI\BugherdAPI;
// Get all users
$users = BugherdAPI::getUsers();
Managing Tasks
Archive a task, retrieve its associated project, or get its comments:
use Itul\BugherdAPI\BugherdProjectTask;
// Archive a task
$task = BugherdProjectTask::find($id);
$response = $task->archive();
// Get the associated project
$project = $task->project();
// Get comments for the task
$comments = $task->comments();
Managing Task Comments
Retrieve the task associated with a specific comment:
use Itul\BugherdAPI\BugherdProjectTaskComment;
$comment = BugherdProjectTaskComment::find($id);
$task = $comment->task();
License
This package is open-source and licensed under the MIT License.