Laravel

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

string

required

The destination URL of the short link.

string

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).

string

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

number

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.

string | 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.

string | 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.

string | null

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

string | null

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

string | null

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

string

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.

boolean

default:false

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

string | 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.

boolean

default:false

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

boolean

default:false

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

string | string[]

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

string | string[]

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

string | null

The comments for the short link.

string | null

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

string | null

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

string | null

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

boolean

default:false

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

string | 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

string | 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

string | 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

string | 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

boolean

default:false

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

string | null

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

string | null

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

object

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

boolean

default:false

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

string | null

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

string | null

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

string | null

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

string | null

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

string | null

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

string | null

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

string[] | null

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

object[]

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.

string | null

The date and time when the tests started.

string | null

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

string | 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.

GETTING STARTED

CONCEPTS

INTEGRATIONS

OPEN SOURCE

1. Prerequisites

2. Install and initialize the Dub PHP SDK

Install

Configuration

Initialize

Service Container (Optional)

3. Create link

4. Upsert link

5. Update link

6. Retrieve analytics for link

7. Examples

Laravel Example

​1. Prerequisites

​2. Install and initialize the Dub PHP SDK

Install

Configuration

Initialize

Service Container (Optional)

​3. Create link

​4. Upsert link

​5. Update link

​6. Retrieve analytics for link

​7. Examples

Laravel Example

1. Prerequisites

2. Install and initialize the Dub PHP SDK

3. Create link

4. Upsert link

5. Update link

6. Retrieve analytics for link

7. Examples