The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Apache2-API-v0.3.0
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ Apache2::API::Request::Params

NAME

Apache2::API::Request::Params - Apache2 Request Fields Object

SYNOPSIS

    use Apache2::API::Request::Params;
    ## $r is the Apache2::RequestRec object
    my $req = Apache2::API::Request::Params->new(
        request         => $r,
        # pool of 2Mb
        brigade_limit   => 2097152,
        disable_uploads => 0,
        # For example: 3Mb
        read_limit      => 3145728,
        temp_dir        => '/home/me/my/tmp'
        upload_hook     => sub
        {
            my( $upload, $new_data ) = @_; 
            # do something
        },
    );

    my $form = $req->args;
    # but it is more efficient to call $request->params with $request being a Apache2::API::Request object
    my @args = $req->args;
    my $val = $req->args( 'first_name' );

    my $status = $req->args_status;

    my @names = $req->body;
    my @vals = $req->body( 'field' );
    my $status = $req->body_status;

    $req->brigade_limit( 1024 );
    my $bucket = $req->bucket_alloc;

    # No upload please
    $req->disable_uploads( 1 );

    # Returns a APR::Request::Cookie::Table object
    my $jar = $req->jar;
    my $cookie = $req->jar( 'cookie_name' );
    my @all = $req->jar( 'cookie_name' );
    my $status = $req->jar_status;

    # Returns a APR::Request::Param::Table object
    my $object = $req->param;
    my $val = $req->param( 'first_name' );
    my @multi_choice_values = $req->param( 'multi_choice_field' );
    # Note that $self->request->param( 'multi_choice_field' ) would return an array reference
    # $self being your object inheriting from Apache2::API
    my $status = $req->param_status;

    $req->parse;
    # Returns a APR::Pool object
    my $pool = $req->pool;

    my $limit = $req->read_limit;

    my $temp_dir = $req->temp_dir;

    my $upload_accessor = $req->upload;
    # Returns a Apache2::API::Request::Upload object
    my $object = $req->upload( 'file_upload' );
    # Returns a APR::Request::Param::Table object
    my $uploads = $req->uploads;

    $req->upload_hook( \&some_sub );

VERSION

    v0.1.1

DESCRIPTION

This is an interface to Apache mod_perl methods to access and manipulate the request data and the way Apache handles those incoming data.

This is taken from APR::Request, APR::Request::Params, APR::Request::Apache2 and Apache2::Request

There are some differences with Apache2::Request that provides similar interface. Apache2::API::Request::Params is more cautious when dealing with APR::Request::body and checks its status is 0 (i.e. successful) and traps any exceptions.

The instantiation makes no assumptions as to the data provided, which otherwise could lead to some unpleasant error, and we thrive to provide reliability as the backbone of a REST API.

Finally, it provides access to more APR::Request methods.

METHODS

new

This takes an hash or an hash reference of parameters, of which 1 is mandatory: the request parameter that must be an Apache2::RequestRec object.

The Apache2::RequestRec object can be retrieved with "request" in Apache2::API::Request and this module object can be instantiated more simply by calling "apr" in Apache2::API::Request, which is basically a shortcut.

Other possible parameters are: "brigade_limit", "disable_uploads", "read_limit", "temp_dir", "upload_hook".

They can also be accessed as methods as documented below.

args

With no arguments, this method returns a tied APR::Request::Param::Table object (or undef if the query string is absent) in scalar context, or the names (in order, with repetitions) of all the parsed query-string arguments.

With the $key argument, in scalar context this method fetches the first matching query-string arg. In list context it returns all matching args.

args() will throw an APR::Request::Error object whenever args_status() is non-zero and the return value is potentially invalid (eg scalar $req->args($key) will not die if the desired query argument was successfully parsed).

    $args = $req->args;
    @arg_names = $req->args;
    if( $args->isa('APR::Request::Param::Table') )
    {
        # ok then
    }
    ok shift( @arg_names ) eq $_ for( keys( %$args ) );

    $foo = $req->args( 'foo' );
    @bar = $req->args( 'bar' );

args_status

Returns the final status code of the Apache2::RequestRec handle's query-string parser.

body

With no arguments, this method returns a tied APR::Request::Param::Table object (or undef if the request body is absent) in scalar context, or the names (in order, with repetitions) of all the parsed cookies.

With the $key argument, in scalar context this method fetches the first matching body param. In list context it returns all matching body params.

"body" will throw an APR::Request::Error object whenever body_status() is non-zero and the return value is potentially invalid (eg scalar $req->body($key) will not die if the desired body param was successfully parsed).

    my $body = $req->body;
    my @body_names = $req->body;
    if( $body->isa('APR::Request::Param::Table') )
    {
        # ok then
    }
    ok shift( @body_names ) eq $_ for( keys( %$body ) );

    my $alpha = $req->body( 'alpha' );
    my @beta = $req->body( 'beta' );

body_status

Returns the final status code of the Apache2::RequestRec handle's body parser.

brigade_limit integer

Get or sets 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.

bucket_alloc

Returns the APR::BucketAlloc object associated to this Apache2::RequestRec handle.

disable_uploads boolean

Engage the disable_uploads hook for this request.

jar

With no arguments, this method returns a tied APR::Request::Cookie::Table object (or undef if the "Cookie" header is absent) in scalar context, or the names (in order, with repetitions) of all the parsed cookies.

With the $key argument, in scalar context this method fetches the first matching cookie. In list context it returns all matching cookies. The returned cookies are the values as they appeared in the incoming Cookie header.

This will trigger an APR::Request::Error if "jar_status" returned value is not zero.

    my $jar = $req->jar;
    my @cookie_names = $req->jar;
    if( $jar->isa( 'APR::Request::Cookie::Table' ) )
    {
        # ok then
    }
    ok shift( @cookie_names ) eq $_ for( keys( %$jar ) );

    my $cookie = $req->jar('apache');
    my @cookies = $req->jar('apache');

jar_status

Returns the final status code of the Apache2::RequestRec handle's cookie header parser.

param

With no arguments, this method returns a tied APR::Request::Param::Table object (or undef, if the query string and request body are absent) in scalar context, or the names (in order, with repetitions) of all the incoming (args + body) params.

With the $key argument, in scalar context this method fetches the first matching param. In list context it returns all matching params.

"param" will throw an APR::Request::Error object whenever param_status() is non-zero and the return value is potentially invalid (eg scalar $req-param($key)> will not die if the desired param was successfully parsed).

    my $param = $req->param;
    my @param_names = $req->param;
    if( $param->isa(' APR::Request::Param::Table' ) )
    {
        # ok then
    }
    ok shift( @param_names ) eq $_ for( keys( %$param ) );

    my $foo = $req->param( 'foo' );
    my @foo = $req->param( 'foo' );

param_status

Returns ($req-args_status, $req->body_status)> in list context; otherwise returns $req->args_status || $req->body_status.

parse

Parses the jar, args, and body tables. Returns $req->jar_status, $req->args_status, $req->body_status.

However, it is more efficient to write:

    sub handler
    {
        my $r = shift( @_ );
        my $req = Apache2::API::Request::Params->new( request => $r );
        # efficiently parses the request body
        $r->discard_request_body;
        my $parser_status = $req->body_status;
        # ...
    }

pool

Returns the APR::Pool object associated to this Apache2::RequestRec handle.

read_limit integer

Get/set the read limit, which controls the total amount of bytes that can be fed to the current parser.

temp_dir string

Get/set the spool directory for uploads which exceed the configured brigade_limit.

upload

With no arguments, this method returns a tied APR::Request::Param::Table object (or undef if the request body is absent) in scalar context (whose entries are Apache2::API::Request::Params::Upload objects inherited from APR::Request::Param), or the names (in order, with repetitions) of all the incoming uploads.

If one ore more arguments are provided, they are taken as data upload field names and their corresponding Apache2::API::Request::Params::Upload objects are returned as a list in list context or the first one on the list in scalar context.

More generally, "upload" follows the same pattern as "param" with respect to its return values and argument list. The main difference is that its returned values are Apache2::API::Request::Param::Upload object refs, not simple scalars.

uploads

This returns an APR::Request::Param::Table. This is different from the "upload" in Apache2::API::Request who returns an array reference of Apache2::API::Request::Params::Upload objects.

upload_hook code reference

Provided with a code reference, this adds an upload hook callback for this request. The arguments to the $callback sub are ($upload, $new_data).

    $r->upload_hook(sub
    {
        my( $upload, $new_data ) = @_;
        # do something
    });

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Apache2::Request, APR::Request, APR::Request::Param, APR::Request::Apache2

COPYRIGHT & LICENSE

Copyright (c) 2023 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.