Net Uri Laravel Package

Technical Evaluation

Architecture Fit

• PSR-7/PSR-17 Alignment: The package’s strict adherence to PSR standards ensures seamless integration with Laravel’s PSR-compliant components (e.g., HTTP clients like Guzzle, middleware, and routing). This reduces friction in Laravel’s existing architecture, which relies heavily on PSR-17 for URI factories and PSR-7 for URI interfaces.
• Non-HTTP URI Support: Laravel primarily focuses on HTTP, but this package enables handling of non-HTTP URIs (e.g., mailto:, ftp:, or custom schemes like app://). This is particularly useful for Laravel applications interacting with diverse systems (e.g., CLI tools, microservices with custom protocols, or integrations with non-web services).
• Immutable Design: The immutable with*() methods align with Laravel’s functional programming patterns (e.g., middleware chains, request pipelines), ensuring thread safety and predictable state management.
• Query and Path Manipulation: Laravel’s routing and request handling often require complex URI manipulations (e.g., dynamic query parameters, path normalization). This package’s helper methods (withQueryItems(), getQueryItem(), withComponents()) simplify these operations, reducing boilerplate in Laravel’s route definitions or request validation logic.

Integration Feasibility

• Laravel HTTP Stack: The package can replace or augment Laravel’s default URI implementations (e.g., Symfony\Component\HttpFoundation\Url or GuzzleHttp\Psr7\Uri) in custom HTTP logic. For example:
  • Use Phrity\Net\Uri in middleware to parse or modify request URIs.
  • Replace URL::to() with UriFactory::createUri() for generating canonical URIs in API responses.
• PSR-17 Factory: Laravel’s HTTP clients (e.g., Guzzle, Symfony HTTP Client) can leverage Phrity\Net\UriFactory as a PSR-17-compliant factory, ensuring consistency across URI creation. This is particularly useful in Laravel’s service container for dependency injection.
• Routing and Validation: The package’s query manipulation methods can streamline Laravel’s route model binding or form request validation. For example:

  use Phrity\Net\Uri;
  $uri = new Uri(request()->getUri());
  $queryParams = $uri->getQueryItems(); // Directly access query params
  

• Internationalization: Laravel applications targeting global audiences can benefit from the package’s IDN encoding/decoding (IDN_ENCODE, IDN_DECODE), ensuring compatibility with non-ASCII domains (e.g., ηßöø必Дあ.com).

Technical Risk

• Validation Gaps: The package does not enforce strict RFC 3986 validation, which could lead to malformed URIs entering the system. Mitigation:
  • Use Laravel’s Validator facade to validate URIs before processing.
  • Implement custom middleware to sanitize URIs (e.g., reject URIs with invalid schemes or ports).
• Performance Impact: The package’s flexibility (e.g., modifiers like REQUIRE_PORT, NORMALIZE_PATH) introduces minor overhead. Mitigation:
  • Benchmark URI parsing/generation in high-throughput Laravel APIs (e.g., using Laravel Forge or Blackfire).
  • Cache frequently used URIs (e.g., in Laravel’s cache layer) if performance is critical.
• Dependency Conflicts: Laravel’s core relies on Symfony’s PSR-7/17 implementations. Mitigation:
  • Use Composer’s replace directive to avoid conflicts:

    "replace": {
      "psr/http-message": "phrity/net-uri"
    }
    

  • Alternatively, alias the package in config/app.php to override Laravel’s default bindings.
• PHP Version Requirements: The package requires PHP 8.1+, while Laravel supports PHP 8.0+. Mitigation:
  • Ensure Laravel’s config/app.php enforces PHP 8.1+ compatibility.
  • Test thoroughly with Laravel’s minimum supported PHP version.

Key Questions

1. Justification for Adoption:
   • What specific Laravel use cases does this package solve that existing solutions (e.g., Symfony’s Uri, Guzzle’s Uri) do not? For example:
     • Need for non-HTTP URI support (e.g., custom protocols, CLI tools).
     • Advanced query manipulation beyond Laravel’s URL helper.
     • Performance optimizations for URI parsing in high-load APIs.
2. Testing Strategy:
   • How will edge cases (e.g., malformed URIs, IDN, ports, custom schemes) be tested in Laravel’s test suite? Will existing tests (e.g., URL::to()) need updates?
   • Example: Test Phrity\Net\Uri with Laravel’s HttpTests or custom feature tests.
3. Dependency Management:
   • How will this package coexist with Laravel’s existing PSR-7/17 implementations (e.g., symfony/http-foundation)? Will there be conflicts in the service container?
   • Audit dependencies using composer why-not phrity/net-uri and composer why symfony/http-foundation.
4. Long-Term Compatibility:
   • How will future Laravel updates (e.g., new HTTP stack versions) affect this package? Will the package remain compatible with Laravel’s evolving PSR-7/17 requirements?
   • Monitor Laravel’s deprecations (e.g., URL helper changes) and adjust integration accordingly.
5. Team Adoption:
   • How will the team adopt this package without disrupting existing workflows? For example:
     • Gradual migration: Start with non-critical features (e.g., CLI tools) before replacing core HTTP logic.
     • Documentation: Update Laravel’s internal docs to reflect the new URI handling approach.

Integration Approach

Stack Fit

• Laravel HTTP Layer:
  • Middleware: Replace Symfony\Component\HttpFoundation\Url or GuzzleHttp\Psr7\Uri in custom middleware to parse or modify URIs. For example:

    public function handle($request, Closure $next) {
        $uri = new Phrity\Net\Uri($request->getUri());
        // Modify URI (e.g., add query params, normalize path)
        $request = $request->withUri($uri);
        return $next($request);
    }
    

  • Routing: Use Phrity\Net\Uri in route definitions for dynamic URI handling. For example:

    Route::get('/search', function (Phrity\Net\Uri $uri) {
        $queryParams = $uri->getQueryItems();
        // Process query params
    });
    

• PSR-17 Factory:
  • Register Phrity\Net\UriFactory as the default PSR-17 factory in Laravel’s service container. Update config/app.php:

    'bindings' => [
        Psr\Http\Message\UriInterface::class => function ($app) {
            return (new Phrity\Net\UriFactory())->createUri('');
        },
    ],
    

  • Integrate with Laravel’s HTTP clients (e.g., Guzzle) to ensure consistent URI creation:

    $client = new GuzzleHttp\Client([
        'base_uri' => (new Phrity\Net\UriFactory())->createUri('https://api.example.com'),
    ]);
    

• Validation and Forms:
  • Use the package’s query manipulation methods in Laravel’s FormRequest or API resource validation. For example:

    public function rules() {
        $uri = new Phrity\Net\Uri($this->request->getUri());
        $queryParams = $uri->getQueryItems();
        return [
            'query_param' => 'required|string',
            // Custom validation logic based on $queryParams
        ];
    }
    

• Internationalization:
  • Enable IDN encoding/decoding for Laravel apps targeting global audiences. For example:

    $uri = new Phrity\Net\Uri('https://ηßöø必Дあ.com');
    $encodedHost = $uri->getHost(Phrity\Net\Uri::IDN_ENCODE);
    

Migration Path

1. Pilot Phase:
   • Start with non-critical features (e.g., CLI tools, custom integrations) to test the package’s compatibility with Laravel.
   • Example: Replace ad-hoc URI parsing in Laravel’s Artisan commands with Phrity\Net\Uri.
2. HTTP Layer Migration:
   • Gradually replace Symfony\Component\HttpFoundation\Url or GuzzleHttp\Psr7\Uri in middleware, controllers, or services.
   • Use feature flags or environment variables to toggle between old and new URI implementations during migration.
3. PSR-17 Factory Integration:
   • Update Laravel’s service container to bind Phrity\Net\UriFactory as the default PSR-17 factory.
   • Test all HTTP clients (e.g., Guzzle, Symfony HTTP Client) to ensure compatibility.
4. Routing and Validation:
   • Update route definitions and validation logic to use the package’s query manipulation methods.
   • Example: Replace request()->query() with `Phrity\Net\Uri