Domainator9K Core Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to your Symfony/Laravel project via Composer:

   composer require district09/domainator9k-core-bundle
   

   Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   return [
       // ...
       District09\Domainator9kCoreBundle\Domainator9kCoreBundle::class => ['all' => true],
   ];
   

2. First Use Case: Domain Validation Inject the DomainValidator service into a controller or service:

   use District09\Domainator9kCoreBundle\Validator\DomainValidator;
   
   class DomainController extends Controller
   {
       public function __construct(private DomainValidator $validator) {}
   
       public function validateDomain(Request $request)
       {
           $domain = $request->input('domain');
           $isValid = $this->validator->validate($domain);
   
           return response()->json(['valid' => $isValid]);
       }
   }
   

3. Key Entry Points

   • Validator: DomainValidator for basic domain checks (syntax, TLD, etc.).
   • Parser: DomainParser to extract components (e.g., subdomain, TLD).
   • Config: Check config/packages/district09_domainator9k_core.yaml for custom rules.

Implementation Patterns

Core Workflows

1. Domain Validation in Forms Use the validator in a Laravel Form Request or Symfony Validator constraint:

   use District09\Domainator9kCoreBundle\Validator\Constraints\ValidDomain;
   
   class StoreDomainRequest extends FormRequest
   {
       public function rules()
       {
           return [
               'domain' => ['required', new ValidDomain()],
           ];
       }
   }
   

2. Domain Parsing for Business Logic Extract domain components (e.g., for routing or analytics):

   $parser = app(DomainParser::class);
   $parts = $parser->parse('sub.example.co.uk');
   // Returns: ['sub' => 'sub', 'domain' => 'example', 'tld' => 'co.uk']
   

3. Custom Rules Extend the validator with custom logic (e.g., blocklist):

   $validator = app(DomainValidator::class);
   $validator->addRule(function ($domain) {
       return !in_array($domain, ['blocked.com', 'spam.org']);
   });
   

4. Integration with Eloquent Add a custom accessor to a model:

   class Website extends Model
   {
       public function getDomainAttribute($value)
       {
           $validator = app(DomainValidator::class);
           return $validator->validate($value) ? $value : null;
       }
   }
   

Laravel-Specific Tips

• Service Provider: Bind the bundle’s services in AppServiceProvider:

  public function register()
  {
      $this->app->bind(DomainValidator::class, function ($app) {
          return new \District09\Domainator9kCoreBundle\Validator\DomainValidator();
      });
  }
  

• API Responses: Use the validator in API resources:

  public function toArray($request)
  {
      return [
          'domain' => $this->validator->validate($this->domain),
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity The validator treats domains as case-insensitive by default. Override with:

   $validator->setCaseSensitive(true);
   

2. IDN (Internationalized Domain Names) Ensure UTF-8 support is enabled in your PHP environment. The bundle may not handle IDNs (e.g., 例.测试) out of the box.

3. Performance Avoid parsing domains in loops without caching. Store parsed results in a temporary cache:

   Cache::remember("domain_{$domain}", 3600, function() use ($parser, $domain) {
       return $parser->parse($domain);
   });
   

4. Deprecated Methods Check the changelog for breaking changes (e.g., DomainValidator::check() may be renamed to validate() in future versions).

Debugging

• Enable Verbose Logging Configure the bundle to log validation steps:

  # config/packages/district09_domainator9k_core.yaml
  domainator9k_core:
      debug: true
  

  Logs will appear in storage/logs/laravel.log.

• Test Edge Cases Common failure points:

  • example..com (double dot)
  • example.c (single-letter TLD)
  • example.local (pseudo-TLD)

Extension Points

1. Custom Validators Implement District09\Domainator9kCoreBundle\Validator\DomainValidatorInterface:

   class CustomValidator implements DomainValidatorInterface
   {
       public function validate($domain): bool
       {
           // Custom logic
       }
   }
   

   Register it as a service alias:

   services:
       District09\Domainator9kCoreBundle\Validator\DomainValidatorInterface: '@App\Validator\CustomValidator'
   

2. Hooks for Parsing Extend DomainParser by subclassing and overriding parse():

   class ExtendedParser extends DomainParser
   {
       protected function parse($domain)
       {
           $result = parent::parse($domain);
           // Modify $result as needed
           return $result;
       }
   }
   

3. Event Listeners Dispatch events for domain actions (e.g., DomainValidatedEvent):

   $validator->validate($domain)->then(function ($result) {
       event(new DomainValidatedEvent($domain, $result));
   });
   

Config Quirks

• Default Rules The bundle ships with default rules (e.g., max length, allowed characters). Override them in config:

  domainator9k_core:
      rules:
          max_length: 253
          allowed_chars: '[a-zA-Z0-9\-\.]'
  

• TLD List The bundle uses a static TLD list. Update it via:

  $validator->setTldList(['com', 'org', 'custom']);