NAME

CGI::Application::Plugin::Header - Plugin for handling header props.

SYNOPSIS

package MyApp;
use parent 'CGI::Application';
use CGI::Application::Plugin::Header;

sub do_something {
    my $self = shift;

    my $header = $self->header; # => CGI::Header object

    # get header props.
    my $type = $header->type; # => "text/plain"

    # set header props.
    $header->type("text/html");

    # compatible with the core methods of CGI::Application
    $self->header_props( type => "text/plain" );
    $self->header_add( type => "text/plain" );

    ...
}

DESCRIPTION

This plugin provides you the common syntax to handle CGI.pm-compatible HTTP header properties.

By using this plugin, your application is capable of the following methods, where $cgiapp denotes the instance of your application which inherits from CGI::Application:

ATTRIBUTES

$header = $cgiapp->header

Returns a CGI::Header object associated with $cgiapp. You can use all methods of $header.

sub cgiapp_postrun {
    my ( $self, $body_ref ) = @_;
    $self->header->set( 'Content-Length' => length $$body_ref );
}

$header = $cgiapp->header( CGI::Header->new(...) )

You can also define your header class which inherits from CGI::Header. For example,

package MyApp::Header;
use parent 'CGI::Header';
use CGI::Cookie;

sub cookies {
    my $self    = shift;
    my $cookies = $self->header->{cookies} ||= [];

    return $cookies unless @_;

    if ( ref $_[0] eq 'HASH' ) {
        push @$cookies, map { CGI::Cookie->new($_) } @_;
    }
    else {
        push @$cookies, CGI::Cookie->new( @_ );
    }

    $self;
}

You can set header as follows:

# using new()

my $query  = CGI->new;
my $header = MyApp::Header->new( query => $query );
my $app    = MyApp->new( query => $query, header => $header );


# using header()

my $app = MyApp->new;

$app->header( MyApp::Header->new( query => $app->query ) );

METHODS

This plugin overrides the following methods of CGI::Application:

%header_props = $cgiapp->header_props

%header_props = $cgiapp->header_props( $k1 => $v1, $k2 => $v2, ... )

%header_props = $cgiapp->header_props({ $k1 => $v1, $k2 => $v2, ... })

%header_props = $cgiapp->header_props({})

Behaves like CGI::Application's header_props method, but the return format is modified. keys of %header_props are lowercased and start with a dash. The following aliases are used:

'-content-type' -> '-type'
'-cookie'       -> '-cookies'

It's guaranteed that the keys are unique.

$cgiapp->header_add( $k1 => $v1, $k2 => $v2, ... )

$cgiapp->header_add({ $k1 => $v1, $k2 => $v2, ... })

Behaves like CGI::Application's header_add method.

COMPATIBILITY

Header property names are normalized by $header automatically, and so this plugin breaks your code which depends on the return value of header_props:

my %header_props = $cgiapp->header_props; # => ( -cookies => 'ID=123456' )

if ( exists $header_props{-cookie} ) {
    ...
}

Those codes can be rewritten using $header as well as header_props or header_add:

if ( $cgiapp->header->exists('-cookie') ) {
    ...
}

The following plugins are compatible with this module:

CGI::Application::Plugin::Redirect

The following plugins are roughly compatible with this module:

CGI::Application::Plugin::Stream

"Setting a custom Content-Length/-Content-Length header" is not supported by this module. In other words, the stream_file method always overwrites the Content-Length header.

CGI::Application::Plugin::Session

You need to overwrite the alias table of CGI::Header:

use parent 'CGI::Header';

sub _build_alias {
    +{
        'cookies'      => 'cookie',
        'content-type' => 'type',
    };
}

sub cookies {
    my $self = shift;
    return $self->header->{cookies} unless @_;
    $self->header->{cookies} = shift;
    $self;
}

sub cookie {
    my $self = shift;
    $self->cookies(@_);
}

AUTHOR

Ryo Anazawa (anazawa@cpan.org)

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.