README

A Laravel package for quick and easy integration with the Trello API, providing a comprehensive set of features for managing boards, lists, cards, members, and more.

Installation

You can install the package via composer:

composer require quickhelper/quicktrello

Publishing the config file

php artisan vendor:publish --tag="quicktrello-config"

This will publish the config file to config/quicktrello.php.

Configuration

Add the following to your .env file:

TRELLO_API_KEY=your_trello_api_key
TRELLO_TOKEN=your_trello_token
TRELLO_WEBHOOK_SECRET=optional_webhook_secret

You can get your API key and token from https://trello.com/app-key.

Usage

Boards

use QuickTrello\Facades\QuickTrello;

// Get all boards
$boards = QuickTrello::getBoards();

// Get a specific board
$board = QuickTrello::getBoard('board_id');

// Get board members
$members = QuickTrello::getBoardMembers('board_id');

Lists

// Get lists for a board
$lists = QuickTrello::getLists('board_id');

// Create a new list
$list = QuickTrello::createList('board_id', 'List Name', [
    'pos' => 'top' // Optional position ('top', 'bottom', or a position value)
]);

// Update a list
$list = QuickTrello::updateList('list_id', [
    'name' => 'New List Name',
    'pos' => 'bottom'
]);

// Archive a list
$list = QuickTrello::archiveList('list_id', true); // Archive
$list = QuickTrello::archiveList('list_id', false); // Unarchive

Cards

// Get cards for a list
$cards = QuickTrello::getCards('list_id');

// Create a card
$card = QuickTrello::createCard('list_id', 'Card title', [
    'desc' => 'Card description',
    'due' => '2025-03-01',
    'pos' => 'top'
]);

// Update a card
$card = QuickTrello::updateCard('card_id', [
    'name' => 'Updated Card Title',
    'desc' => 'Updated description'
]);

// Move a card to another list
$card = QuickTrello::moveCard('card_id', 'new_list_id');

// Add a comment to a card
$comment = QuickTrello::addComment('card_id', 'This is a comment');

// Add a label to a card
$label = QuickTrello::addLabel('card_id', 'label_id');

// Remove a label from a card
$result = QuickTrello::removeLabel('card_id', 'label_id');

// Add a due date to a card
$card = QuickTrello::addDueDate('card_id', '2025-03-01T12:00:00Z');

Members and Assignments

// Get all board members
$members = QuickTrello::getBoardMembers('board_id');

// Get all organization members
$members = QuickTrello::getOrganizationMembers('org_id');

// Assign a member to a card
$result = QuickTrello::assignMemberToCard('card_id', 'member_id');

// Remove a member from a card
$result = QuickTrello::removeMemberFromCard('card_id', 'member_id');

// Get members assigned to a card
$members = QuickTrello::getCardMembers('card_id');

Checklists

// Add a checklist to a card
$checklist = QuickTrello::addChecklist('card_id', 'Checklist Name');

// Add an item to a checklist
$item = QuickTrello::addChecklistItem('checklist_id', 'Checklist Item');

Webhooks

The package automatically registers a webhook endpoint at /api/trello/webhooks (configurable). You can create webhooks in Trello to receive notifications when events occur:

// Create a webhook
$webhook = QuickTrello::createWebhook(
    'https://your-app.com/api/trello/webhooks',
    'model_id', // board_id, card_id, etc.
    'Description of webhook'
);

// Get all webhooks
$webhooks = QuickTrello::getWebhooks();

// Delete a webhook
$result = QuickTrello::deleteWebhook('webhook_id');

Listening for Webhook Events

You can listen for webhook events in your Laravel application:

// In your EventServiceProvider
Event::listen('quicktrello.webhook_received', function ($payload) {
    // Handle all webhook events
});

// Listen for specific event types
Event::listen('quicktrello.createCard', function ($payload) {
    // Handle card creation events
});

Event::listen('quicktrello.updateCard', function ($payload) {
    // Handle card update events
});

Event::listen('quicktrello.addMemberToCard', function ($payload) {
    // Handle when a member is assigned to a card
});

Event::listen('quicktrello.createList', function ($payload) {
    // Handle list creation events
});

Advanced Usage

Error Handling

The package throws TrelloException when API errors occur. You can catch these exceptions to handle errors gracefully:

use QuickTrello\Exceptions\TrelloException;

try {
    $card = QuickTrello::createCard('list_id', 'Card title');
} catch (TrelloException $e) {
    // Handle error
    $statusCode = $e->getCode();
    $message = $e->getMessage();
}

Webhook Verification

For added security, you can set a webhook secret in your config and the package will verify incoming webhook requests:

// In config/quicktrello.php
'webhook_secret' => env('TRELLO_WEBHOOK_SECRET'),

Available Methods

Boards

• getBoards()
• getBoard(string $boardId)
• getBoardMembers(string $boardId)

Lists

• getLists(string $boardId)
• createList(string $boardId, string $name, array $options = [])
• updateList(string $listId, array $data)
• archiveList(string $listId, bool $archived = true)

Cards

• getCards(string $listId)
• createCard(string $listId, string $name, array $options = [])
• updateCard(string $cardId, array $data)
• moveCard(string $cardId, string $listId)
• addComment(string $cardId, string $text)
• addLabel(string $cardId, string $labelId)
• removeLabel(string $cardId, string $labelId)
• addDueDate(string $cardId, string $dueDate)

Members

• getBoardMembers(string $boardId)
• getOrganizationMembers(string $orgId)
• assignMemberToCard(string $cardId, string $memberId)
• removeMemberFromCard(string $cardId, string $memberId)
• getCardMembers(string $cardId)

Checklists

• addChecklist(string $cardId, string $name)
• addChecklistItem(string $checklistId, string $name)

Webhooks

• createWebhook(string $callbackUrl, string $idModel, string $description = '')
• deleteWebhook(string $webhookId)
• getWebhooks()

License

The MIT License (MIT). Please see License File for more information.

Best regards,
Yossef Ashraf