jeffersongoncalves / laravel-dub

1.0.0 2026-09-06 22:30 UTC

Requires

• php: ^8.2
• illuminate/support: ^11.0|^12.0|^13.0
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.21
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Jefferson Gonçalves

• http
• rest
• client
• analytics
• laravel
• link-shortener
• dub
• dub.co

Published on Packagist.org on 2026-09-06 22:31 UTC

README

Laravel Dub

A lightweight Dub.co API client for Laravel. It wraps the api.dub.co REST calls behind a small static client, threads your API key, and centralises rate-limit detection so callers get a thrown DubRateLimitException rather than a silent failure during a limit window.

Features

• Link management — createLink(), listLinks(), getLink(), updateLink(), deleteLink(), bulkCreateLinks()
• Analytics — analytics(), analyticsByCountry(), analyticsByDevice()
• Rate-limit aware — throws DubRateLimitException on a 429, honouring the Retry-After header, carrying the retryAfter seconds
• No exceptions on plain non-2xx — every method returns null/false on ordinary failures so callers don't need to wrap every call in a try/catch

Installation

composer require jeffersongoncalves/laravel-dub

Optionally publish the config file:

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

Configuration

Add to your .env:

DUB_API_KEY=dub_xxxxxxxxxxxxxxxxxxxx

Create an API key from your Dub workspace settings.

Config Options

// config/dub.php
return [
    'api_key' => env('DUB_API_KEY'),
    'api_url' => env('DUB_API_URL', 'https://api.dub.co'),
    'timeout' => (int) env('DUB_TIMEOUT', 8),
];

Usage

use JeffersonGoncalves\Dub\DubClient;
use JeffersonGoncalves\Dub\Exceptions\DubRateLimitException;

// Create a link
$link = DubClient::createLink([
    'url' => 'https://example.com',
    'domain' => 'dub.sh',
]);

// List links
$links = DubClient::listLinks(['domain' => 'dub.sh']);

// Get a link by domain/key or linkId/externalId
$link = DubClient::getLink(['domain' => 'dub.sh', 'key' => 'abc123']);

// Update a link
$link = DubClient::updateLink('link_1234', ['url' => 'https://example.com/updated']);

// Delete a link
$deleted = DubClient::deleteLink('link_1234');

// Bulk create links
$links = DubClient::bulkCreateLinks([
    ['url' => 'https://example.com/a'],
    ['url' => 'https://example.com/b'],
]);

// Analytics
$analytics = DubClient::analytics(['domain' => 'dub.sh', 'key' => 'abc123']);
$byCountry = DubClient::analyticsByCountry(['domain' => 'dub.sh', 'key' => 'abc123']);
$byDevice = DubClient::analyticsByDevice(['domain' => 'dub.sh', 'key' => 'abc123']);

Handling rate limits

try {
    $links = DubClient::listLinks();
} catch (DubRateLimitException $e) {
    // Back off for $e->retryAfter seconds (queue jobs can release($e->retryAfter)).
}

Testing

composer test

Static Analysis

composer analyse

Code Formatting

composer format

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

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