Implementing a new provider

This project aims to be compatible with as many registrars as possible, giving users a choice when creating a Connector.

Adding a new Provider is straightforward. Simply follow the steps below.

This guide explains how to add support for a new domain registrar. You’ll implement both the Backend (Provider logic) and the Frontend (configuration form).

Prerequisites

Read the API documentation of the new Provider and identify the sections related to user authentication and domain name registration.
Set up your development environment.
Manual Installation Install the project from source to begin development

Backend

In this section, you’ll implement the logic required to interact with the new Provider’s API.

Create a new DTO class to validate user authentication data.
- Directorysrc
  - DirectoryDto.Connector
    DefaultProviderDto.php default DTO, which will also be used
    MySuperRegistrarProviderDto.php your new DTO class
    …
Add the necessary class properties and assertions. The DTO class must extend DefaultProviderDto.

Only include properties required for user authentication, domain name registration, and any legally required consents.
MySuperRegistrarProviderDto.php
```
namespace App\Dto\Connector;

   class MySuperRegistrarProviderDto extends DefaultProviderDto
```
Create a new Provider class.
- Directorysrc
  - DirectoryService
    DirectoryProvider
    AbstractProvider.php defines the signature of methods
    MySuperRegistrarProvider.php your new Provider
    …

The class must extend AbstractProvider. Refer to the existing Providers for implementation examples.

namespace App\Service\Provider;

#[Autoconfigure(public: true)]
class MySuperRegistrarProvider extends AbstractProvider
{
   protected string $dtoClass = MySuperRegistrarProviderDto::class;

   /** @var MySuperRegistrarProviderDto */
   protected DefaultProviderDto $authData;

Implement the assertAuthentication method.

This method validates user authentication data. Make a request to the Provider’s API to verify that the user’s credentials are valid.

The method must return void when authentication succeeds.

If an issue occurs, throw an appropriate exception from the App\Exception\Provider namespace.
MySuperRegistrarProvider.php
```
protected function assertAuthentication(): void
{
   // TODO: Implement assertAuthentication() method.
}
```
Implement the getCachedTldList method.
MySuperRegistrarProvider.php
```
protected function getCachedTldList(): CacheItemInterface
{
   return $this->cacheItemPool->getItem('app.provider.my-super-registrar.supported-tld');
}
```
This method returns the cache entry holding the list of TLDs supported by this Provider. Even if the API does not currently provide this information, implement the method for future compatibility.
Implement the getSupportedTldList method.

If the Provider API does not offer a way to retrieve supported TLDs, return an empty array []. Otherwise, call the API and return the list of supported TLDs.
MySuperRegistrarProvider.php
```
protected function getSupportedTldList(): array
{
   // TODO: Implement getSupportedTldList() method.
}
```
Implement the isSupported method (if necessary). Override isSupported only if the Provider API cannot list supported TLDs. In that case, return true to indicate that all TLDs are potentially valid.
Implement the orderDomain method.

Follow the Provider’s API documentation to implement domain ordering using the required properties.

As with authentication, you may throw generic Provider exceptions in case of an error.
MySuperRegistrarProvider.php
```
public function orderDomain(Domain $domain, bool $dryRun): void
{
   // TODO: Implement orderDomain() method.
}
```

Add your Provider to the ConnectorProvider enumeration.

namespace AppConfig;

enum ConnectorProvider: string
{
   // ...
   case MY_SUPER_REGISTRAR = 'my-super-registrar';

   public function getConnectorProvider(): string
   {
       return match ($this) {
           // ...
           ConnectorProvider::MY_SUPER_REGISTRAR => MySuperRegistrarProvider::class,
   };
}

Well done! 🎉

You have now completed the Backend implementation. Let’s continue with the Frontend! 🚀

Frontend

Create a form containing the necessary fields for your Provider.
- Directoryassets
  - Directoryutils
    Directoryproviders
    Directoryforms
    DefaultConnectorFormItems.tsx fields shared by all
    MySuperRegistrarConnectorForm.tsx
    …
Add the fields corresponding to the DTO you created earlier. Check existing forms for reference. If the Provider API does not allow retrieving supported TLDs, display this information as in the other forms.
Add your Provider to the ConnectorProvider enumeration. The value must exactly match the one defined in PHP.
assets/utils/api/connectors.ts
```
export enum ConnectorProvider {
   // ...
   MY_SUPER_REGISTRAR = 'my-super-registrar'
}
```

Add the API terms of service link and the reference to your new form in the index.ts configuration file.

export const providersConfig: Record<ConnectorProvider, ProviderConfig> = {
   // ...
   [ConnectorProvider.MY_SUPER_REGISTRAR]: {
       tosLink: 'https://...',
       form: MySuperRegistrarConnectorForm
   }
}

Ensure the interface renders correctly and fix any display issues.

Great job! 🎉

Your Frontend implementation is now complete.

Testing

Add the corresponding test function in the Provider test collection.

#[DependsExternal(RDAPServiceTest::class, 'testUpdateRdapServers')]
public function testMySuperRegistrar()
{
   $token = static::getContainer()->getParameter('my_super_registrar_token');
   if (!$token) {
       $this->markTestSkipped('Missing My Super Registrar token');
   }

   $this->testGenericProvider(ConnectorProvider::MY_SUPER_REGISTRAR, [
       'waiveRetractationPeriod' => true,
       'acceptConditions' => true,
       'ownerLegalAge' => true,
       'token' => $token,
   ]);
}

Create a Symfony configuration parameter connecting the environment variable to the credentials.
Run the tests with PHPUnit:
Terminal window
```
php vendor/bin/phpunit
```
Ensure the test passes. If it fails, fix the implementation accordingly. Consider enabling code coverage to identify executed sections.

That’s it!

You’ve now finished implementing a new Provider. ✨