purl

What is PURL?

In standard Drupal, a URL like /about-us simply points to a piece of content. PURL (Persistent URL) allows you to attach "context" to your URLs that persists as the user navigates the site.

Think of PURL as a URL-based context. It allows segments of your URL (like subdomains or path prefixes) to trigger specific site behaviors—like changing the theme, filtering content by a specific group, or switching a user's workspace—without needing a different node for every variation.

How it Works: The Three Pillars

To understand PURL, you only need to know three terms:

1. The Provider: The "Logic." This is the module or feature that wants to use PURL (e.g., the Group module or a custom "Tenant" module).
2. The Modifier: The "Key." This is the specific value in the URL, such as my-team or client-a.
3. The Method: The "Location." This defines where the modifier lives in the URL.

Supported Methods:

• Path: example.com/my-team/dashboard
• Subdomain: my-team.example.com/dashboard
• Domain: my-team-portal.com/dashboard
• Query String: example.com/dashboard?workspace=my-team
• User Agent/Header: (Advanced) Triggers context based on the browser or request headers.

Common Use Cases

• Multi-Tenancy: Run 100 "mini-sites" from one Drupal install where each client has their own subdomain (client1.site.com, client2.site.com).
• Group Module: Automatically filter all site content and navigation based on a "Space" prefix in the URL (/groups/marketing/...).
• Dynamic Branding: Change the site’s CSS or Logo based on a URL prefix without changing the actual page path.
• Persistent Tracking: Maintain a "campaign ID" in the URL across the entire user session without losing it when the user clicks a link.

For Developers: Why use PURL?

If you’ve ever tried to manually rewrite outbound links to keep a query string or a path prefix, you know it’s a nightmare. PURL handles the heavy lifting:

• Inbound Processing: It automatically detects the modifier and stores the "Context" so your code can easily ask, "Which PURL workspace am I currently in?"
• Outbound Rewriting: PURL hooks into Drupal’s URL generator. Once a user enters a PURL context, every link on the page is automatically updated to include that context.
• Plugin Architecture: modernized for Drupal 10/11. You can easily create custom Provider plugins to map URL modifiers to any entity or configuration.