# return( $self->error( "Document URI needs to be an absolute URL path. Value provided was '$new'." ) ) if( length( $new ) && substr( $new, 0, 1 ) ne '/' );
if( $r)
{
# We do a lookup unless we are already in a sub request, and we do not want to end up in an infinite loop
return( $self->error( "URI path must be an absolute path starting with '/'. Path provided was \"$uri_path\".") ) if( substr( $uri_path, 0, 1 ) ne '/');
# No need to go further
if( -e( "${doc_root}${path}") )
{
return({
filepath=> "${doc_root}${path}",
path=> $uri_path,
query_string=> $qs,
code=> 200,
});
}
elsif( $uri_patheq '/')
{
return({
filepath=> $doc_root,
path=> $uri_path,
path_info=> undef(),
query_string=> $qs,
code=> ( -e( $doc_root) ? 200 : 404 ),
});
}
my@parts= split( '/', substr( $uri_path, 1 ) );
my$trypath= '';
my$trypath_uri= '';
my$pathinfo= '';
foreachmy$p( @parts)
{
# The last path was a directory, and we cannot find the element within. So, the rest of the path is not path info, but rather a 404 missing document hierarchy
# We test the $pathinfo string, so we do not bother checking further if it is already set.
# The uri is now /some/uri/file.html/some/path?q=something&l=ja_JP
$uri->query_string( 'q=something&l=ja_JP' );
my $html = $uri->slurp_utf8;
my $raw = $uri->slurp({ binmode => ':raw' });
# Same as $uri->document_uri
my $uri = $uri->uri;
=head1 VERSION
v0.1.3
=head1 DESCRIPTION
L<Apache2::SSI::URI> is used to manipulate and query http uri. It is used by L<Apache2::SSI> both for the main query, and also for sub queries like when there is an C<include> directive.
In this case, there would be the main document uri such as C</some/path/file.html> and containing a directive such as:
<!--#include virtual="../other.html" -->
An L<Apache2::SSI::URI> object would be instantiated to process the uri C<../other.html>, flatten the dots and get its underlying filename.
Even if the uri provided does not exist, am L<Apache2::SSI::URI> object would still be returned, so you need to check if the file exists by doing:
This instantiate an object that is used to access other key methods. It takes the following parameters:
=over 4
=item I<apache_request>
This is the L<Apache2::RequestRec> object that is provided if running under mod_perl.
it can be retrieved from L<Apache2::RequestUtil/request> or via L<Apache2::Filter/r>
You can get this L<Apache2::RequestRec> object by requiring L<Apache2::RequestUtil> and calling its class method L<Apache2::RequestUtil/request> such as C<Apache2::RequestUtil->request> and assuming you have set C<PerlOptions +GlobalRequest> in your Apache Virtual Host configuration.
Note that there is a main request object and subprocess request object, so to find out which one you are dealing with, use L<Apache2::RequestUtil/is_initial_req>, such as:
use Apache2::RequestUtil (); # extends Apache2::RequestRec objects
my $r = $r->is_initial_req ? $r : $r->main;
=item I<base_uri>
This is the base uri which is used to make uri absolute.
For example, if the main document uri is C</some/folder/file.html> containing a directive:
<!--#include virtual="../other.html" -->
One would instantiate an object using C</some/folder/file.html> as the base_uri like this:
my $uri = Apache2::SSI::URI->new(
base_uri => '/some/folder/file.html',
apache_request => $r,
document_uri => '../other.html',
# No need to specify document_root, because it will be derived from
# the Apache2::RequestRec provided with the apache_request parameter.
);
=item I<document_root>
This is only necessary to be provided if this is not running under Apache mod_perl. Without this value, L<Apache2::SSI> has no way to guess the document root and will not be able to function properly and will return an L</error>.
=item I<document_uri>
This is only necessary to be provided if this is not running under Apache mod_perl. This must be the uri of the document being served, such as C</my/path/index.html>. So, if you are using this outside of the rim of Apache mod_perl and your file resides, for example, at C</home/john/www/my/path/index.html> and your document root is C</home/john/www>, then the document uri would be C</my/path/index.html>
=back
=head2 apache_request
Sets or gets the L<Apache2::RequestRec> object. As explained in the L</new> method, you can get this Apache object by requiring the package L<Apache2::RequestUtil> and calling L<Apache2::RequestUtil/request> such as C<Apache2::RequestUtil->request> assuming you have set C<PerlOptions +GlobalRequest> in your Apache Virtual Host configuration.
When running under Apache mod_perl this is set automatically from the special L</handler> method, such as:
my $r = $f->r; # $f is the Apache2::Filter object provided by Apache
=head2 base_uri
Sets or gets the base reference uri. This is used to render the L</document_uri> provided an absolute uri.
=head2 clone
Create a clone of the object and return it.
=head2 code
Sets or gets the http code for this uri.
$uri->code( 404 );
=head2 collapse_dots
Provided with an uri, and this will resolve the path and removing the dots, such as C<.> and C<..> and return an L<URI> object.
my $uri = $ssi->collapse_dots( '/../a/b/../c/./d.html' );
# would become /a/c/d.html
my $uri = $ssi->collapse_dots( '/../a/b/../c/./d.html?foo=../bar' );
# would become /a/c/d.html?foo=../bar
$uri->query # foo=../bar
=head2 document_directory
Returns an L<Apache2::SSI::URI> object of the current directory of the L</document_uri> provided.
This can also be called as C<$uri->document_dir>
=head2 document_filename
This is an alias for L<Apache2::SSI::URI/filename>
=head2 document_path
Sets or gets the uri path to the document. This is the same as L</document_uri>, except it is striped from L</query_string> and L</path_info>.
=head2 document_root
Sets or gets the document root.
Wen running under Apache mod_perl, this value will be available automatically, using L<Apache2::RequestRec/document_root> method.
If it runs outside of Apache, this will use the value provided upon instantiating the object and passing the I<document_root> parameter. If this is not set, it will return the value of the environment variable C<DOCUMENT_ROOT>.
=head2 document_uri
Sets or gets the document uri, which is the uri of the document being processed.
For example:
/index.html
Under Apache, this will get the environment variable C<DOCUMENT_URI> or calls the L<Apache2::RequestRec/uri> method.
Outside of Apache, this will rely on a value being provided upon instantiating an object, or the environment variable C<DOCUMENT_URI> be present.
The value should be an absolute uri.
=head2 env
Sets or gets environment variables that are distinct for this uri.
It is the equivalent of L<Apache2::RequestRec/subprocess_env>. Actually it uses L<Apache2::RequestRec/subprocess_env> if running under Apache/mod_perl, other wise it uses a private hash reference to store the values.
=head2 filename
This returns the system file path to the document uri as a string.
=head2 finfo
Returns a L<Apache2::SSI::Finfo> object. This provides access to L<perlfunc/stat> information as method, taking advantage of L<APR::Finfo> when running under Apache, and an identical interface otherwise. See L<Apache2::SSI::Finfo> for more information.
=head2 new_uri
A short-hand for C<Apache2::SSI::URI->new>
=head2 parent
Returns the parent of the document uri, or if there is no parent, it returns the current object itself.
my $up = $uri->parent;
# would return /some/path assuming the document uri was /some/path/file.html
=head2 path_info
Sets or gets the path info for the current uri.
Example:
my $string = $ssi->path_info;
$ssi->path_info( '/my/path/info' );
The path info value is also set automatically when L</document_uri> is called, such as: