Uri Components Laravel Package

Product Decisions This Supports

• Feature Development:

  • URL/URI Manipulation: Enables granular, immutable manipulation of URI components (e.g., query parameters, paths, domains) for APIs, redirects, or dynamic URL generation (e.g., pagination, filtering).
  • Validation & Sanitization: Supports strict URI validation (e.g., IDN hosts, IPv4/IPv6) for security-sensitive features like OAuth callbacks or payment links.
  • Query Parameter Management: Advanced query handling (e.g., getList, appendList, filter) for analytics tools, search engines, or form submissions.
  • Domain/Subdomain Logic: Features like isSubdomainOf, commonAncestorWith for multi-tenant apps, CDN routing, or domain-based feature flags.

• Roadmap Prioritization:

  • Build vs. Buy: Justifies not building custom URI parsing logic (e.g., for a new analytics dashboard or URL shortener) by leveraging a battle-tested, PSR-7-compatible library.
  • Tech Debt Reduction: Replaces ad-hoc string manipulation (e.g., explode('/'), preg_replace) with type-safe, immutable components, reducing bugs in URL-heavy features.
  • Internationalization (i18n): Enables IDN (Internationalized Domain Names) support for global products without reinventing wheel.

• Use Cases:

  • APIs: Constructing/validating API endpoints with complex query params (e.g., GraphQL variables, pagination).
  • SEO Tools: Modifying URLs for canonicalization, redirects, or A/B testing.
  • Security: Sanitizing user-generated URLs (e.g., preventing SSRF via Host validation).
  • Legacy Systems: Gradually migrating from parse_url()/http_build_query() to a structured, maintainable approach.

When to Consider This Package

• Adopt When:

  • Your app requires fine-grained URI manipulation beyond simple string concatenation (e.g., dynamic path segments, query arrays).
  • You need immutable, type-safe URI components to avoid side effects in concurrent or serverless environments.
  • Your team already uses PSR-7 (e.g., with Symfony, Slim, or Laminas) and wants consistency.
  • You’re building features involving complex query logic (e.g., filtering, sorting, or multi-value params).
  • IDN/IPv6 support is critical (e.g., global audience, IPv6-only infrastructure).

• Look Elsewhere If:

  • You only need basic URL parsing (e.g., extracting a domain from a string) → Use PHP’s built-in parse_url().
  • Your stack is non-PHP (e.g., JavaScript/Node.js → Use url core module or node:url).
  • You’re constrained by PHP < 8.1 (e.g., legacy LTS) → Consider bobthecow/uri or polyfills.
  • You need URL shortening → Use dedicated packages like mathiasverraes/micro-uri.
  • Your primary use case is web scraping → Libraries like symfony/dom-crawler may suffice.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us handle URLs like a first-class citizen—no more fragile string hacks or regex nightmares. For example:

• APIs: Safely construct endpoints with complex queries (e.g., /products?category[]=electronics&category[]=books&sort=-price) without manual encoding/decoding.
• Security: Automatically validate domains/IPs to block malicious inputs (e.g., SSRF attacks) with zero custom code.
• Global Scale: Support international domains (e.g., 例子.测试) and IPv6 out of the box, future-proofing our product for non-English markets. It’s a drop-in replacement for messy URL logic, reducing bugs and dev time while adding enterprise-grade features. The MIT license and active maintenance make it a low-risk choice."

For Engineers:

*"Why this over homegrown solutions?

• Immutable Components: No more str_replace() hell—URI parts (query, path, host) are immutable value objects. Example:

  $uri = Uri::create('https://example.com/search?q=php');
  $updated = $uri->withQuery($uri->getQuery()->append('page', 2));
  

• PSR-7 Compatibility: Works seamlessly with frameworks like Symfony, Laminas, or Slim.
• Advanced Features:
  • Query arrays/lists: $query->appendList('tags', 'laravel')->appendList('tags', 'php').
  • Domain logic: $domain->isSubdomainOf('example.com').
  • IPv6/IPv4 normalization: $modifier->normalizeHost().
• Performance: Optimized for PHP 8.1+ (e.g., BackedEnum support, no deprecated PSR-7 cruft).
• Maintenance: Actively developed by the League (same team as league/oauth2-client), with clear deprecation paths.

Migration Path:

1. Start with Uri::create() for parsing.
2. Replace http_build_query() with $query->toRFC3986().
3. Use Modifier for chaining changes (e.g., $uri->withPath()->withQuery()).
4. Adopt Domain/Path classes for complex logic.

Trade-offs:

• Slight learning curve for immutable patterns.
• PHP 8.1+ required (but worth it for type safety).

Next Steps:

• Add to composer.json as a dev dependency.
• Audit 1–2 high-risk URL-heavy features (e.g., API client, redirect logic) for migration candidates."*