Apache2-API
view release on metacpan or search on metacpan
return( $api->reply( Apache2::Const::HTTP_OK => { message => "Hello world" } ) );
my $r = $api->apache_request;
return( $api->bailout({
message => "Oops",
code => Apache2::Const::BAD_REQUEST,
public_message => "An unexpected error occurred.",
}) );
# or
return( $api->bailout( @some_reasons ) );
# 100kb
$api->compression_threshold(102400);
my $decoded = $api->decode_base64( $b64_string );
my $ref = $api->decode_json( $json_data );
my $decoded = $api->decode_url;
my $perl_utf8 = $api->decode_utf8( $data );
my $b64_string = $api->encode_base64( $data );
my $json_data = $api->encode_json( $ref );
my $encoded = $api->encode_url( $uri );
my $utf8 = $api->encode_utf8( $data );
my $uuid = $api->generate_uuid;
my $auth = $api->get_auth_bearer;
my $handlers = $api->get_handlers;
my $dt = $api->header_datetime( $http_datetime );
my $bool = $api->is_perl_option_enabled;
# JSON object
my $json = $api->json( pretty => 1, sorted => 1, relaxed => 1 );
my $lang = $api->lang( 'en_GB' );
# en_GB
my $lang = $api->lang_unix;
# en-GB
my $lang = $api->lang_web;
$api->log_error( "Oops" );
$api->print( @some_data );
$api->push_handlers( $name => $code_reference );
return( $api->reply( Apache2::Const::HTTP_OK => {
message => "All good!",
# arbitrary property
client_id => "efe4bcf3-730c-4cb2-99df-25d4027ec404",
# special property
cleanup => sub
{
# Some code here to be executed after the reply is sent out to the client.
}
}) );
# Apache2::API::Request
my $req = $api->request;
# Apache2::API::Response
my $req = $api->response;
my $server = $api->server;
my $version = $api->server_version;
$api->set_handlers( $name => $code_reference );
$api->warn( @some_warnings );
my $hash = apr1_md5( $clear_password );
my $hash = apr1_md5( $clear_password, $salt );
my $ht = $api->htpasswd( $clear_password );
my $ht = $api->htpasswd( $clear_password, salt => $salt );
my $hash = $ht->hash;
say "Does our password match ? ", $ht->matches( $user_clear_password ) ? "yes" : "not";
VERSION
v0.5.1
DESCRIPTION
This module provides a comprehensive, powerful, yet simple framework to
access Apache mod_perl's API <https://perl.apache.org/docs/2.0/api/> and
documented appropriately.
Apache mod_perl is an awesome framework, but quite complexe with a steep
learning curve and methods all over the place. So much so that they have
developed a module dedicated to find appropriate methods
<https://perl.apache.org/docs/2.0/user/coding/coding.html#toc_Where_the_
Methods_Live> with ModPerl::MethodLookup
METHODS
new
my $api = Apache2::API->new( $r, $hash_ref_of_options );
# or
my $api = Apache2::API->new( apache_request => $r, compression_threshold => 102400 );
This initiates the package and takes an Apache2::RequestRec object and
an hash or hash reference of parameters, or only an hash or hash
reference of parameters:
* "apache_request"
See "apache_request"
* "compression_threshold"
See "compression_threshold"
* "debug"
Optional. If set with a positive integer, this will activate
debugging message
apache_request
Returns the Apache2::RequestRec object that was provided upon object
instantiation.
bailout
$api->bailout( $error_string );
$api->bailout( { code => 400, message => $internal_message } );
$api->bailout( { code => 400, message => $internal_message, public_message => "Sorry!" } );
Given an error message, this will prepare the HTTP header and response
accordingly.
It will call "gettext" to get the localised version of the error
message, so this method is expected to be overriden by inheriting
package.
If the outgoing content type set is "application/json" then this will
return a properly formatted standard json error, such as:
{ "error": { "code": 401, "message": "Something went wrong" } }
Otherwise, it will send to the client the message as is.
instantiation.
response
Returns the Apache2::API::Response object. This object is set upon
instantiation.
server()
Returns a Apache2::Server object
server_version
Tries hard to find out the version number of the Apache server. This
returns the value from "server_version" in Apache2::API::Request
set_handlers()
Returns the values from "set_handlers" in Apache2::Server by passing it
whatever arguments were provided.
use_rfc_error
Boolean. When true, this will return rfc9457 style error
<https://www.rfc-editor.org/rfc/rfc9457.html>
warn( @list )
Given a list of string, this sends a warning using "warn" in
Apache2::Log
_try( $object_type, $method_name, @_ )
Given an object type, a method name and optional parameters, this
attempts to call it, passing it whatever arguments were provided and
return its return values.
Apache2 methods are designed to die upon error, whereas our model is
based on returning "undef" and setting an exception with
Module::Generic::Exception, because we believe that only the main
program should be in control of the flow and decide whether to interrupt
abruptly the execution, not some sub routines.
CLASS FUNCTIONS
apr1_md5
my $md5_password = apr1_md5( $clear_password );
my $md5_password = apr1_md5( $clear_password, $salt );
This class function is exported by default.
It takes a clear password, and optionally a salt, and returns an Apache
md5 encoded password.
This function merely instantiates a new Apache2::API::Password object,
and calls the method hash to return the encoded password.
The password returned is suitable to be used and saved in an Apache
password file used in web basic authentication.
Upon error, this will die.
CONSTANTS
"mod_perl" provides constants through Apache2::Constant and
APR::Constant. Apache2::API makes all those constants available using
their respective package name, such as:
use Apache2::API;
say Apache2::Const::HTTP_BAD_REQUEST; # 400
You can import constants into your namespace by specifying them when
loading Apache2::API, such as:
use Apache2::API qw( HTTP_BAD_REQUEST );
say HTTP_BAD_REQUEST; # 400
Be careful, however, that there are over 400 Apache2 constants and some
common constant names in Apache2::Constant and APR::Constant, so it is
recommended to use the fully qualified constant names rather than
importing them into your namespace.
Some constants are special like "OK", "DECLINED" or "DECLINE_CMD"
Apache underlines
<https://perl.apache.org/docs/2.0/user/handlers/http.html#toc_HTTP_Reque
st_Cycle_Phases> that "all handlers in the chain will be run as long as
they return Apache2::Const::OK or Apache2::Const::DECLINED. Because
stacked handlers is a special case. So don't be surprised if you've
returned Apache2::Const::OK and the next handler was still executed.
This is a feature, not a bug."
* "Apache2::Const::OK"
The only value that can be returned by all handlers is
"Apache2::Const::OK", which tells Apache that the handler has
successfully finished its execution.
* "Apache2::Const::DECLINED"
This indicates success, but it's only relevant for phases of type
RUN_FIRST ("PerlProcessConnectionHandler", "PerlTransHandler",
"PerlMapToStorageHandler", "PerlAuthenHandler", "PerlAuthzHandler",
"PerlTypeHandler", "PerlResponseHandler"
Apache2 documentation explains
<https://perl.apache.org/docs/2.0/api/Apache2/RequestRec.html#toc_C_
allowed_> that "generally modules should "Apache2::Const::DECLINED"
any request methods they do not handle."
* "Apache2::Const::DONE"
This "tells Apache to stop the normal HTTP request cycle and fast
forward to the PerlLogHandler,"
Check Apache documentation on handler return value
<https://perl.apache.org/docs/2.0/user/handlers/intro.html#toc_Handler_R
eturn_Values> for more information.
INSTALLATION
As usual, to install this module, you can do:
perl Makefile.PL
make
make test
# or
# t/TEST
sudo make install
If you have Apache/modperl2 installed, this will also prepare the
Makefile and run test under modperl.
The Makefile.PL tries hard to find your Apache configuration, but you
can give it a hand by specifying some command line parameters.
For example:
( run in 1.875 second using v1.01-cache-2.11-cpan-d7a12ab2c7f )