view release on metacpan or  search on metacpan

lib/Apache2/API/Request.pm  view on Meta::CPAN

    AllowOverride AuthConfig

The following applies:

    use Apache2::API;
    $req->allow_overrides & Apache2::Const::OR_AUTHCFG; # true
    $req->allow_overrides & Apache2::Const::OR_LIMIT; # false

See also L<https://httpd.apache.org/docs/2.4/en/mod/core.html#allowoverride>

=head2 allow_override_opts

    my $bitmask = $req->allow_override_opts;

Retrieve the bitmask value of allowed C<Options> set by C<AllowOverride Options> Apache configuration directive, by calling L<Apache2::Access/allow_override_opts>

You would need to use Apache constants against the returned value.

For example if the configuration for the current request was:

    AllowOverride Options=Indexes,ExecCGI

The following applies:

    use Apache2::API;
    $req->allow_override_opts & Apache2::Const::OPT_EXECCGI; # true
    $req->allow_override_opts & Apache2::Const::OPT_SYM_LINKS; # false

Note that enabling single options was introduced in Apache 2.2. For Apache 2.0 this function returns:

    Apache2::Const::OPT_UNSET | Apache2::Const::OPT_ALL | Apache2::Const::OPT_INCNOEXEC | Apache2::Const::OPT_SYM_OWNER | Apache2::Const::OPT_MULTI

which corresponds to the default value (if not set) for Apache 2.2.

See also L<https://httpd.apache.org/docs/2.4/en/mod/core.html#allowoverride>

=head2 apache

This is an alias for L</request>. It returns an L<RequestRec> object.

=head2 apr

Returns a L<Apache2::API::Request::Param> object used to access Apache mod_perl methods to manipulate request data.

=head2 args

    my $hash_ref = $req->args;
    my @names = $req->args;
    my $first_value = $req->args( $name );
    my @values = $req->args( $name );

    my $table = $req->args;
    # The keys are case-insensitive.
    $table->set( $key => $val );
    $table->unset( $key );
    $table->add( $key, $val );
    $val = $table->get( $key );
    @val = $table->get( $key );
    $table->merge( $key => $val );
    $table_overlay = $table_base->overlay( $table_overlay, $pool );
    $table_overlay->compress( APR::Const::OVERLAP_TABLES_MERGE );

    $table_a->overlap( $table_b, APR::Const::OVERLAP_TABLES_SET );

Get or sets the query string data by calling L<APR::Body/args>

With no arguments, this method returns a tied L<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 in list context.

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

See also L</query> for the equivalent, but using L<Apache2::API::Query> instead of L<APR::Body/args>

See also L</query_string> to set or get the query string as a string.

=head2 args_status

    my $int = $req->args_status; # should be 0

Returns the final status code of the query-string parser.

=head2 as_string

Returns the HTTP request as a string by calling L<Apache2::RequestUtil/as_string>

=head2 auth

Returns the C<Authorization> header value if any. This ill have been processed upon object initiation phase.

=head2 auth_headers

    $req->auth_headers;

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works only for basic and digest authentication, by calling L<Apache2::Access/note_auth_failure>

This method requires C<AuthType> to be set to C<Basic> or C<Digest>. Depending on the setting it will call either L</auth_headers_basic> or L</auth_headers_digest>.

It does not return anything.

=head2 auth_headers_basic

    $req->auth_headers_basic;

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works only for basic authentication.

It does not return anything.

=head2 auth_headers_digest

    $req->auth_headers_digest;

Setup the output headers so that the client knows how to authenticate itself the next time, if an authentication request failed. This function works only for digest authentication.

It does not return anything.

=head2 auth_name

    my $auth_name = $req->auth_name();
    my $auth_name = $req->auth_name( $new_auth_name );

Sets or gets the current Authorization realm, i.e. the per directory configuration directive C<AuthName>

lib/Apache2/API/Request.pm  view on Meta::CPAN

=head2 headers

Gets or sets the HTTP request headers using L<APR::Table> by calling L</Apache2::RequestRec/headers_in>

This takes zero, one or sets or C<< key => value >> pairs.

When no argument is provided, this returns the L<APR::Table> object.

When one argument is provided, it returns the corresponding HTTP header value, if any.

You can set multiple key-value pairs, like so:

    $req->headers( $var1 => $val1, $var2 => $val2 );

If a value provided is C<undef>, it will remove the corresponding HTTP headers.

With the L<APR::Table> object, you can access and set header fields directly, such as:

    my $accept = $req->headers->{Accept};
    $req->headers->{Accept} = 'application/json';
    $req->headers->{Accept} = undef; # unset it

or

    my $accept = $req->headers->get( 'Accept' );
    $req->headers->set( Accept => 'application/json' );
    $req->headers->unset( 'Accept' );
    $req->headers->add( Vary => 'Accept-Encoding' );
    # Very useful for this header
    $req->headers->merge( Vary => 'Accept-Encoding' );
    # Empty the headers
    $req->headers->clear;
    use APR::Const qw( :table );
    # to merge: multiple values for the same key are flattened into a comma-separated list.
    $req->headers->compress( APR::Const::OVERLAP_TABLES_MERGE );
    # to overwrite: each key will be set to the last value seen for that key.
    $req->headers->compress( APR::Const::OVERLAP_TABLES_SET );
    my $table = $req->headers->copy( $req2->pool );
    my $headers = $req->headers;
    $req->headers->do(sub
    {
        my( $key, $val ) = @_;
        # Do something
        # return(0) to abort
    }, keys( %$headers ) );
    # or without any filter keys
    $req->headers->do(sub
    {
        my( $key, $val ) = @_;
        # Do something
        # return(0) to abort
    });
    # To prepare a table of 20 elements, but the table can still grow
    my $table = APR::Table::make( $req->pool, 20 );
    my $table2 = $req2->headers;
    # overwrite any existing keys in our table $table
    $table->overlap( $table2, APR::Const::OVERLAP_TABLES_SET );
    # key, value pairs are added, regardless of whether there is another element with the same key in $table
    $table->overlap( $table2, APR::Const::OVERLAP_TABLES_MERGE );
    my $table3 = $table->overlay( $table2, $pool3 );

See L<APR::Table> for more information.

=head2 header_only

This is the same as L</is_header_only>

=head2 headers_as_hashref

Returns the list of headers as an hash reference, by calling L<Apache2::RequestRec/headers_in>

Since the call to L<Apache2::RequestRec> returns a L<APR::Table> object, we may get 2 or more same key name, and in that case, the hash with that key will have as a value an array reference.

=head2 headers_as_json

Returns the list of headers as a json data, by retrieving the hash from L</headers_as_hashref> and encode it with L<JSON>

=head2 headers_in

Returns the list of the headers as special hash, which is actually an L<APR::Table> object.

If a header name is provided, you can retrieve its value like so:

    my $cookie = $req->headers_in->{Cookie} || '';

=head2 headers_out

This is identical to L</headers_in>, as it returns a L<APR::Table> object.

Returns or sets the key => value pairs of outgoing HTTP headers, only on 2xx responses.

See also L</err_headers_out>, which allows to set headers for non-2xx responses and persist across internal redirects.

More information at L<Apache2::RequestRec/headers_out>

=head2 hostname

Retrieve or set the HTTP server host name, such as C<www.example.com>, by calling L<Apache2::RequestRec/hostname>

This is not the machine hostname.

More information at L<Apache2::RequestRec>

=head2 http_host

Returns an C<URI> object of the HTTP host being accessed. This is created during object initiation phase.

This calls the method C<host> on the L<URI> object returned by L</uri>

=head2 id

Returns the connection id; unique at any point in time, by calling L<Apache2::Connection/id>.

See L<Apache2::Connection> for more information.

This is the same as L</connection_id>

=head2 if_modified_since

Returns the value of the HTTP header If-Modified-Since as a C<DateTime> object.