docs::a...he2::URI(3)

🎀 NAME 🎀

Bestie, this is Apache2::URI — the Perl API for manipulating URIs 💅. The page itself is docs::a...he2::URI(3), from the User Contributed Perl Documentation, and it's here to make Apache URI wrangling make sense.

🌈 Synopsis 🌈

use Apache2::URI ();

$hostport = $r->construct_server();
$hostport = $r->construct_server($hostname);
$hostport = $r->construct_server($hostname, $port);
$hostport = $r->construct_server($hostname, $port, $pool);

$url = $r->construct_url();
$url = $r->construct_url($rel_uri);
$url = $r->construct_url($rel_uri, $pool);

$parsed_uri = $r->parse_uri($uri);

$parsed_uri = $r->parsed_uri();

$url = join '%20', qw(one two three);
Apache2::URI::unescape_url($url);

💅 Description 💅

Okay so here's the vibe: while APR::URI gives you a generic API to dissect, adjust, and put together any given URI string, Apache2::URI gives you an API that's specific to Apache — it takes the information directly from the $r object. So when you're manipulating the URI of the current HTTP request, you usually use methods from both classes 🫶.

✨ API ✨

Apache2::URI provides the following functions and methods:

🦋 "construct_server" 🦋

Construct a string made of hostname and port:

$hostport = $r->construct_server();
$hostport = $r->construct_server($hostname);
$hostport = $r->construct_server($hostname, $port);
$hostport = $r->construct_server($hostname, $port, $pool);

• obj: $r (Apache2::RequestRec object) — the current request object.
• opt arg1: $hostname (string) — the hostname of the server. If that argument is not passed, $r->get_server_name is used.
• opt arg2: $port (string) — the port the server is running on. If that argument is not passed, $r->get_server_port is used.
• opt arg3: $pool (APR::Pool object) — the pool to allocate the string from. If that argument is not passed, $r->pool is used.
• ret: $hostport (string) — the server's hostport string.
• since: 2.0.00

Examples:

• Assuming that:

$r->get_server_name == "localhost";
$r->get_server_port == 8001;

The code:

$hostport = $r->construct_server();

returns a string:

localhost:8001

• The following code sets the values explicitly:

$hostport = $r->construct_server("my.example.com", 8888);

and it returns a string:

my.example.com:8888

🌸 "construct_url" 🌸

Build a fully qualified URL from the uri and information in the request rec:

$url = $r->construct_url();
$url = $r->construct_url($rel_uri);
$url = $r->construct_url($rel_uri, $pool);

• obj: $r (Apache2::RequestRec object) — the current request object.
• opt arg1: $rel_uri (string) — the path to the requested file (it may include a concatenation of path, query and fragment components). If that argument is not passed, $r->uri is used.
• opt arg2: $pool (APR::Pool object) — the pool to allocate the URL from. If that argument is not passed, $r->pool is used.
• ret: $url (string) — a fully qualified URL.
• since: 2.0.00

Examples:

• Assuming that the request was:

http://localhost.localdomain:8529/test?args

The code:

my $url = $r->construct_url;

returns the string:

http://localhost.localdomain:8529/test

notice that the query (args) component is not in the string. You need to append it manually if it's needed.

• Assuming that the request was:

http://localhost.localdomain:8529/test?args

The code:

my $rel_uri = "/foo/bar?tar";
my $url = $r->construct_url($rel_uri);

returns the string:

http://localhost.localdomain:8529/foo/bar?tar

🔥 "parse_uri" 🔥

Break apart URI (affecting the current request's uri components):

$r->parse_uri($uri);

• obj: $r (Apache2::RequestRec object) — the current request object.
• arg1: $uri (string) — the uri to break apart.
• ret: no return value.
• warning: This method has several side-effects explained below.
• since: 2.0.00

This method call has the following side-effects:

1. sets $r->args to the rest after '?' if such exists in the passed $uri, otherwise sets it to undef.
2. sets $r->uri to the passed $uri without the $r->args part.
3. sets $r->hostname (if not set already) using the (scheme://host:port) parts of the passed $uri.

👑 "parsed_uri" 👑

Get the current request's parsed uri object:

my $uri = $r->parsed_uri();

• obj: $r (Apache2::RequestRec object) — the current request object.
• ret: $uri (APR::URI object) — the parsed uri.
• since: 2.0.00

This object is suitable for using with APR::URI::rpath.

🧚 "unescape_url" 🧚

Unescape URLs:

Apache2::URI::unescape_url($url);

• obj: $url (string) — the URL to unescape.
• ret: no return value — the argument $url is now unescaped.
• since: 2.0.00

Example:

my $url = join '%20', qw(one two three);
Apache2::URI::unescape_url($url);

$url now contains the string:

"one two three";

🌈 See Also 🌈

APR::URI, mod_perl 2.0 documentation.

💖 Copyright 💖

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

🫶 Authors 🫶

The mod_perl development team and numerous contributors.

---

✨ Signing off with perl v5.42.3, dated 2023-10-21, from docs::a...he2::URI(3) — slay, bestie, you made it to the end 💜