Apache2-API
view release on metacpan or search on metacpan
lib/Apache2/API/Request.pm view on Meta::CPAN
# get an APR::Request::Apache2 object
my $apr = $req->apr;
# query string as an hash reference
my $hash_ref = $req->args; # also an APR::Request::Param::Table object
my $status = $req->args_status;
# HTTP query
my $string = $req->as_string;
my $auth = $req->auth;
my $auth = $req->authorization;
my $auth_type = $req->auth_type;
$req->auto_header(1);
# returns an APR::Request::Param::Table object similar to APR::Table
my $body = $req->body;
my $status = $req->body_status;
my $limit = $req->brigade_limit;
my $charset = $req->charset;
$req->child_terminate;
my $api_version = $req->client_api_version;
# close client connection
$req->close;
my $status_code = $req->code;
# Apache2::Connection
my $conn = $req->connection;
my $id = $req->connection_id;
# content of the request filename
my $content = $req->content;
my $encoding = $req->content_encoding;
my $langs_array_ref = $req->content_languages;
my $len = $req->content_length;
# text/plain
my $ct = $req->content_type;
# Get a Cookie object
my $cookie = $req->cookie( $name );
# Cookie::Jar object
my $jar = $req->cookies;
# get data string sent by client
my $data = $req->data;
my $formatter = $req->datetime;
my $decoded = $req->decode( $string );
my $do_not_track = $req->dnt;
my $encoded = $req->encode( $string );
$req->discard_request_body(1);
my $document_root = $req->document_root;
my $url = $req->document_uri;
# APR::Table object
my $hash_ref = $req->env;
my $headers = $req->err_headers_out;
# request filename
my $filename = $req->filename;
# APR::Finfo object
my $finfo = $req->finfo;
# e.g.: CGI/1.1
my $gateway = $req->gateway_interface;
my $code_ref = $req->get_handlers( $name );
# 404 Not Found
my $str = $req->get_status_line(404);
my $r = $req->global_request;
my $is_head = $req->header_only;
# same
my $is_head = $req->is_header_only;
my $content_type = $req->headers( 'Content-Type' );
# or (since it is case insensitive)
my $content_type = $req->headers( 'content-type' );
# or
my $content_type = $req->headers->{'Content-Type'};
$req->headers( 'Content-Type' => 'text/plain' );
# or
$req->headers->{'Content-Type'} = 'text/plain';
# APR::Table object
my $headers = $req->headers;
my $hash_ref = $req->headers_as_hashref;
my $json = $req->headers_as_json;
my $headers = $req->headers_in;
my $out = $req->headers_out;
my $hostname = $req->hostname;
my $uri_host = $req->http_host;
my $conn_id = $req->id;
my $if_mod = $req->if_modified_since;
my $if_no_match = $req->if_none_match;
my $filters = $req->input_filters;
my $bool = $req->is_aborted;
my $enabled = $req->is_perl_option_enabled;
# running under https?
my $secure = $req->is_secure;
# JSON object
lib/Apache2/API/Request.pm view on Meta::CPAN
my $notes = $req->redirect_error_notes;
my $qs = $req->redirect_query_string;
my $status = $req->redirect_status;
my $url = $req->redirect_url;
my $referrer = $req->referer;
# APR::SockAddr object
my $addr = $req->remote_addr;
my $host = $req->remote_host;
my $string = $req->remote_ip;
my $port = $req->remote_port;
$req->reply( Apache2::Const::FORBIDDEN => { message => "Get away" } );
# Apache2::RequestRec
my $r = $req->request;
my $scheme = $req->request_scheme;
# DateTime::Lite object
my $dt = $req->request_time;
my $uri = $req->request_uri;
my $filename = $req->script_filename;
my $name = $req->script_name;
my $uri = $req->script_uri;
# Apache2::ServerUtil object
my $server = $req->server;
my $addr = $req->server_addr;
my $admin = $req->server_admin;
my $hostname = $req->server_hostname;
my $name = $req->server_name;
my $port = $req->server_port;
my $proto = $req->server_protocol;
my $sig = $req->server_signature;
my $software = $req->server_software;
my $vers = $req->server_version;
$req->set_basic_credentials( $user => $password );
$req->set_handlers( $name => $code_ref );
my $data = $req->slurp_filename;
# Apache2::Connection object
my $socket = $req->socket;
my $status = $req->status;
my $line = $req->status_line;
my $dt = $req->str2datetime( $http_date_string );
my $rc = $req->subnet_of( $ip, $mask );
# APR::Table object
my $env = subprocess_env;
my $dir = $req->temp_dir;
my $r = $req->the_request;
my $dt = $req->time2datetime( $time );
say $req->time2str( $seconds );
# text/plain
my $type = $req->type;
my $raw = $req->unparsed_uri;
# Apache2::API::Request::Params
my $uploads = $req->uploads;
my $uri = $req->uri;
my $decoded = $req->url_decode( $url );
my $encoded = $req->url_encode( $url );
my $user = $req->user;
my $agent = $req->user_agent;
=head1 VERSION
v0.4.2
=head1 DESCRIPTION
The purpose of this module is to provide an easy access to various methods designed to process and manipulate incoming requests.
This is designed to work under modperl.
Normally, one would need to know which method to access across various Apache2 mod perl modules, which makes development more time consuming and even difficult, because of the scattered documentation and even sometime outdated.
This module alleviate this problem by providing all the necessary methods in one place. Also, at the contrary of L<Apache2> modules suit, all the methods here are die safe. When an error occurs, it will always return undef() and the error will be abl...
For its alter ego to manipulate outgoing HTTP response, use the L<Apache2::API::Response> module.
Throughout this documentation, we refer to C<$r> as the L<Apache request object|Apache2::RequestRec> and C<$req> as an object from this module.
=head1 CONSTRUCTORS
=head2 new
This takes an optional hash or hash reference of options and instantiate a new object.
It takes the following parameters:
=over 4
=item * C<checkonly>
If true, it will not perform the initialisation it would usually do under modperl.
=item * C<debug>
Optional. If set with a positive integer, this will activate verbose debugging message
=item * C<max_size>
Optional. This is the maximum size of the data that can be sent to us over HTTP. By default, there is no limit.
=item * C<request>
This is a required parameter to be sent with a value set to a L<Apache2::RequestRec> object
=back
=head1 METHODS
=head2 aborted
Tells whether the connection has been aborted or not, by calling L<Apache2::Connection/aborted>
=head2 accept
Returns the HTTP C<Accept> header value, such as C<text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8>
lib/Apache2/API/Request.pm view on Meta::CPAN
Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works only for digest authentication.
It does not return anything.
=head2 auth_name
my $auth_name = $req->auth_name();
my $auth_name = $req->auth_name( $new_auth_name );
Sets or gets the current Authorization realm, i.e. the per directory configuration directive C<AuthName>
The C<AuthName> directive creates protection realm within the server document space. To quote RFC 1945 "These realms allow the protected resources on a server to be partitioned into a set of protection spaces, each with its own authentication scheme ...
The client uses the root URL of the server to determine which authentication credentials to send with each HTTP request. These credentials are tagged with the name of the authentication realm that created them. Then during the authentication stage th...
=head2 auth_type
my $auth_type = $req->auth_type();
my $auth_type = $req->auth_type( $new_auth_type );
Sets or gets the type of authorization required for this request, i.e. the per directory configuration directive C<AuthType>
Normally C<AuthType> would be set to C<Basic> to use the basic authentication scheme defined in RFC 1945, Hypertext Transfer Protocol (HTTP/1.0). However, you could set to something else and implement your own authentication scheme.
=head2 authorization
Returns the HTTP C<authorization> header value. This is similar to L</auth>.
See also L<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization>
=head2 auth_type
Returns the authentication type by calling L<Apache2::RequestRec/auth_type>
my $auth_type = $req->auth_type; # Basic
=head2 auto_header
Given a boolean value, this enables the auto header or not by calling the method L<Apache2::RequestRec/assbackwards>
If this is disabled, you need to make sure to manually update the counter, such as:
$req->connection->keepalives( $req->connection->keepalives + 1 );
See L<Apache2::RequestRec> for more information on this.
=head2 basic_auth_passwd
my( $rc, $passwd ) = $req->basic_auth_passwd;
Get the details from the basic authentication, by calling L<Apache2::Access/get_basic_auth_pw>
It returns:
=over 4
=item 1. the value of an Apache constant
This would be C<Apache2::Const::OK> if the password value is set (and assured a correct value in L</user>); otherwise it returns an error code, either C<Apache2::Const::HTTP_INTERNAL_SERVER_ERROR> if things are really confused, C<Apache2::Const::HTTP...
=item 2. the password as set in the headers (decoded)
=back
Note that if C<AuthType> is not set, L<Apache2::Access/get_basic_auth_pw> first sets it to C<Basic>.
=head2 basic_auth_pw
This is an alias for L</basic_auth_passwd>
=head2 basic_auth_pwd
This is an alias for L</basic_auth_passwd>
=head2 body
Returns an L<APR::Request::Param::Table|APR::Request::Param> object containing the C<POST> data parameters of the L<Apache2::Request> object.
my $body = $req->body;
my @body_names = $req->body;
If there is no request body, then this would return C<undef>. So, for example, if you do a C<POST> query without any content, this would return C<undef>
An optional name parameter can be passed to return the POST (or other similar query types) data parameter associated with the given name:
my $foo_body = $req->body("foo");
In scalar context this method fetches the first matching body param. In list context it returns all matching body params.
This is similar to the C<param> method. The main difference is that modifications to the scalar C<< $req->body() >> table affect the underlying C<apr_table_t> attribute in C<apreq_request_t>, so their impact will be noticed by all C<libapreq2> applic...
Contrary to perl hash, this uses L<APR::Table> and the order in the hash is preserved, so you could do:
my @body_names = $req->body;
my @body_names = %$body;
would yield the same thing.
This will throw an L<APR::Request::Error> object whenever L</body_status> returns a non-zero value.
Check L<Apache2::Request> and L<APR::Table> for more information.
=head2 body_status
my $int = $req->body_status; # should return 0
Returns the final status code of the body parser.
=head2 brigade_limit
my $int = $req->brigade_limit;
$req->brigade_limit( $int );
Get or set the brigade_limit for the current parser. This limit determines how many bytes of a file upload that the parser may spool into main memory. Uploads exceeding this limit are written directly to disk.
See also L</temp_dir>
=head2 call
Provided with an Apache2 API method name, and optionally with some additional arguments, and this will call that Apache2 method and return its result.
lib/Apache2/API/Request.pm view on Meta::CPAN
=head2 cookie
Returns the current value for the given cookie name, which may be C<undef> if nothing is found.
This works by calling the L</cookies> method, which returns a L<cookie jar object|Cookie::Jar>.
=head2 cookies
Returns a L<Cookie::Jar> object acting as a jar with various methods to access, manipulate and create cookies.
=head2 data
This method reads the data sent by the client. It can be used as an accessor, and it will return a cached data, if any, or read the data from L<APR::Bucket>, or it can be used as a mutator to artificially set a payload.
Internally it uses L<Apache2::RequestUtil/pnotes> to cache the processed request body and stores it in C<REQUEST_BODY>, and set the shared property C<REQUEST_BODY_PROCESSED> to C<1>. Thus, the processed raw request body is always for other handlers w...
It takes an optional hash or hash reference of the following options:
=over 4
=item * C<data>
When provided, this will set the request body to the value provided.
=item * C<max_size>
The maximum size of the data that can be transmitted to us over HTTP. By default, there is no limit.
=back
Finally, if a charset is specified, this will also decode it from its encoded charset into perl internal utf8.
This is specifically designed for C<JSON> payload.
It returns a string of data upon success, or sets an L<error|Module::Generic/error> and return C<undef> or an empty list depending on the context.
You can also set a maximum size to read by setting the attribute C<PAYLOAD_MAX_SIZE> in Apache configuration file.
For example:
<Directory /home/john/www>
PerlOptions +GlobalRequest
SetHandler modperl
# package inheriting from Apache2::API
PerlResponseHandler My::API
# 2Mb upload limit
PerlSetVar PAYLOAD_MAX_SIZE 2097152
</Directory>
This is just an example and not a recommandation. Your mileage may vary.
=head2 datetime
Returns a new L<Apache2::API::DateTime> object, which is used to parse and format dates for HTTP.
See L<Apache2::API/parse_datetime> and L<Apache2::API/format_datetime>
=head2 decode
Given a url-encoded string, this returns the decoded string, by calling L<APR::Request/decode>
This uses L<APR::Request> XS method.
See also L<rfc3986|https://datatracker.ietf.org/doc/html/rfc3986>
=head2 discard_request_body
my $rc = $req->discard_request_body;
In C<HTTP/1.1>, any method can have a body. However, most C<GET> handlers would not know what to do with a request body if they received one. This helper routine tests for and reads any message body in the request, simply discarding whatever it recei...
Returns C<Apache2::Const::OK> upon success.
use Apache2::API;
my $rc = $req->discard_request_body;
return( $rc ) if( $rc != Apache2::Const::OK );
This method calls L<Apache2::RequestIO/discard_request_body>
=head2 dnt
Sets or gets the environment variable C<HTTP_DNT> using L<Apache2::RequestRec/subprocess_env>. See L</env> below for more on that.
This is an abbreviation for C<Do not track>
If available, typical value is a boolean such as C<0> or C<1>
=head2 document_root
Sets or retrieve the document root for this server.
If a value is provided, it sets the document root to a new value only for the duration of the current request.
See L<Apache2::RequestUtil> for more information.
=head2 document_uri
Get the value for the environment variable C<DOCUMENT_URI>.
=head2 encode
Given a string, this returns its url-encoded version
This uses L<APR::Request> XS method.
=head2 env
my $val = $req->env( $name );
$req->env( $name, $value );
Using the Apache C<subprocess_env> table, this sets or gets environment variables. This is the equivalent of this:
$req->subprocess_env;
$env_table = $req->subprocess_env;
$req->subprocess_env( $key => $val );
$val = $req->subprocess_env( $key );
where C<$req> is this module object.
lib/Apache2/API/Request.pm view on Meta::CPAN
use APR::Brigade ();
use APR::Bucket ();
use Apache2::Filter ();
sub send_response_body
{
my( $req, $data ) = @_;
my $bb = APR::Brigade->new( $req->pool,
$req->connection->bucket_alloc );
my $b = APR::Bucket->new( $bb->bucket_alloc, $data );
$bb->insert_tail( $b );
$req->output_filters->fflush( $bb );
$bb->destroy;
}
In fact that's what C<< $req->read() >> does behind the scenes. But it also knows to parse HTTP headers passed together with the data and it also implements buffering, which the above function does not.
=head2 param
Provided a name, this returns its equivalent value, using L<Apache2::API::Request::Params/param>.
If C<$name> is an upload field, ie part of a multipart post data, it returns an L<Apache2::API::Request::Upload> object instead.
If a value is provided, this calls L<Apache2::API::Request::Param/param> providing it with the name ane value. This uses L<APR::Request::Param>.
=head2 params
Get the request parameters (using case-insensitive keys) by mimicing the OO interface of L<CGI::param>.
It can take as argument, only a key and it will then retrieve the corresponding value, or it can take a key and value pair to set them using L<Apache2::API::Request::Params/param>
If the value is an array, this will set multiple entry of the key for each value provided.
This uses Apache L<APR::Table> and works for both C<POST> and C<GET> methods.
If the methods received was a C<GET> method, this method returns the value of the L</query> method instead.
=head2 parse_date
Alias to L<Apache2::API::DateTime/parse_date>
=head2 path
Get the value for the environment variable C<PATH>
See also L</env>
=head2 path_info
my $path_info = $req->path_info();
my $prev_path_info = $req->path_info( $path_info );
Get or set the C<PATH_INFO>, what is left in the path after the C<< URI --> filename >> translation, by calling L<Apache2::RequestRec/path_info>
Return a string as the current value.
=head2 payload
Returns the JSON data decoded into a perl structure. This is set at object initiation phase and calls the L</data> method to read the incoming data and decoded it into perl internal utf8.
=head2 per_dir_config
Get the dir config vector, by calling L<Apache2::RequestRec/per_dir_config>. Returns a L<Apache2::ConfVector> object.
For an in-depth discussion, refer to the Apache Server Configuration Customization in Perl chapter.
=head2 pnotes
Share Perl variables between Perl HTTP handlers, using L<Apache2::RequestUtil/pnotes>.
# to share variables by value and not reference, $val should be a lexical.
$old_val = $req->pnotes( $key => $val );
$val = $req->pnotes( $key );
$hash_ref = $req->pnotes();
Note: sharing variables really means it. The variable is not copied. Only its reference count is incremented. If it is changed after being put in pnotes that change also affects the stored value. The following example illustrates the effect:
my $v = 1; my $v = 1;
$req->pnotes( 'v'=> $v ); $req->pnotes->{v} = $v;
$v++; $v++;
my $x = $req->pnotes('v'); my $x = $req->pnotes->{v};
=head2 pool
Returns the pool associated with the request as a L<APR::Pool> object of the L<Apache2 connection|Apache2::Connection>. If you rather want access to the pool object of the Apache2 request itself, use L</request>, such as:
# $rest being a Apache2::API object
my $request_pool = $req->pool;
$request_pool->cleanup_register( \&cleanup );
=head2 preferred_language
Given an array reference of supported languages, this method will get the client accepted languages by calling L</accept_language> and derive the best match, ie the client preferred language, using L<HTTP::AcceptLanguage>,.
It returns a string representing a language code.
Note that it does not matter if the array reference of supported language use underscore or dash, so both of the followings are equivalent:
my $best_lang = $req->preferred_language( [qw( en_GB fr_FR ja_JP ko_KR )] );
and
my $best_lang = $req->preferred_language( [qw( en-GB fr-FR ja-JP ko-KR )] );
If somehow, no suitable language could be found, it will return an empty string, and it will return C<undef> in scalar context, or an empty list in list context upon error, so check if the return value is defined or not.
See also: L</languages> and L</accept_language>
=head2 prev
my $prev_r = $req->prev();
Pointer to the previous request if this is an internal redirect, by calling L<Apache2::RequestRec/prev>.
Returns a L<Apache2::RequestRec> blessed reference to the previous (internal) request structure or C<undef> if there is no previous request.
=head2 protocol
my $protocol = $req->protocol();
( run in 0.517 second using v1.01-cache-2.11-cpan-2398b32b56e )