> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain registrars

> Connect Spartan to a domain registrar. Core owns the domain, billing and pages. Your module translates calls into the registrar API.

![Core, RegistrarManager, your Registrar class, the registrar API](https://mintcdn.com/dezerx/dVNBM3sq4VCh7CKa/public/extensions/registrars/top.webp?fit=max\&auto=format\&n=dVNBM3sq4VCh7CKa\&q=85\&s=784a0f28079e582da2acdf9e5d6a1eae)

Namecheap ships today. Read [Fundamentals](https://docs.dezerx.com/extensions/tutorials/fundamentals.md) first.

## Build it

**1. Generate**

```bash theme={null}
php artisan make:module DomainSilo --type=registrar
```

This creates `Modules/DomainRegistrars/DomainSiloRegistrar` with `"category": "registrar"`, a provider extending `RegistrarModuleServiceProvider`, the thin service classes core looks up and a `Services/Registrar.php` stub.

**2. Implement Registrar**

Fill in the methods that throw `not implemented yet`. The class name and namespace are fixed, because `RegistrarManager` resolves `Modules\{Module}\Services\Registrar`.

**3. Enable and check**

```bash theme={null}
php artisan module:enable DomainSiloRegistrar
php artisan module:migrate DomainSiloRegistrar
php artisan octane:reload
php artisan module:doctor DomainSiloRegistrar
```

**4. Set prices**

Enter or import TLD prices on the domain pricing page in the admin, and pick a default registrar if you run more than one.

## A small complete example

```php app/Services/Registrar.php theme={null}
namespace Modules\DomainSiloRegistrar\Services;

use App\Domains\AbstractRegistrar;
use App\Domains\Capability;
use App\Domains\Data\Availability;
use App\Domains\Data\DomainInfo;
use App\Domains\Data\RegistrationRequest;
use App\Domains\Data\RegistrationResult;
use App\Domains\Data\RenewalResult;
use App\Domains\RegistrarException;
use Carbon\CarbonImmutable;
use Illuminate\Support\Facades\Http;
use Modules\DomainSiloRegistrar\Models\DomainSiloCredential;

class Registrar extends AbstractRegistrar
{
    public function key(): string
    {
        return 'domainsilo';
    }

    public function displayName(): string
    {
        return 'DomainSilo';
    }

    public function capabilities(): array
    {
        return [Capability::Availability, Capability::Register, Capability::Renew, Capability::Sync];
    }

    public function isConfigured(): bool
    {
        return DomainSiloCredential::query()->exists();
    }

    private function api(): \Illuminate\Http\Client\PendingRequest
    {
        $c = DomainSiloCredential::firstOrFail();

        return Http::withToken($c->api_key)->baseUrl($c->url)->timeout(30);
    }

    public function checkAvailability(array $domains): array
    {
        $response = $this->api()->post('/v1/check', ['domains' => $domains]);

        if ($response->failed()) {
            throw RegistrarException::connection('DomainSilo availability check failed');
        }

        $result = [];

        foreach ($response->json('results') as $row) {
            $result[$row['domain']] = new Availability($row['domain'], (bool) $row['available']);
        }

        return $result;
    }

    public function register(RegistrationRequest $request): RegistrationResult
    {
        $response = $this->api()->post('/v1/register', [
            'domain' => $request->domain->ascii,
            'years' => $request->years,
        ]);

        if ($response->failed()) {
            throw RegistrarException::rejected($response->json('message', 'Registration rejected'));
        }

        return new RegistrationResult(
            completed: true,
            registrarReference: (string) $response->json('id'),
            expiryDate: CarbonImmutable::parse($response->json('expires')),
        );
    }

    public function renew(string $domain, int $years, array $options = []): RenewalResult
    {
        $response = $this->api()->post("/v1/domains/{$domain}/renew", ['years' => $years]);

        if ($response->failed()) {
            throw RegistrarException::rejected($response->json('message', 'Renewal rejected'));
        }

        return new RenewalResult(renewed: true, expiryDate: CarbonImmutable::parse($response->json('expires')));
    }

    public function getInfo(string $domain): DomainInfo
    {
        $response = $this->api()->get("/v1/domains/{$domain}");

        if ($response->notFound()) {
            throw new RegistrarException('The registrar no longer holds this domain.', RegistrarException::NOT_FOUND);
        }

        return new DomainInfo(
            domain: $domain,
            status: DomainInfo::ACTIVE,
            expiryDate: CarbonImmutable::parse($response->json('expires')),
        );
    }
}
```

## Rules that matter

> [accordion] Return data, never touch core tables
>
> A registrar module never writes to `services`, `invoices` or `domains`. Return the data objects and let core save them.

> [accordion] Throw RegistrarException only
>
> `rejected()` is final and not retried. `connection($message, outcomeUnknown: true)` means the request may have arrived. Core retries it but checks `getInfo()` first, so a domain is never ordered twice. Never retry a call that costs money inside the module.

> [accordion] Declare what you support
>
> `capabilities()` lists `App\Domains\Capability` cases. Core hides buttons and skips calls for everything you leave out. Optional methods cover transfers, nameservers, lock, EPP code, ID protection, contacts, DNS records, email forwarding and TLD pricing.

> [accordion] Domains are ASCII
>
> Domains arrive as punycode. Use `App\Domains\Data\DomainName`, which knows multi label suffixes such as `co.uk`. Termination never deletes a domain at the registrar, it just stops renewing.

> [accordion] Keep only connection details in the module
>
> Store API keys encrypted and list them under `secrets` in `module.json` so the Secrets vault can see them. Default nameservers and prices are core settings.

Test with `Http::fake()`. `NamecheapRegistrar` and its Pest tests are the reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.