Back Url Bundle Laravel Package

Getting Started

Reality check first: this bundle is archived, has zero dependents, and targets Symfony 2 (EOL since November 2018). Treat it as a small piece of legacy glue you either vendor into an existing Symfony 2.8 app or replace outright — it is not a dependency to adopt on a new project.

Minimal steps in a legacy app:

1. Pin it explicitly. With no maintainer, composer require ys-tools/back-url-bundle will resolve to whatever dev-master happens to be. Commit-lock it or fork it under your own namespace:

   "repositories": [{ "type": "vcs", "url": "[email protected]:yourorg/BackUrl.git" }],
   "require": { "ys-tools/back-url-bundle": "dev-master#<sha>" }
   

2. Register the bundle in app/AppKernel.php (Symfony 2 has no bundle auto-discovery):

   $bundles = [ /* ... */ new YsTools\BackUrlBundle\BackUrlBundle() ];
   

3. Look here first, in this order: README.md → Annotation/ (the annotation class and its name — this is the actual public API) → Resources/config/services.yml (service IDs and any request listener) → DependencyInjection/Configuration.php (any tunables). Because the repo is tiny, reading all of it takes ten minutes and is cheaper than guessing at the annotation signature.
4. Confirm the annotation is wired into routing. Annotation-based controller arguments need sensio/framework-extra-bundle's ControllerListener (or the bundle's own listener) active on the kernel.controller event, plus doctrine/annotations configured in config.yml. If the annotation silently does nothing, that wiring is the first suspect.

First use case: the canonical one — a controller that renders a form, where the form's "Cancel" link and the post-submit redirect should both return the user to wherever they came from rather than a hardcoded route. Annotate the action, get the back URL (or a redirect response) injected, done, instead of hand-rolling $request->headers->get('referer') in every controller.

Implementation Patterns

Annotation-driven capture. The intended pattern is to decorate the action and let the bundle resolve the back URL from the request for you, roughly:

/**
 * @BackUrl("backUrl")
 */
public function editAction(Request $request, $backUrl)
{
    // ... handle form ...
    if ($form->isValid()) {
        return $this->redirect($backUrl ?: $this->generateUrl('homepage'));
    }
}

Verify the exact annotation name and argument semantics against Annotation/ — the bundle is unmaintained, so the README may lag the code.

Always have a fallback. The referer header is absent more often than people expect. Pair every use with a default route so a missing back URL degrades to sane navigation rather than a 500 or a blank redirect.

Session-backed back URLs for multi-step flows. If the bundle only reads the referer, a POST→POST sequence loses the original origin after the first hop. The robust pattern is to persist the first back URL in the session and refresh it only on safe (GET) requests:

// kernel.request listener, GET only
if ($request->isMethodSafe() && !$request->isXmlHttpRequest()) {
    $request->getSession()->set('back_url', $request->headers->get('referer'));
}

That is also the pattern to reach for if you decide to replace the bundle — it is about thirty lines and removes the dependency entirely.

Don't fight the security component. Symfony's firewall already stores _security.<firewall>.target_path on the login form. If you route login redirects through your own back-URL mechanism you will get two competing sources of truth and non-deterministic post-login destinations. Use one, not both.

Twig-level integration. If the bundle ships a Twig extension for back links, prefer it over generating href="{{ app.request.headers.get('referer') }}" in templates — the header is user-controlled and belongs nowhere near an href without validation (see Gotchas).

Test it explicitly. Referer behaviour is invisible in normal feature tests. Set the header yourself:

$client->request('GET', '/items/1/edit', [], [], ['HTTP_REFERER' => '/items']);
$client->submit($form);
$this->assertTrue($client->getResponse()->isRedirect('/items'));

And add a companion test with no referer to prove the fallback works.

Gotchas and Tips

• Open redirect. The referer is attacker-controllable. Any back-URL redirect must be restricted to relative paths or a host allowlist before it reaches RedirectResponse. If the bundle does not validate this itself, wrap it — do not assume.
• Missing referer is the normal case, not the edge case: HTTPS→HTTP transitions, Referrer-Policy: no-referrer (increasingly the browser default), privacy extensions, links from native apps, and any direct/bookmarked entry all produce nothing. Design for the empty value first.
• Relative vs absolute. Decide once whether your back URL is a path (/items) or a full URL, and normalise at the boundary. Mixing them produces redirects that work locally and break behind a proxy.
• Redirect loops. A back URL that points at the page you are currently redirecting from will bounce forever. Compare against the current request URI before redirecting.
• Annotation cache. In prod, new or edited annotations need php app/console cache:clear --env=prod --no-debug. Developers regularly lose an hour to a stale annotation cache thinking the bundle is broken.
• Dependency collisions. doctrine/annotations and sensio/framework-extra-bundle version constraints in a Symfony 2.8 app are fragile; adding a bundle that requires the annotation reader can force an unwanted bump. Run composer why doctrine/annotations before and after.
• Debugging. Start at the kernel.controller / kernel.request listeners registered by the bundle (debug:event-dispatcher in Symfony 2.8). If the back URL is empty, check whether the listener fired at all before suspecting the annotation.
• Extension points. Because there is no upstream, fork-and-patch is the realistic extension path. Prefer decorating the bundle's service over editing the vendored source, so a future replacement is a config change rather than an archaeology project.
• The strongest tip: plan the exit. The value here is a ~30-line request listener plus a redirect helper. Porting it to a first-party service is low risk, removes an unmaintained dependency from your audit trail, and is the only path that survives an eventual Symfony upgrade. Do that before you build anything substantial on top of the annotation.