view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    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...

# 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](https://metacpan.org/pod/Apache2%3A%3ARequestRec) object and an hash or hash reference of parameters, or only an hash or hash reference of parameters:

- `apache_request`

    See ["apache\_request"](#apache_request)

- `compression_threshold`

    See ["compression\_threshold"](#compression_threshold)

- `debug`

    Optional. If set with a positive integer, this will activate debugging message

## apache\_request

Returns the [Apache2::RequestRec](https://metacpan.org/pod/Apache2%3A%3ARequestRec) 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"](#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"](#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](https://metacpan.org/pod/APR%3A%3ABase64#decode) in the background.

## decode\_json( $data )

This decode from utf8 some data into a perl structure using [JSON](https://metacpan.org/pod/JSON)

If an error occurs, it will return undef and set an exception that can be accessed with the [error](https://metacpan.org/pod/Module%3A%3AGeneric#error) method.

## decode\_url( $string )

Given a url-encoded string, this returns the decoded string using ["decode" in APR::Request](https://metacpan.org/pod/APR%3A%3ARequest#decode)

## decode\_utf8( $data )

Decode some data from ut8 into perl internal utf8 representation using [Encode](https://metacpan.org/pod/Encode)

If an error occurs, it will return undef and set an exception that can be accessed with the [error](https://metacpan.org/pod/Module%3A%3AGeneric#errir) method.

## encode\_base64( $data )

Given some data, this will encode it using base64 algorithm. It uses ["encode" in APR::Base64](https://metacpan.org/pod/APR%3A%3ABase64#encode).

## 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](https://metacpan.org/pod/APR%3A%3ARequest#encode)

## 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](https://metacpan.org/pod/APR%3A%3AUUID)

## 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' ) || []};