Psl Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require azjezz/psl:^6.2.1
   

   The package provides a Public Suffix List (PSL) parser and validator, enabling domain parsing and validation (e.g., extracting example.com from sub.example.com.co.uk). Note: This release includes security fixes for the Psl\H2 component, which does not affect core PSL functionality unless you directly use Psl\H2\ServerConnection.

2. First Use Case: Parse a domain to extract its registered domain (e.g., google.com from mail.google.com):

   use Azjezz\Psl\Psl;
   
   $psl = new Psl();
   $domain = 'sub.example.co.uk';
   $registeredDomain = $psl->parse($domain); // Returns 'example.co.uk'
   

3. Key Classes:

   • Psl: Core class for parsing/validating domains (unchanged).
   • Psl\Exception\InvalidDomainException: Thrown for invalid domains (e.g., example..com).
   • Preloaded PSL: Updated via composer update (no breaking changes to core PSL logic).

4. Where to Look First:

   • PSL Documentation.
   • tests/ for usage examples (e.g., DomainParserTest.php).
   • src/Psl.php for API reference.
   • Security Note: If using Psl\H2\ServerConnection, review the security advisory.

Implementation Patterns

Core Workflows

1. Domain Parsing (Unchanged):

   $psl = new Psl();
   $result = $psl->parse('sub.domain.co.jp'); // Returns 'domain.co.jp'
   

   • Edge Cases: Handles international domains (IDNs) and private TLDs (e.g., .test).
   • Output: Returns a string (registered domain) or null for invalid domains.

2. Validation (Unchanged):

   try {
       $psl->validate('invalid..domain.com'); // Throws InvalidDomainException
   } catch (\Azjezz\Psl\Exception\InvalidDomainException $e) {
       // Handle invalid domain
   }
   

3. Integration with Laravel (Unchanged):

   • Request Validation:

     use Illuminate\Support\Facades\Validator;
     
     $validator = Validator::make($request->all(), [
         'domain' => ['required', function ($attribute, $value, $fail) {
             $psl = new Psl();
             if (!$psl->validate($value)) {
                 $fail('The '.$attribute.' must be a valid domain.');
             }
         }]
     ]);
     

   • Middleware:

     public function handle($request, Closure $next) {
         $psl = new Psl();
         if (!$psl->validate($request->domain)) {
             abort(400, 'Invalid domain');
         }
         return $next($request);
     }
     

4. Batch Processing (Unchanged):

   $domains = ['example.com', 'sub.test', 'invalid..domain'];
   $psl = new Psl();
   $results = array_map([$psl, 'parse'], $domains);
   // $results = ['example.com', 'test', null]
   

5. Custom PSL Updates (Unchanged):

   • Replace the default PSL file:

     $psl = new Psl('/path/to/custom/psl.txt');
     

New: HTTP/2 Security Considerations

If your application directly uses Psl\H2\ServerConnection (e.g., for custom HTTP/2 server logic), this release includes critical fixes:

• Content-Length Validation: Ensures DATA frames match declared content-length headers (RFC 9113 compliance).
• Stream Exception Handling: Throws Psl\H2\Exception\StreamException on mismatches or overflows.
• Send Window Fix: waitForSendWindow() now flushes pending writes to prevent deadlocks.

Example of Safe HTTP/2 Usage:

use Azjezz\Psl\H2\ServerConnection;

try {
    $connection = new ServerConnection($socket);
    $stream = $connection->acceptStream();
    $headers = $stream->receiveHeaders(); // Validates content-length
    $data = $stream->receiveData();       // Throws on size mismatch
} catch (\Azjezz\Psl\H2\Exception\StreamException $e) {
    \Log::error("HTTP/2 stream error: {$e->getMessage()}");
    $connection->closeStream($stream->id());
}

Gotchas and Tips

Pitfalls

1. IDN Handling (Unchanged):

   • Use idn_to_ascii() for normalization:

     $psl->parse(idn_to_ascii('例子.测试')); // Returns '测试'
     

2. Private TLDs (Unchanged):

   • Extend the PSL file for internal TLDs (e.g., .localhost).

3. Performance (Unchanged):

   • Cache the Psl instance for high-throughput apps:

     $psl = app()->singleton(Psl::class, fn() => new Psl());
     

4. HTTP/2 Security Risks (New):

   • Affected: Only applications using Psl\H2\ServerConnection with untrusted client traffic.
   • Mitigation: Upgrade to ^6.2.1 and validate streams as shown above.
   • Unaffected: Core PSL parsing/validation (Psl class) remains unchanged.

5. Exception Handling (Unchanged):

   • Catch InvalidDomainException for malformed domains (e.g., example..com).

Debugging Tips

1. Verify PSL Updates (Unchanged):

   $psl = new Psl();
   echo $psl->getPslVersion(); // Check loaded PSL version.
   

2. HTTP/2 Stream Errors (New):

   • Log StreamException for debugging:

     try {
         $data = $stream->receiveData();
     } catch (\Azjezz\Psl\H2\Exception\StreamException $e) {
         \Log::debug("Stream {$stream->id()} failed: {$e->getMessage()}");
     }
     

3. Test Edge Cases (Unchanged):

   • Use the package’s test suite for reference.

Extension Points

1. Custom PSL Rules (Unchanged):

   • Extend Psl for blacklists or additional logic.

2. HTTP/2 Custom Logic (New):

   • Override ServerConnection methods to handle custom stream validation:

     class CustomH2Connection extends ServerConnection {
         protected function validateHeaders(array $headers): void {
             parent::validateHeaders($headers);
             // Add custom header validation
         }
     }
     

3. Laravel Integration (Unchanged):

   • Bind Psl to the container and use dependency injection.

4. PSL File Management (Unchanged):

   • Dynamically update via a console command (if needed).

Security Note: If you do not use Psl\H2\ServerConnection, this update is a non-breaking change and requires no action. Only applications handling untrusted HTTP/2 traffic with the H2 component must upgrade.