stitch-digital/nametodomain-php-sdk

An SDK to easily work with the Name To Domain API

1.0.0 2026-01-16 17:25 UTC

Requires

• php: ^8.1
• saloonphp/pagination-plugin: ^2.2
• saloonphp/saloon: ^3.14

Requires (Dev)

• laravel/pint: ^1.0
• pestphp/pest: ^2.35|^3.8.2
• phpstan/phpstan: ^2.1
• vlucas/phpdotenv: ^5.6.2

MIT

• John Trickett

• api
• sdk
• domain
• nametodomain

README

This package is the official PHP SDK for the Name To Domain API, built with Saloon v3.

use NameToDomain\PhpSdk\NameToDomain;

// Single resolution
$result = NameToDomain::make($token)->resolve(
    company: 'Stitch Digital',
    country: 'GB'
);

// Create batch job
$job = NameToDomain::make($token)->createJob(
    items: [
        ['company' => 'Stripe', 'country' => 'US'],
        ['company' => 'Spotify', 'country' => 'SE'],
    ]
);

Behind the scenes, the SDK uses Saloon to make the HTTP requests.

Installation

composer require stitch-digital/nametodomain-php-sdk

To get started, we highly recommend reading the Name To Domain API documentation.

Quick Start

use NameToDomain\PhpSdk\NameToDomain;

// Single resolution
$result = NameToDomain::make($token)->resolve(
    company: 'Stitch Digital',
    country: 'GB'
);

// Create batch job
$job = NameToDomain::make($token)->createJob(
    items: [
        ['company' => 'Stripe', 'country' => 'US'],
        ['company' => 'Spotify', 'country' => 'SE'],
    ]
);

// Check job status
$jobStatus = NameToDomain::make($token)->job(jobId: $job->id);

// Get all job items
$items = NameToDomain::make($token)->jobItems(jobId: $job->id)->collect()->all();

Usage

To authenticate, you'll need an API token. You can create one in the API Dashboard at Name To Domain.

use NameToDomain\PhpSdk\NameToDomain;

$client = NameToDomain::make('your-api-token');

Setting a timeout

By default, the SDK will wait for a response from Name To Domain for 10 seconds. You can change this by passing a requestTimeout option:

$client = NameToDomain::make(
    apiToken: 'your-api-token',
    requestTimeout: 30
);

Handling errors

The SDK will throw an exception if the API returns an error. For validation errors, the SDK will throw a ValidationException.

try {
    $client->resolve(company: '', country: 'US');
} catch (\NameToDomain\PhpSdk\Exceptions\ValidationException $exception) {
    $exception->getMessage(); // returns a string describing the errors
    
    $exception->getErrors(); // returns an array with all validation errors
    $exception->getErrorsForField('company'); // get errors for a specific field
}

For all other errors, the SDK will throw a \NameToDomain\PhpSdk\Exceptions\NameToDomainException.

try {
    $client->job(jobId: 'invalid-id');
} catch (\NameToDomain\PhpSdk\Exceptions\NameToDomainException $exception) {
    $exception->getMessage();
    $exception->response; // access the Saloon Response object for debugging
}

Resolve

The resolve endpoint allows you to resolve a single company name to its official website domain with a confidence score.

Resolve a company

You can use the resolve method to resolve a company name and country code to its domain.

$result = NameToDomain::make($token)->resolve(
    company: 'Stitch Digital',
    country: 'GB'
);

The response includes the original input and the resolution result. If no reliable match is found, the domain and confidence will be null.

Resolve with idempotency key

You can include an idempotency key to safely retry requests:

$result = NameToDomain::make($token)->resolve(
    company: 'Stripe',
    country: 'US',
    idempotencyKey: 'my-unique-idempotency-key'
);

Jobs

Jobs allow you to process multiple company resolutions in batch.

Creating a job

You can use the createJob method to create a batch job.

$records = [
    ['company' => 'Stripe', 'country' => 'US'],
    ['company' => 'Spotify', 'country' => 'SE'],
];

$job = NameToDomain::make($token)->createJob(
    items: $records
);

Creating a job with idempotency key

You can include an idempotency key to safely retry job creation:

$job = NameToDomain::make($token)->createJob(
    items: [
        ['company' => 'Stripe', 'country' => 'US'],
    ],
    idempotencyKey: 'my-unique-idempotency-key'
);

Getting a single job

You can use the job method to get a single job and check its status.

$jobId = '01KF3TH8MCBFAZ98MFYB6TS63H';

$job = NameToDomain::make($token)->job(jobId: $jobId);

Getting job items

The jobItems method returns a Saloon Paginator instance, giving you full flexibility in how you consume the paginated results. This leverages Saloon's powerful pagination features.

Iterating over items

The simplest way to get all job items is to iterate over them using the items() method:

$paginator = NameToDomain::make($token)->jobItems(jobId: $jobId);

foreach ($paginator->items() as $item) {
    // $item is a NameToDomain\PhpSdk\Dto\JobItem
    if ($item->result && $item->result['domain']) {
        echo "{$item->input['company']}: {$item->result['domain']}\n";
    }
}

Using Laravel Collections

If you're using Laravel (or have illuminate/collections installed), you can use the collect() method to get a LazyCollection:

// Get all items as an array
$items = NameToDomain::make($token)
    ->jobItems(jobId: $jobId)
    ->collect()
    ->all();

// Use collection methods for filtering, mapping, etc.
$domains = NameToDomain::make($token)
    ->jobItems(jobId: $jobId)
    ->collect()
    ->filter(fn($item) => $item->result && $item->result['domain'])
    ->map(fn($item) => $item->result['domain'])
    ->all();

The LazyCollection is memory-efficient and only loads one page at a time, making it perfect for processing large batches.

Iterating over responses

You can also iterate directly over the paginator to get each page as a Saloon Response:

$paginator = NameToDomain::make($token)->jobItems(jobId: $jobId);

foreach ($paginator as $response) {
    $status = $response->status();
    $data = $response->json();
    // Process each page's response
}

Custom pagination parameters

You can specify the starting page and items per page:

$paginator = NameToDomain::make($token)->jobItems(
    jobId: $jobId,
    page: 2,
    perPage: 100
);

Job item structure

Each job item includes the original input, processing status, and result:

foreach ($paginator->items() as $item) {
    // $item is a NameToDomain\PhpSdk\Dto\JobItem
    // Structure:
    // $item->id => '01HQJXK8N4ABCD1234567890XY' (or null if not available)
    // $item->input => ['company' => 'Stripe', 'country' => 'US']
    // $item->status => NameToDomain\PhpSdk\Enums\JobItemStatus
    // $item->result => ['company_normalized' => '...', 'domain' => '...', 'confidence' => 98] (or null)
    // $item->errorMessage => null (or error message if failed)
    // $item->processedAt => '2026-01-16T16:34:45+00:00' (or null)
    
    echo "Status: {$item->status->value}\n";
    
    if ($item->result) {
        echo "Domain: {$item->result['domain']}\n";
        echo "Confidence: {$item->result['confidence']}\n";
    }
    
    if ($item->errorMessage) {
        echo "Error: {$item->errorMessage}\n";
    }
}

Pagination

The SDK uses Saloon's pagination plugin to handle paginated responses. The jobItems() method returns a Paginator instance that provides several ways to consume the results.

Why use a Paginator?

Saloon's paginators are memory-efficient - they only keep one page in memory at a time. This means you can iterate through thousands of pages and millions of results without running out of memory.

Available methods

items() - Iterate over individual items

Returns a generator that yields each JobItem DTO across all pages:

$paginator = NameToDomain::make($token)->jobItems(jobId: $jobId);

foreach ($paginator->items() as $item) {
    // Process each JobItem
    echo $item->result['domain'];
}

collect() - Get a LazyCollection

Returns a Laravel LazyCollection (requires illuminate/collections):

// Get all items as an array
$allItems = $paginator->collect()->all();

// Use collection methods
$domains = $paginator->collect()
    ->filter(fn($item) => $item->result && $item->result['domain'])
    ->map(fn($item) => $item->result['domain'])
    ->values()
    ->all();

Direct iteration - Get each page as a Response

Iterate directly over the paginator to get each page:

foreach ($paginator as $response) {
    $items = $response->dto(); // Get items from this page
    // Process the page
}

Advanced pagination features

For more advanced pagination features like asynchronous pagination, request pooling, and custom pagination logic, see the Saloon pagination documentation.

Using Saloon requests directly

This SDK uses Saloon to make the HTTP requests. Instead of using the NameToDomain class, you can use the underlying request classes directly. This way, you have full power to customize the requests.

use NameToDomain\PhpSdk\NameToDomain;
use NameToDomain\PhpSdk\Requests\Resolve\ResolveRequest;

$client = NameToDomain::make('your-api-token');
$request = ResolveRequest::make('Stripe', 'US');

// Get raw response from the Name To Domain API
$response = $client->send($request)->json();

// Or get the DTO directly
$response = $client->send($request)->dto();

Take a look at the Saloon documentation to learn more about how to customize the requests.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• John Trickett
• Stitch Digital

License

The MIT License (MIT). Please see License File for more information.