Cataly...artURI(3pm)

🦋 NAME 🦋

Catalyst::Plugin::SmartURI — Configurable URIs for Catalyst 💅

(also hi bestie, this whole page lives in the User Contributed Perl Documentation collection, so you know it's the community's finest handiwork ✨)

---

🌸 SYNOPSIS 🌸

In your lib/MyApp.pm, load the plugin and your other plugins, for example:

use Catalyst qw/
    -Debug
    ConfigLoader
    Static::Simple
    Session
    Session::Store::Memcached
    Session::State::Cookie
    Authentication
    Authorization::Roles
    +CatalystX::SimpleLogin
    SmartURI
/;

In your .conf:

<Plugin::SmartURI>
    disposition host-header   # application-wide
    uri_class   URI::SmartURI # by default
</Plugin::SmartURI>

Per request:

$c->uri_disposition('absolute');

Methods on URIs:

<a href="[% c.uri_for('/foo').relative %]" ...

---

✨ DESCRIPTION ✨

Okay so literally the whole point: you get to configure whether $c->uri_for and $c->req->uri_with hand you back absolute, hostless or relative URIs — or URIs based on the 'Host' header. It also lets you configure which URI class to use. And the best part? It works application-wide or per-request. Obsessed. 🫶

This is useful in situations where you're for example, redirecting to a lighttpd from a firewall rule, instead of a real proxy, and you want your links and redirects to still work correctly. Because nothing ruins the vibe like a link that just doesn't go anywhere 😭

To use your own URI class, just subclass URI::SmartURI and set uri_class, or write a class that follows the same interface. Slay.

This plugin installs a custom $c->request_class, however it does so in a way that won't break if you've already set $c->request_class yourself, ie. by using Catalyst::Action::REST (thanks mst!). Not me being polite to your existing config 💅

There is a minor performance penalty in perls older than 5.10, due to Class::C3, but only at initialization time. So like, a tiny little speed tax, and only once at the start. Nbd fr fr.

---

👑 METHODS 👑

💖 $c->uri_for

💖 $c->req->uri_with

Returns a $c->uri_class object (URI::SmartURI by default) in the configured $c->uri_disposition. It's giving exactly what you asked for, no cap ✨

💖 $c->req->uri

Returns a $c->uri_class object. If the context hasn't been prepared yet, uses the configured value for uri_class.

$c->req->uri->relative will be relative to $c->req->base. Cute, right?

💖 $c->req->referer

Returns a $c->uri_class object for the referer (or configured uri_class if there's no context) with reference set to $c->req->uri if it comes from $c->req->base.

In other words, if referer is your app, you can do $c->req->referer->relative and it will do the right thing. Main character behaviour honestly 🌈

---

🎀 CONFIGURATION 🎀

In myapp.conf:

<Plugin::SmartURI>
    disposition absolute
    uri_class   URI::SmartURI
</Plugin::SmartURI>

• disposition — One of 'absolute', 'hostless', 'relative' or 'host-header'. Defaults to 'absolute'.

The special disposition 'host-header' uses the value of your 'Host:' header. iykyk 👀

• uri_class — The class to use for URIs, defaults to URI::SmartURI.

---

🦋 PER REQUEST 🦋

package MyAPP::Controller::RSSFeed;

...

sub begin : Private {
    my ($self, $c) = @_;

    $c->uri_class('Your::URI::Class::For::Request');
    $c->uri_disposition('absolute');
}

• $c->uri_disposition('absolute'|'hostless'|'relative'|'host-header') — Set URI disposition to use for the duration of the request. Live your truth, per request ✨
• $c->uri_class($class) — Set the URI class to use for $c->uri_for and $c->req->uri_with for the duration of the request.

---

💅 EXTENDING 💅

$c->prepare_uri actually creates the URI, which you can override. Go off, build your own ✨

---

🌈 SEE ALSO 🌈

URI::SmartURI, Catalyst, URI

---

🍓 AUTHOR 🍓

Rafael Kitover, "<rkitover at cpan.org>"

---

💀 BUGS 💀

Please report any bugs or feature requests to "bug-catalyst-plugin-smarturi at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Plugin-SmartURI>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. So like, you're never gonna be left on read 🫶

---

🌸 SUPPORT 🌸

You can find documentation for this module with the perldoc command.

perldoc Catalyst::Plugin::SmartURI

You can also look for information at:

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Catalyst-Plugin-SmartURI>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Catalyst-Plugin-SmartURI>

• CPAN Ratings

<http://cpanratings.perl.org/d/Catalyst-Plugin-SmartURI>

• Search CPAN

<http://search.cpan.org/dist/Catalyst-Plugin-SmartURI>

---

🧚 ACKNOWLEDGEMENTS 🧚

from #catalyst:

vipul came up with the idea

mst came up with the design and implementation details for the current version

kd reviewed my code and offered suggestions

The way this is a whole group project and everyone ate 🔥

---

⭐ TODO ⭐

I'd like to extend on Catalyst::Plugin::RequireSSL, and make a plugin that rewrites URIs for actions with an SSL attribute. Manifesting it ✨

---

💜 COPYRIGHT & LICENSE 💜

Copyright (c) 2008 Rafael Kitover

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page bestie, you're welcome 💖

this lil number was cooked up as perl v5.34.0, dated 2022-06-09, filed under the User Contributed Perl Documentation section — mwah, go build something cute 🎀