Url Encryptor Bundle Laravel Package

Getting Started

• Install with composer require nzo/url-encryptor-bundle. This is a Symfony bundle, not a Laravel package. In a Symfony app, register it in config/bundles.php, set the secret/key in .env, and configure config/packages/nzo_url_encryptor.yaml.
• First place to look: the README usage examples and the bundle’s DependencyInjection configuration. Identify the service class (usually Nzo\UrlEncryptorBundle\UrlEncryptor\UrlEncryptor) and the cipher/key options. That service is what you would port or wrap if you need the behavior in Laravel.
• First Laravel use case: encrypt an ID before placing it in a URL, then decrypt it in the controller. In Laravel you cannot autowire the Symfony bundle directly, so either:
  • use Laravel’s native equivalent first: Crypt::encryptString($id) / Crypt::decryptString($encrypted), or
  • port the bundle’s encrypt/decrypt logic into a small UrlIdEncryptor service, or
  • run it inside a Symfony service if you already have a Symfony app in the stack.
• Minimal Laravel-native example:

  $encrypted = Crypt::encryptString($user->id);
  $url = route('users.show', ['user' => $encrypted]);
  
  // Controller
  $id = Crypt::decryptString($request->route('user'));
  

  For tamper-proof URLs with expiry, prefer URL::signedRoute() / URL::temporarySignedRoute() before reaching for a third-party encryptor.

Implementation Patterns

• Wrap encryption behind one adapter. Do not scatter encrypt()/decrypt() calls across controllers. Create App\Support\UrlIdEncryptor with encryptId() and decryptId() methods. In Symfony, inject the bundle service into that adapter; in Laravel, bind your ported implementation in a service provider.
• Encrypt at URL-generation time, decrypt at request-boundary time. Encrypt IDs when building links (route helper, presenter, or Blade component) and decrypt in middleware or a form request. This keeps controllers clean and makes it obvious where ciphertext enters the app.
• Use it for opaque identifiers, not secrets. Good fits: invite IDs, unsubscribe tokens, short-lived opaque references, redirect targets. Bad fits: passwords, API keys, large payloads, or anything that still needs authorization checks after decryption.
• Symfony integration: autowire the bundle service into controllers and Twig extensions. Use the provided Twig filter if available, but keep business logic out of templates.
• Laravel integration: create a custom Blade directive or helper, e.g. @encryptedRoute('users.show', $user->id), backed by your adapter. Do not attempt to load the Symfony bundle’s service definitions in Laravel.
• Key configuration: load the key from an environment variable, keep it out of version control, and use the same key across all web nodes. If the bundle supports a key ring or key rotation, configure it before you need it; otherwise plan a migration path.
• Token pattern: encrypt a small payload such as ['id' => 123, 'exp' => now()->addHour()->timestamp], then validate expiry after decryption. This mirrors signed URLs but gives you opaque ciphertext instead of a visible signature.

Gotchas and Tips

• It is not a Laravel package. There is no service provider, facade, publishable config, or Laravel auto-discovery. You will either use it in a Symfony application or port/wrap the underlying encryption class. Budget time for that adapter.
• Key changes break every existing URL. Rotating the secret key invalidates all previously generated links. Version your ciphertext or keep the old key available during a transition window.
• URL length grows quickly. Encrypted output is typically longer than the input and may be base64url-encoded. Avoid using it for large query strings or data embedded in QR codes and emails; prefer short opaque tokens stored server-side.
• Encoding mismatches cause decryption failures. Ensure the ciphertext is URL-safe and encoded exactly once. Double-encoding or mixing +// with URL-safe -/_ will produce intermittent decrypt exceptions.
• Handle decryption failures explicitly. Catch exceptions and return 404 or 400 rather than letting a malformed token produce a 500. Do not leak whether the ciphertext was tampered with or the key was wrong.
• Audit maturity before production. The package has modest stars and zero dependents, and the listed release date is future-dated. Pin a specific version, check PHP/Symfony constraints, review the encryption implementation, and add round-trip plus tamper-detection tests.
• Debugging: test encrypt/decrypt in isolation (bin/console or artisan tinker), verify the key is actually loaded, and log only a ciphertext prefix — never the plaintext or full key.
• Extension points: in Symfony, decorate the bundle service if you need custom behavior. In Laravel, bind an interface to your adapter so you can swap implementations later. If the bundle service is final, port the logic instead of extending it.
• Encryption is not authorization. Always re-check ownership and permissions after decrypting an ID. URL encryption hides identifiers; it does not grant access.