Laravel - Dub

1. Prerequisites#

To follow this guide, you will need to:

2. Install and initialize the Dub PHP SDK#

Install#

To install the Dub PHP SDK, run the following command:

composer require dub/dub-php

Configuration#

In your .env file, add your Dub API key:

DUB_API_KEY=your_api_key

In your config/services.php file, add the following:

'dub' => [  'api_key' => env('DUB_API_KEY'),],

Initialize#

You can now create an instance of the Dub class and pass in your API key:

index.php

use Dub\Dub;use Dub\Components\Security;$dub = Dub::builder()->setSecurity(config('services.dub.api_key'))->build();// create a link$dub->links->create(...);

Service Container (Optional)#

If you want to be able to inject the Dub class via the service container, add this to the register method of your AppServiceProvider.php:

index.php

$this->app->bind(Dub::class, function ($app) {  return Dub::builder()->setSecurity($app['config']->get('services.dub.api_key'))->build();});

You can then inject the authenticated Dub instance throughout your application:

index.php

use Dub\Laravel\Dub;class LinkController extends Controller {  public function createLink(Dub $dub) {    // Now you can use the SDK instance    $dub->links->create(...);  }}

3. Create link#

Let's create a short link using the Dub Laravel SDK.

index.php

use Dub\Models\Operations;class LinkController extends Controller {  public function createLink() {    $dub = new Dub();    try {      $request = new Operations\CreateLinkRequestBody(        url: 'https://google.com'      );      $response = $dub->links->create($request);      if ($response->linkSchema !== null) {        // handle response      }  } catch (Throwable $e) {    // handle exception  }  }}

Full list of available attributes for the Link model

urlstringrequired#

The destination URL of the short link.

domainstring#

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

keystring#

The short link slug. If not provided, a random 7-character slug will be generated.

keyLengthnumber#

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength.

externalIdstring | null#

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace.

tenantIdstring | null#

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.

programIdstring | null#

The ID of the program the short link is associated with.

partnerIdstring | null#

The ID of the partner the short link is associated with.

folderIdstring | null#

The unique ID of an existing folder to assign the short link to.

prefixstring#

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversionboolean#

Whether to track conversions for the short link. Defaults to false if not provided.

Default: false

identifierstring | null#

The identifier of the short link that is unique across your workspace. If set, it can be used to identify your short link for client-side click tracking.

archivedboolean#

Whether the short link is archived. Defaults to false if not provided.

Default: false

publicStatsboolean#

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided.

Default: false

tagIdsstring | string[]#

The unique IDs of the tags assigned to the short link.

tagNamesstring | string[]#

The unique name of the tags assigned to the short link (case insensitive).

commentsstring | null#

The comments for the short link.

expiresAtstring | null#

The date and time when the short link will expire at.

expiredUrlstring | null#

The URL to redirect to when the short link has expired.

passwordstring | null#

The password required to access the destination URL of the short link.

proxyboolean#

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

Default: false

titlestring | null#

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

descriptionstring | null#

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

imagestring | null#

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

videostring | null#

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewriteboolean#

Whether the short link uses link cloaking. Defaults to false if not provided.

Default: false

iosstring | null#

The iOS destination URL for the short link for iOS device targeting.

androidstring | null#

The Android destination URL for the short link for Android device targeting.

geoobject#

Geographic targeting for the short link. Allows you to redirect users based on their location.

doIndexboolean#

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

Default: false

utm_sourcestring | null#

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.

utm_mediumstring | null#

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.

utm_campaignstring | null#

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.

utm_termstring | null#

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.

utm_contentstring | null#

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.

refstring | null#

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.

webhookIdsstring[] | null#

An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

testVariantsobject[]#

An array of A/B test URLs and the percentage of traffic to send to each URL. Requires 2-4 variants with percentages between 10-90.

testStartedAtstring | null#

The date and time when the tests started.

testCompletedAtstring | null#

The date and time when the tests were or will be completed.

tagIdstring | null#

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link.

Optionally, you can also pass an externalId field to associate the link with a unique identifier in your own system.

index.php

use Dub\Models\Operations;class LinkController extends Controller{    public function createLinkWithExternalId()    {        $dub = new Dub();        try {            $request = new Operations\CreateLinkRequestBody(                url: 'https://google.com',                externalId: '12345'            );            $response = $dub->links->create($request);            if ($response->linkSchema !== null) {                // handle response            }        } catch (Throwable $e) {            // handle exception        }    }}

This will let you easily update the link or retrieve analytics for it later on using the externalId instead of the Dub linkId.

4. Upsert link#

The Dub Laravel SDK provides a method to upsert a link – where an existing link is updated if it exists, or a new link is created if it doesn't.

index.php

use Dub\Models\Operations;class LinkController extends Controller{    public function upsertLink()    {        $dub = new Dub();        try {            $request = new Operations\UpsertLinkRequestBody(                url: 'https://google.com'            );            $response = $dub->links->upsert($request);            if ($response->linkSchema !== null) {                // handle response            }        } catch (Throwable $e) {            // handle exception        }    }}

This way, you won't have to worry about checking if the link already exists when you're creating it.

5. Update link#

To update an existing link using the Dub Laravel SDK, you can either use the link's linkId or externalId.

index.php

use Dub\Models\Operations;class LinkController extends Controller{    public function updateLink()    {        $dub = new Dub();        try {            $request = new Operations\UpdateLinkRequest();            $request->linkId = 'cly2p8onm000cym8200nfay7l';            $request->requestBody = new Operations\UpdateLinkRequestBody();            $request->requestBody->url = 'https://google.us';            $response = $dub->links->update($request);            if ($response->linkSchema !== null) {                echo $response->linkSchema->shortLink;            }        } catch (Throwable $e) {            // handle exception        }    }}

6. Retrieve analytics for link#

You can also retrieve analytics for a link using the Dub Laravel SDK.

index.php

use Dub\Models\Operations;class LinkController extends Controller{    public function retrieveAnalytics()    {        $dub = new Dub();        try {            $request = new Operations\RetrieveAnalyticsRequest();            $request->linkId = 'clmnr6jcc0005l308q9v56uz1';            $request->interval = Operations\Interval::SevenD;            $request->groupBy = Operations\GroupBy::Timeseries;            $response = $dub->analytics->retrieve($request);            if ($response->oneOf !== null) {                // Handle the response                print_r($response->oneOf);            }        } catch (Throwable $e) {            // handle exception        }    }}

7. Examples#

Laravel Example

See the full example on GitHub.