The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-Easy-v2.0.1
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ CGI::Easy::Headers

NAME

CGI::Easy::Headers - Manage HTTP headers

VERSION

This document describes CGI::Easy::Headers version v2.0.1

SYNOPSIS

    use CGI::Easy::Headers;

    my $h = CGI::Easy::Headers->new();

    $h->{Expires} = 'Sat, 01 Jan 2000 00:00:00 GMT';
    $h->add_cookie({
        name    => 'somevar',
        value   => 'someval',
        expires => time + 86400,
        domain  => '.example.com',
        path    => '/admin/',
        secure  => 1,
    });
    print $h->compose(), '<html>...</html>';

    $h->redirect('http://google.com/');
    print $h->compose();

    $h->require_basic_auth('Secret Area');
    print $h->compose();

DESCRIPTION

Provides user with simple hash where user can easy add/modify/delete HTTP headers while preparing them for sending in CGI reply.

INTERFACE

new

    $h = CGI::Easy::Headers->new();
    $h = CGI::Easy::Headers->new( \%headers );

Create new CGI::Easy::Headers object/hash with these fields:

    'Status'        => '200 OK',
    'Content-Type'  => 'text/html; charset=utf-8',
    'Date'          => q{},
    'Set-Cookie'    => [],

If %headers given, it will be appended to default keys and so may overwrite default values.

See compose() below about special values in 'Date' and 'Set-Cookie' fields.

While you're free to add/modify/delete any fields in this object/hash, HTTP headers is case-insensitive, and thus it's possible to accidentally create different keys in this hash for same HTTP header:

    $h->{'Content-Type'} = 'text/plain';
    $h->{'content-type'} = 'image/png';

To protect against this, compose() allow only keys named in 'Content-Type' way and will throw exception if it found keys named in other way. There few exceptions from this rule: 'ETag', 'WWW-Authenticate' and 'Digest-MD5'.

Return created CGI::Easy::Headers object.

    $h->add_cookie( \%cookie );
    $h->add_cookie( \%cookie1, \%cookie2, ... );

Add new cookies to current HTTP headers. Actually it's just do this:

    push @{ $h->{'Set-Cookie'} }, \%cookie, ...;

Possible keys in %cookie:

    name        REQUIRED STRING
    value       OPTIONAL STRING (default "")
    domain      OPTIONAL STRING (default "")
    path        OPTIONAL STRING (default "/")
    expires     OPTIONAL STRING or SECONDS
    secure      OPTIONAL BOOL

Format for "expires" should be either correct date 'Thu, 01-Jan-1970 00:00:00 GMT' or time in seconds.

Return nothing.

redirect

    $h->redirect( $url );
    $h->redirect( $url, $status );

Set HTTP headers 'Location' and 'Status'.

If $status not provided, use '302 Found'.

Return nothing.

require_basic_auth

    $h->require_basic_auth();
    $h->require_basic_auth( $realm );

Set HTTP headers 'WWW-Authenticate' and 'Status'.

Return nothing.

compose

    $headers = $h->compose();

Render all object's fields into single string with all HTTP headers suitable for sending to user's browser.

Most object's field values expected to be simple strings (or ARRAYREF with strings for headers with more than one values) which should be copied to HTTP headers as is:

    $h->{ETag} = '123';
    $h->{'X-My-Header'} = 'my value';
    $h->{'X-Powered-By'} = ['Perl', 'CGI::Easy'];
    $headers = $h->compose();
    # $headers will be:
    #   "ETag: 123\r\n" . 
    #   "X-My-Header: my value\r\n" .
    #   "X-Powered-By: Perl\r\n" .
    #   "X-Powered-By: CGI::Easy\r\n" .
    #   "\r\n"

But there few fields with special handling:

Date

You can set it to usual string (like 'Sat, 01 Jan 2000 00:00:00 GMT') or to unixtime in seconds (as returned by time()) - in later case time in seconds will be automatically converted to string with date/time.

If it set to empty string (new() will initially set it this way), then current date/time will be automatically used.

This field must be ARRAYREF (new() will initially set it to []), and instead of strings must contain HASHREF with cookie properties (see add_cookie() above).

Return string with HTTP headers ending with empty line. Throw exception on keys named with wrong case (see new() about details).

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/powerman/perl-CGI-Easy/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests.

https://github.com/powerman/perl-CGI-Easy

    git clone https://github.com/powerman/perl-CGI-Easy.git

Resources

AUTHOR

Alex Efros <powerman@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2009- by Alex Efros <powerman@cpan.org>.

This is free software, licensed under:

  The MIT (X11) License