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

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