Provision Provider Domain Names Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and publish the config (php artisan vendor:publish --tag="<package>-config"). Most of the day-to-day surface area lives in config/<package>.php and in src/Providers/*.
• Read src/Providers/RealtimeRegister/ first. Each provider is a thin adapter around the registrar API; the surrounding manager/facade/dispatcher is where Laravel integration happens.
• Add credentials to config/services.php (or the package config) rather than .env-reading inside provider classes, and set the sandbox/base URL for local work.
• First use case: a domain registration/transfer for a .si domain through Realtime Register — check availability, build contacts, call register()/transfer() with an explicit period, and persist the resulting order/domain reference.

$registrar = DomainRegistrar::provider('realtime-register');

$registrar->register(
    domain: 'example.si',
    period: 1, // years — see gotchas on provider quirks
    contacts: $contacts,
);

Implementation Patterns

• Provider resolution per TLD. Treat the provider as a strategy: resolve by TLD (or by explicit config) and never hard-code a single provider in your controllers. Wrap the choice in a small service so swapping providers for a TLD is a config change.
• Contacts as first-class objects. Build registrant/admin/tech contacts as DTOs, then let each provider adapter map them. The .si technical-contact rule (no organization field) should be handled inside the provider adapter, not in your controller — keep the TLD-specific branching out of app code.
• Period normalization at the boundary. Pass periods as a single, documented unit (years) from your app and let the adapter translate. v2.12.90 fixes the provider to honor period on register/transfer; keep your own contract stable so future provider fixes don't ripple into your callsites.
• Wrap writes in jobs + idempotency keys. Registration and transfer are slow, billable, and stateful. Queue them, store a local DomainOrder row with a unique key, and guard against double-submits — the registrar is not your source of truth for idempotency.
• Persist provider payloads. Store the raw request/response (redacting secrets) on your order record. Provider error shapes differ wildly; the payload is your only reliable debugging artifact later.
• Fake the manager in tests. Bind a fake provider into the container for feature tests and reserve real API calls for a small, tagged integration suite against the sandbox.

// app/Services/DomainRegistration.php
public function register(string $domain, int $years): DomainOrder
{
    return DB::transaction(function () use ($domain, $years) {
        $order = DomainOrder::firstOrCreate(
            ['domain' => $domain, 'action' => 'register'],
            ['years' => $years, 'status' => 'pending'],
        );

        dispatch(new SubmitRegistration($order));

        return $order;
    });
}

Gotchas and Tips

• Period units are the classic bug. The v2.12.90 fix means older versions silently dropped or misapplied period on register/transfer. Pin the version in composer.json and add a test asserting the period actually reaches the provider payload (Http::assertSent), not just that the call succeeded.
• TLD-specific field rules. The .si technical contact no longer sends organization. If you were relying on that field being propagated (e.g., matching contacts by exact payload), your assertions or reconciliation logic may need updating. Build contacts against the adapter's rules, not a universal schema.
• Provider parity is not guaranteed. Availability checks, transfer auth codes, DNSSEC, and contact validation differ by provider and TLD. Put capability checks (supports('dnssec')) behind a small interface rather than instanceof checks scattered in controllers.
• Validate before you spend money. Normalize and validate the domain (IDN/punycode, TLD allowlist) locally; a rejected registrar call still costs latency and pollutes your order table.
• Distinguish "rejected" from "unknown". Timeouts during register are the dangerous case — reconcile against the registrar's order status before retrying, or you risk double billing.
• Config caching hides env reads. If a provider reads env() directly instead of config(), it breaks under php artisan config:cache. Confirm your credentials land in config files.
• Log the provider, not just the error. Add the provider name, endpoint, and TLD to log context; when a single TLD breaks, you want to grep for it without correlating order IDs by hand.
• Sandbox first, and record fixtures. Keep a tests/Fixtures/realtime-register/*.json set of real sandbox responses and replay them in unit tests — this is the cheapest way to catch the next provider-side quirk like the period fix.