Introduction

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

Initialize

Initialize the Dub PHP SDK by creating a new instance of the Dub class.

index.php

declare(strict_types=1);

require 'vendor/autoload.php';

use Dub\Dub;
use Dub\Models\Components;

$dub = Dub::builder()->setSecurity("DUB_API_KEY")->build();

3. Create link

Let’s create a short link using the Dub PHP SDK.

index.php

use Dub\Models\Operations;

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 which is a unique identifier for the link in your own database to associate it with the link in Dub’s system.

index.php

use Dub\Models\Operations;

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

Dub PHP 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. so you don’t have to worry about checking if the link already exists.

index.php

use Dub\Models\Operations;

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

Let’s update an existing link using the Dub PHP SDK. You can do that in two ways:

Using the link’s linkId in Dub’s system.
Using the link’s externalId in your own database (prefixed with ext_).

index.php

use Dub\Models\Operations;

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

Let’s retrieve analytics for a link using the Dub PHP SDK.

index.php

use Dub\Models\Operations;

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

PHP Example

See the full example on GitHub.

GETTING STARTED

CONCEPTS

INTEGRATIONS

OPEN SOURCE

Introduction

1. Prerequisites

2. Install and initialize the Dub PHP SDK

Install

Initialize

3. Create link

4. Upsert link

5. Update link

6. Retrieve analytics for link

7. Examples

PHP Example

​1. Prerequisites

​2. Install and initialize the Dub PHP SDK

Install

Initialize

​3. Create link

​4. Upsert link

​5. Update link

​6. Retrieve analytics for link

​7. Examples

PHP 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