Url Bundle Laravel Package

Getting Started

zicht/url-bundle is a Symfony bundle — not a Laravel package. Before reaching for composer require, be clear on what you're actually getting: a small set of URL utilities (URL value objects, URL signing/verification, and Twig helpers) wired through Symfony's DI container. With zero dependents and no stars, treat it as a reference implementation you may lift from rather than a drop-in dependency.

Minimal path if you're evaluating it:

1. composer require zicht/url-bundle in a scratch Symfony app (not your Laravel app — there's no service provider, facade, or config/url.php).
2. Explore the source, starting at src/ — look for the bundle class, the URL/signer services, and any Twig extension. The namespace is Zicht\Bundle\UrlBundle\….
3. Read the bundle's DependencyInjection/Configuration.php to see the real config keys (secret, defaults). That file is the source of truth, not the README.
4. First use case: signed URLs — generate a URL with an HMAC query parameter, then verify it on the receiving endpoint. This is the classic "unsubscribe link / time-limited download" pattern and it's the most likely reason to care about this bundle at all.

If you want the behavior in Laravel today, plan to copy the signer/URL classes into app/Support/ and skip the bundle entirely.

Implementation Patterns

Signed-URL round trip (Symfony native). Inject the signer service into a controller, sign the absolute URL for a route, return it in a response or email. On the receiving controller, pull the signature from the request, run verification, and reject on failure. Keep signing and verification in the same class so the parameter name and hashing algorithm can't drift.

Twig integration. If the bundle ships a Twig extension (likely url_sign or similar filter), use it in templates for outbound links (password resets, magic links, download links). This is convenient in Symfony; in Laravel you'd replicate it with a Blade directive wrapping your copied signer service.

Compose with the router, don't hardcode. Generate the base URL with Symfony's UrlGeneratorInterface, then sign. Hardcoded paths will break across environments and signed URLs will silently mismatch on host changes.

Bridge pattern for Laravel. Register a UrlSignerServiceProvider that binds a small interface to a copied signer class, and read the secret from config('services.url_signer.secret'). This gives you testability and keeps the origin of the code obvious. Prefer an HMAC (hash_hmac('sha256', $url, $secret)) over anything clever — the bundle's value is the shape, not exotic crypto.

Use cases that fit cleanly:

• Time-limited download or invite links
• Unsubscribe / preference-center links in transactional email
• Signed redirects that must not be tamperable
• Canonical URL normalization before caching

Testing pattern. For every signed-URL feature, write two tests: one that asserts a freshly signed URL verifies, and one that asserts a URL with a tampered query parameter or expired timestamp is rejected. Freeze the clock with Carbon::setTestNow() in Laravel (or Symfony's clock) so expiration tests are deterministic.

Gotchas and Tips

• It's not a Laravel package. No auto-discovery, no UrlBundleServiceProvider, no facade. Installing it in a Laravel app will register classes but wire nothing — you'll get "target class does not exist" errors the moment you try to resolve a signer from the container. Either run it in Symfony or vendor the code.
• Low-maintenance risk. Zero dependents and no stars is a signal: no community pressure to fix bugs, no migration guides, no security advisories. Pin the version in composer.json with an exact constraint and audit the signer code yourself before production use.
• Secret handling. Never fall back to an empty or default secret — a signer with an empty key produces predictable signatures. Use %env(URL_SIGNER_SECRET)% in Symfony or env() in Laravel, and fail loudly at boot if it's missing.
• Timing-safe comparison. If you copy the verification logic, use hash_equals() rather than ===. The bundle may already do this; verify before trusting it in an auth-adjacent flow.
• Host/scheme mismatch. Signing an absolute URL means the host is part of the signed payload. Behind a proxy, Request::getSchemeAndHttpHost() can differ between signing and verification — configure trusted proxies or sign only the path + query, not the host.
• Config key drift. Symfony bundle config lives under an extension alias (e.g. zicht_url: in config/packages/). Don't assume url: — check the bundle class's getContainerExtension().
• Extension points. If you stay in Symfony, override the signer service by re-aliasing the interface in services.yaml after the bundle loads; that's the cleanest way to swap in your own implementation without forking.
• Debugging tip. When signatures fail, log the raw string that was signed alongside the received URL. Nine times out of ten the bug is a trailing slash, a reordered query string, or URL-encoding drift — seeing both strings makes it obvious in seconds.
• When to walk away. If your only need is hash_hmac on a route URL, the bundle is overhead. A ~20-line UrlSigner class in app/Support/ gives you the same result with no Symfony dependency and no supply-chain surface.