Apache2::URI(3pm)

1docs::api::Apache2::URIU(s3e)r Contributed Perl Documentadtoicosn::api::Apache2::URI(3)
2
3
4

NAME

6       Apache2::URI - Perl API for manipulating URIs
7

Synopsis

9         use Apache2::URI ();
10
11         $hostport = $r->construct_server();
12         $hostport = $r->construct_server($hostname);
13         $hostport = $r->construct_server($hostname, $port);
14         $hostport = $r->construct_server($hostname, $port, $pool);
15
16         $url = $r->construct_url();
17         $url = $r->construct_url($rel_uri);
18         $url = $r->construct_url($rel_uri, $pool);
19
20         $parsed_uri = $r->parse_uri($uri);
21
22         $parsed_uri = $r->parsed_uri();
23
24         $url = join '%20', qw(one two three);
25         Apache2::URI::unescape_url($url);
26

Description

28       While "APR::URI" provides a generic API to dissect, adjust and put
29       together any given URI string, "Apache2::URI" provides an API specific
30       to Apache, by taking the information directly from the $r object.
31       Therefore when manipulating the URI of the current HTTP request usually
32       methods from both classes are used.
33

API

35       "Apache2::URI" provides the following functions and methods:
36
37   "construct_server"
38       Construct a string made of hostname and port
39
40         $hostport = $r->construct_server();
41         $hostport = $r->construct_server($hostname);
42         $hostport = $r->construct_server($hostname, $port);
43         $hostport = $r->construct_server($hostname, $port, $pool);
44
45       obj: $r ( "Apache2::RequestRec object" )
46           The current request object
47
48       opt arg1: $hostname ( string )
49           The hostname of the server.
50
51           If that argument is not passed, "$r->get_server_name" is used.
52
53       opt arg2: $port ( string )
54           The port the server is running on.
55
56           If that argument is not passed, "$r->get_server_port" is used.
57
58       opt arg3: $pool ( "APR::Pool object" )
59           The pool to allocate the string from.
60
61           If that argument is not passed, "$r->pool" is used.
62
63       ret: $hostport ( string )
64           The server's hostport string
65
66       since: 2.0.00
67
68       Examples:
69
70       •   Assuming that:
71
72             $r->get_server_name == "localhost";
73             $r->get_server_port == 8001;
74
75           The code:
76
77             $hostport = $r->construct_server();
78
79           returns a string:
80
81             localhost:8001
82
83       •   The following code sets the values explicitly:
84
85             $hostport = $r->construct_server("my.example.com", 8888);
86
87           and it returns a string:
88
89             my.example.com:8888
90
91   "construct_url"
92       Build a fully qualified URL from the uri and information in the request
93       rec:
94
95         $url = $r->construct_url();
96         $url = $r->construct_url($rel_uri);
97         $url = $r->construct_url($rel_uri, $pool);
98
99       obj: $r ( "Apache2::RequestRec object" )
100           The current request object
101
102       opt arg1: $rel_uri ( string )
103           The path to the requested file (it may include a concatenation of
104           path, query and fragment components).
105
106           If that argument is not passed, "$r->uri" is used.
107
108       opt arg2: $pool ( "APR::Pool object" )
109           The pool to allocate the URL from
110
111           If that argument is not passed, "$r->pool" is used.
112
113       ret: $url ( string )
114           A fully qualified URL
115
116       since: 2.0.00
117
118       Examples:
119
120       •   Assuming that the request was
121
122             http://localhost.localdomain:8529/test?args
123
124           The code:
125
126             my $url = $r->construct_url;
127
128           returns the string:
129
130             http://localhost.localdomain:8529/test
131
132           notice that the query (args) component is not in the string. You
133           need to append it manually if it's needed.
134
135       •   Assuming that the request was
136
137             http://localhost.localdomain:8529/test?args
138
139           The code:
140
141             my $rel_uri = "/foo/bar?tar";
142             my $url = $r->construct_url($rel_uri);
143
144           returns the string:
145
146             http://localhost.localdomain:8529/foo/bar?tar
147
148   "parse_uri"
149       Break apart URI (affecting the current request's uri components)
150
151         $r->parse_uri($uri);
152
153       obj: $r ( "Apache2::RequestRec object" )
154           The current request object
155
156       arg1: $uri ( string )
157           The uri to break apart
158
159       ret: no return value
160       warning:
161           This method has several side-effects explained below
162
163       since: 2.0.00
164
165       This method call has the following side-effects:
166
167       1.  sets "$r->args" to the rest after '?' if such exists in the passed
168           $uri, otherwise sets it to "undef".
169
170       2.  sets "$r->uri" to the passed $uri without the "$r->args" part.
171
172       3.  sets "$r->hostname" (if not set already) using the
173           ("scheme://host:port") parts of the passed $uri.
174
175   "parsed_uri"
176       Get the current request's parsed uri object
177
178         my $uri = $r->parsed_uri();
179
180       obj: $r ( "Apache2::RequestRec object" )
181           The current request object
182
183       ret: $uri ( "APR::URI object" )
184           The parsed uri
185
186       since: 2.0.00
187           This object is suitable for using with "APR::URI::rpath"
188
189   "unescape_url"
190       Unescape URLs
191
192         Apache2::URI::unescape_url($url);
193
194       obj: $url ( string )
195           The URL to unescape
196
197       ret: no return value
198           The argument $url is now unescaped
199
200       since: 2.0.00
201
202       Example:
203
204         my $url = join '%20', qw(one two three);
205         Apache2::URI::unescape_url($url);
206
207       $url now contains the string:
208
209         "one two three";
210

Copyright

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

Authors

219       The mod_perl development team and numerous contributors.
220
221
222
223perl v5.34.0                      2022-02-02        docs::api::Apache2::URI(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors