Apache2-API
view release on metacpan or search on metacpan
NAME
Apache2::API - Apache2 API Framework
SYNOPSIS
use Apache2::API
# To import in your namespace
# use Apache2::API qw( :common :http );
# $r is an Apache2::RequestRec object that you can get from within an handler or
# with Apache2::RequestUtil->request
my $api = Apache2::API->new( $r, compression_threshold => 204800 ) ||
die( Apache2::API->error );
# or:
my $api = Apache2::API->new( apache_request => $r, compression_threshold => 204800 ) ||
die( Apache2::API->error );
# or even inside your mod_perl script/cgi:
#!/usr/bin/perl
use strict;
use warnings;
use Apache2::API;
my $r = shift( @_ );
my $api = Apache2::API->new( $r );
# for example:
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.
compression_threshold( $integer )
The number of bytes threshold beyond which, the "reply" method will gzip
compress the data returned to the client.
decode_base64( $data )
Given some data, this will decode it using base64 algorithm. It uses
"decode" in APR::Base64 in the background.
decode_json( $data )
This decode from utf8 some data into a perl structure using JSON
If an error occurs, it will return undef and set an exception that can
be accessed with the error method.
decode_url( $string )
Given a url-encoded string, this returns the decoded string using
"decode" in APR::Request
decode_utf8( $data )
Decode some data from ut8 into perl internal utf8 representation using
Encode
If an error occurs, it will return undef and set an exception that can
be accessed with the error method.
encode_base64( $data )
Given some data, this will encode it using base64 algorithm. It uses
"encode" in APR::Base64.
encode_json( $hash_reference )
Given a hash reference, this will encode it into a json data
representation.
However, this will not utf8 encode it, because this is done upon
printing the data and returning it to the client.
The JSON object has the following properties enabled: "allow_nonref",
"allow_blessed", "convert_blessed" and "relaxed"
encode_url( $string )
Given a string, this returns its url-encoded version using "encode" in
APR::Request
encode_utf8( $data )
This encode in ut8 the data provided and return it.
If an error occurs, it will return undef and set an exception that can
be accessed with the error method.
generate_uuid
Generates an uuid string and return it. This uses APR::UUID
get_auth_bearer
Checks whether an "Authorization" HTTP header was provided, and get the
Bearer value.
If no header was found, it returns an empty string.
If an error occurs, it will return undef and set an exception that can
be accessed with the error method.
get_handlers
Returns a reference to a list of handlers enabled for a given phase.
$handlers_list = $res->get_handlers( $hook_name );
A list of handlers configured to run at the child_exit phase:
@handlers = @{ $res->get_handlers( 'PerlChildExitHandler' ) || []};
gettext( 'string id' )
Get the localised version of the string passed as an argument.
This is supposed to be superseded by the package inheriting from
Apache2::API, if any.
header_datetime( DateTime object )
Given a DateTime object, this sets it to GMT time zone and set the
proper formatter (Apache2::API::DateTime) so that the stringification is
compliant with HTTP headers standard.
htpasswd
my $ht = $api->htpasswd( $clear_password, create => 1 );
my $ht = $api->htpasswd( $clear_password, create => 1, salt => $salt );
my $ht = $api->htpasswd( $md5_password );
my $bool = $ht->matches( $user_input_password );
This instantiates a new Apache2::API::Password object by providing its
constructor whatever arguments was received.
It returns a new Apache2::API::Password object, or, upon error, "undef"
in scalar context, or an empty list in list context.
is_perl_option_enabled
Checks if perl option is enabled in the Virtual Host and returns a
boolean value
json
Returns a JSON object.
You can provide an optional hash or hash reference of properties to
enable or disable:
my $J = $api->json( pretty => 1, relaxed => 1 );
( run in 0.590 second using v1.01-cache-2.11-cpan-39bf76dae61 )