view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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"

README  view on Meta::CPAN

    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 );

    Each property corresponds to one that is supported by JSON

    It also supports "ordered", "order" and "sort" as an alias to
    "canonical"

  lang( $string )
    Set or get the language for the API. This would typically be the HTTP
    preferred language.

  lang_unix( $string )
    Given a language, this returns a language code formatted the unix way,
    ie en-GB would become en_GB

  lang_web( $string )
    Given a language, this returns a language code formatted the web way, ie
    en_GB would become en-GB

  log
        $api->log->emerg( "Urgent message." );
        $api->log->alert( "Alert!" );
        $api->log->crit( "Critical message." );
        $api->log->error( "Error message." );
        $api->log->warn( "Warning..." );
        $api->log->notice( "You should know." );
        $api->log->info( "This is for your information." );
        $api->log->debug( "This is debugging message." );

    Returns a Apache2::Log::Request object.

  log_error( $string )
    Given a string, this will log the data into the error log.

    When log_error is accessed with the Apache2::RequestRec the error gets
    logged into the Virtual Host log, but when log_error gets accessed via
    the Apache2::ServerUtil object, the error get logged into the Apache
    main error log.

  print( @list )
    print out the list of strings and returns the number of bytes sent.

    The data will possibly be compressed if the HTTP client acceptable
    encoding
    <HTTPs://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encodi
    ng> and if the data exceeds the value set in "compression_threshold"

    It will gzip it if the HTTP client acceptable encoding is "gzip" and if
    IO::Compress::Gzip is installed.

    It will bzip it if the HTTP client acceptable encoding is "bzip2" and if
    IO::Compress::Bzip2 is installed.

    It will deflate if if the HTTP client acceptable encoding is "deflate"
    and IO::Compress::Deflate is installed.

    If none of the above is possible, the data will be returned
    uncompressed.

    Note that the HTTP header "Vary" will be added the "Accept-Encoding"
    value.

  push_handlers
    Returns the values from "push_handlers" in Apache2::Server by passing it
    whatever arguments were provided.

  reply
    This takes an HTTP code and a message, or an exception object such as
    Module::Generic::Exception or any other object that supports the "code"
    and "message" method, or just a hash reference, reply will find out if
    the code provided is an error and format the replied json appropriately
    like: