Aliases

An alias in Siren is a code that identifies a collaborator in tracking links, coupon systems, or other attribution mechanisms. When a customer clicks ?ref=JNE, Siren resolves JNE to a collaborator through the alias system. When a coupon code is applied at checkout, the same system connects that code to a collaborator.

Aliases are scoped by type. A “tracking” alias is the code in referral URLs. A “coupon” alias is a promotional code bound to a collaborator. The system is extensible, so extensions can register additional types.

Every alias record carries an issued date. When a collaborator’s code changes, Siren doesn’t overwrite the old record — it creates a new one with a later timestamp. This means old links and codes continue to resolve correctly, and the system can reconstruct who owned a given code at any point in history.

Aliases are created automatically when collaborators are created, and updated through the collaborator REST API. If you find yourself writing code that creates alias records directly, consider whether the collaborator create/update endpoints would be more appropriate. Direct datastore access is primarily useful for reading alias data and for migration scripts.

Accessing alias data

The alias datastore is available through dependency injection or the static facade. Dependency injection is preferred for extension code wired through an initializer. The facade is convenient for standalone scripts, theme files, or other code running outside Siren’s container.

use Siren\Collaborators\Core\Datastores\CollaboratorAliases\Interfaces\CollaboratorAliasesDatastore;

class ReferralLinkService
{
    protected CollaboratorAliasesDatastore $aliases;

    public function __construct(CollaboratorAliasesDatastore $aliases)
    {
        $this->aliases = $aliases;
    }

    public function getTrackingCode(int $collaboratorId): ?string
    {
        try {
            $alias = $this->aliases->getAliasForCollaborator($collaboratorId, 'tracking');
            return $alias->getCode();
        } catch (\PHPNomad\Datastore\Exceptions\RecordNotFoundException $e) {
            return null;
        }
    }
}

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

$alias = CollaboratorAliases::getAliasByCode('JNE', 'tracking');
$collaboratorId = $alias->getCollaboratorId();

The alias model

Each alias record is represented by an Alias model instance.

Getter methods: getCode(), getType(), getCollaboratorId(), getIssuedDate().

The primary key is a compound of all four fields, which allows the same code to exist for different types and the same collaborator to have multiple historical records of the same type.

Looking up an alias by code

getAliasByCode(string $code, string $type, ?DateTime $before = null) finds the alias record matching a specific code and type. Since the same code can be reassigned over time, this returns the most recently issued match. Pass a DateTime to the $before parameter to find who owned the code at that point in history. Throws RecordNotFoundException if no matching alias exists.

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

// Who currently owns this tracking code?
$alias = CollaboratorAliases::getAliasByCode('JNE', 'tracking');
$collaboratorId = $alias->getCollaboratorId();

// Who owned it on January 1st?
$historicalAlias = CollaboratorAliases::getAliasByCode(
    'JNE',
    'tracking',
    new DateTime('2025-01-01')
);

Getting a collaborator’s current alias

getAliasForCollaborator(int $id, string $type, ?DateTime $before = null) retrieves the alias of a given type for a specific collaborator. Returns the most recently issued alias of that type. Like getAliasByCode, the $before parameter supports historical lookups. Throws RecordNotFoundException if the collaborator has no alias of that type.

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

// Get current tracking code
$alias = CollaboratorAliases::getAliasForCollaborator(12, 'tracking');
echo $alias->getCode(); // e.g. "JNE"

// Get coupon alias
$couponAlias = CollaboratorAliases::getAliasForCollaborator(12, 'coupon');
echo $couponAlias->getCode(); // e.g. "JANE20"

How aliases are generated

When a collaborator is created, a GenerateCollaboratorTrackingAlias listener fires and generates a unique tracking code automatically. The code generator produces consonant-only strings (from the set B, C, D, G, H, J, K, L, P, R, T, V, Z) to avoid accidentally spelling words. The length is calculated based on the number of existing aliases to minimize collisions.

The minimum code length is configurable via the collaborators.config.minimumTrackingIdLength config value. The AliasGenerator interface can be replaced through the DI container if you need a different generation strategy.

You can also provide a custom tracking code when creating or updating a collaborator through the REST API by passing the trackingId field. If the code is already taken, the API returns an error.

How aliases are used in the attribution pipeline

Aliases connect customer actions to collaborators at two points in the pipeline.

When a customer visits a URL containing the referral parameter (default ?ref=CODE), the CollaboratorFromUrl locator extracts the code and calls getAliasByCode(code, 'tracking') to resolve the collaborator. The config key collaborator.urlReference.key controls the parameter name.

When a customer applies a coupon code and the BoundCouponUsed engagement trigger is active, the CollaboratorFromAlias locator calls getAliasByCode(code, 'coupon') to find the associated collaborator. If a match is found, an engagement is created for the collaborator’s active programs.

Practical examples

Building a referral link for a collaborator

use Siren\Collaborators\Core\Facades\CollaboratorAliases;
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;

function getReferralUrl(int $collaboratorId, string $baseUrl): ?string
{
    try {
        $alias = CollaboratorAliases::getAliasForCollaborator($collaboratorId, 'tracking');
        return $baseUrl . '?ref=' . $alias->getCode();
    } catch (RecordNotFoundException $e) {
        return null;
    }
}

Checking if a coupon code is linked to a collaborator

use Siren\Collaborators\Core\Facades\CollaboratorAliases;
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;

function getCollaboratorForCoupon(string $couponCode): ?int
{
    try {
        $alias = CollaboratorAliases::getAliasByCode($couponCode, 'coupon');
        return $alias->getCollaboratorId();
    } catch (RecordNotFoundException $e) {
        return null;
    }
}

Querying all aliases for a collaborator

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

$allAliases = CollaboratorAliases::andWhere([
    ['column' => 'collaboratorId', 'operator' => '=', 'value' => 12]
], null, null, 'dateIssued', 'DESC');

foreach ($allAliases as $alias) {
    echo $alias->getType() . ': ' . $alias->getCode() . ' (issued ' . $alias->getIssuedDate()->format('Y-m-d') . ')' . PHP_EOL;
}