NAME
Blosxom::Header - Missing interface to modify HTTP headers
SYNOPSIS
use Blosxom::Header;
my $header = Blosxom::Header->new;
$header->set(
Status => '304 Not Modified',
Last_Modified => 'Wed, 23 Sep 2009 13:36:33 GMT',
);
my $status = $header->get( 'Status' );
my $bool = $header->exists( 'ETag' );
my @deleted = $header->delete( qw/Content_Disposition Content_Length/ );
$header->push_cookie( @cookies );
$header->push_p3p( @p3p );
$header->clear;
# tie() interface (EXPERIMENTAL)
tie my %header, 'Blosxom::Header';
$header{Status} = '304 Not Modified';
my $value = $header{Status};
my $bool = exists $header{Status};
my $deleted = delete $header{Status};
my @keys = keys %header;
%header = ();
DESCRIPTION
Blosxom, an weblog application, globalizes $header which is a reference to hash. This application passes $header CGI::header() to generate HTTP headers.
package blosxom;
use CGI;
our $header = { -type => 'text/html' };
# Loads plugins
print CGI::header( $header );
header() doesn't care whether keys of $header are lowecased nor starting with a dash. The problem is multiple elements of $header may specify the same field:
package plugin_foo;
$blosxom::header->{-status} = '304 Not Modified';
package plugin_bar;
$blosxom::header->{Status} = '404 Not Found';
In above way, plugin developers can't modify HTTP headers consistently. Blosxom misses the interface. This module provides you the alternative way, and also some convenient methods described below.
METHODS
- $header = Blosxom::Header->new
-
Creates a new Blosxom::Header object.
- $header->set( $field => $value )
- $header->set( $f1 => $v1, $f2 => $v2, ... )
-
Sets the value of one or more header fields. Accepts a list of named arguments. The header field name ($field) isn't case-sensitive. We follow HTTP::Headers' way:
"To make the life easier for perl users who wants to avoid quoting before the => operator, you can use '_' as a replacement for '-' in header names."
The $value argument must be a plain string, except for when the Set-Cookie or P3P header is specified. In exceptional cases, $value may be a reference to an array.
$header->set( Set_Cookie => [ $cookie1, $cookie2 ] ); $header->set( P3P => [ qw/CAO DSP LAW CURa/ ] );
- $value = $header->get( $field )
- @values = $header->get( $field )
-
Returns a value of the specified HTTP header. In list context, a list of scalars is returned.
my @cookie = $header->get( 'Set_Cookie' ); my @p3p = $header->get( 'P3P' );
- $bool = $header->exists( $field )
-
Returns a Boolean value telling whether the specified HTTP header exists.
- @deleted = $header->delete( @fields )
-
Deletes the specified elements from HTTP headers. Returns values of deleted elements.
- $header->push( $field => @values )
-
This method is deprecated and will be removed in 0.04. Use push_cookie() or push_p3p() instead. An example convension is:
$header->push( Set_Cookie => @cookies ); $header->push( P3P => @p3p ); # Becomes $header->push_cookie( @cookies ); $header->push_p3p( @p3p );
-
Pushes the Set-Cookie headers onto HTTP headers. Returns the number of the elements following the completed push_cookie().
use CGI::Cookie; my $cookie = CGI::Cookie->new( -name => 'ID', -value => 123456, ); $header->push_cookie( $cookie );
- $header->push_p3p( @p3p )
-
$header->push_p3p( qw/foo bar/ );
- $header->clear
-
This will remove all header fields.
ATTRIBUTES
These methods can both be used to get() and set() the value of an attribute. The attribute value is set if you pass an argument to the method. If the given attribute didn't exists then undef is returned.
- $header->attachment
-
Can be used to turn the page into an attachment. Represents suggested name for the saved file.
$header->attachment( 'foo.png' );
In this case, the outgoing header will be formatted as:
Content-Disposition: attachment; filename="foo.png"
- $header->charset
-
Represents the character set sent to the browser. If not provided, defaults to ISO-8859-1.
$header->charset( 'utf-8' );
NOTE: If $header->type() contains 'charset', this attribute will be ignored.
-
Represents the Set-Cookie headers. The parameter can be an arrayref or a string.
$header->cookie( [ 'foo', 'bar' ] ); $header->cookie( 'baz' );
- $header->expires
-
The Expires header gives the date and time after which the entity should be considered stale. You can specify an absolute or relative expiration interval. The following forms are all valid for this field:
$header->expires( '+30s' ); # 30 seconds from now $header->expires( '+10m' ); # ten minutes from now $header->expires( '+1h' ); # one hour from now $header->expires( '-1d' ); # yesterday $header->expires( 'now' ); # immediately $header->expires( '+3M' ); # in three months $header->expires( '+10y' ); # in ten years time # at the indicated time & date $header->expires( 'Thu, 25 Apr 1999 00:40:33 GMT' );
- $header->nph
-
If set to a true value, will issue the correct headers to work with a NPH (no-parse-header) script:
$header->nph( 1 );
- $header->p3p
-
Will add a P3P tag to the outgoing header. The parameter can be an arrayref or a space-delimited string.
$header->p3p( [ qw/CAO DSP LAW CURa/ ] ); $header->p3p( 'CAO DSP LAW CURa' );
In either case, the outgoing header will be formatted as:
P3P: policyref="/w3c/p3p.xml" CP="CAO DSP LAW CURa"
- $header->status
-
Represents the Status header.
$header->status( '304 Not Modified' );
- $header->target
-
Represents the Window-Target header.
$header->target( 'ResultsWindow' );
- $header->type
-
The Content-Type header indicates the media type of the message content. If not defined, defaults to 'text/html'.
$header->type( 'text/plain' );
NOTE: If you don't want to output the Content-Type header, you have to set to an empty string:
$header->type( q{} );
DEPENDENCIES
Blosxom 2.0.0 or higher.
SEE ALSO
AUTHOR
Ryo Anazawa (anazawa@cpan.org)
LICENSE AND COPYRIGHT
Copyright (c) 2011-2012 Ryo Anazawa. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.