Skip to content
handle HTTP header properties
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


    CGI::Header::Props - handle HTTP header properties

      use CGI;
      use CGI::Header::Props;

      my $query = CGI->new;

      # HTTP header properties
      my $header = {
          type    => 'text/html',
          charset => 'utf-8'

      my $props = CGI::Header::Props->new(
          query   => $query,
          handler => 'header', # or 'redirect'
          header  => $header

      # inspect $header
      $props->get('Content-Length'); # => 3002
      $props->exists('Content-Length'); # => true

      # update $header 
      $props->set( 'Content-Length' => 3002 ); # overwrite
      $props->delete('Content-Length'); # => 3002
      $props->clear; # => $self

      # convenience methods
      $props->cookie( @cookies ); # @cookies are CGI::Cookie objects
      $props->p3p(qw/CAO DSP LAW CURa/);
      $props->status('301 Moved Permanently');

      $props->header; # same reference as $header

      # stringify $header
      $props->as_string; # invokes $query->redirect

    This document refers to CGI::Header::Props version 0.01.

    This module helps you handle HTTP header properties.
    Instances of application often hold those properties.'s "header" or "redirect" method is used to convert the header
    property into CGI response headers.

    This module is inspired by how CGI::Application handles the header
    property. The framework has "header_props" attribute. "header_add"
    method can be used to update "header_props". "header_type" represents
    which method of ("header" or "redirect") stringifies
    "header_props" when "run" is invoked.

    $props = CGI::Header::Props->new
        Create a new "CGI::Header::Props" object.

        Returns the header hash associated with this "CGI::Header::Props"
        object. This attribute defaults to a reference to an empty hash.

        Returns the query object associated with this "CGI::Header::Props"
        object. This attribute defaults to the Singleton instance of

    $self = $props->handler('redirect')
        Works like CGI::Application's "header_type()" method. This method
        can be used to declare that you are setting a redirection header.
        This attribute defaults to "header".

          $props->hadnler('redirect')->as_string; # invokes $props->query->redirect

    $self = $props->rehash
        Rebuilds the header hash to normalize property names without
        changing the reference. Returns this object itself. If property
        names aren't normalized, the methods listed below won't work as you

          my $h1 = $props->header;
          # => {
          #      '-content_type'   => 'text/plain',
          #      'Set-Cookie'      => 'ID=123456; path=/',
          #      'expires'         => '+3d',
          #      '-target'         => 'ResultsWindow',
          #      '-content-length' => '3002',
          # }


          my $h2 = $props->header; # same reference as $h1
          # => {
          #      '-type'           => 'text/plain',
          #      '-cookie'         => 'ID=123456; path=/',
          #      '-expires'        => '+3d',
          #      '-target'         => 'ResultsWindow',
          #      '-content-length' => '3002',
          # }

        Normalized property names are:

        1. lowercased
              'Content_Type' -> 'content_type'

        2. use dashes instead of underscores except for the first character
              'content_type' -> 'content-type''s "header()" method also accepts aliases of property names.
        This module converts them as follows:

          'content-type'  -> 'type'
          'cookies'       -> 'cookie'
          'set-cookie'    -> 'cookie'
          'uri'           -> 'location'
          'url'           -> 'location'
          'window-target' -> 'target'

        If a property name is duplicated, throws an exception:

          # => {
          #     -Type        => 'text/plain',
          #     Content_Type => 'text/html',
          # }

          $props->rehash; # die "Property "type' already exists"

    $value = $props->get( $field )
    $value = $props->set( $field => $value )
        Get or set the value of the header field. The field name ($field) is
        not case sensitive.


        The $value argument must be a plain string:

          $props->set( 'Content-Length' => 3002 );
          my $length = $props->get('Content-Length'); # => 3002

    $value = $props->delete( $field )
        Deletes the specified field. Returns the value of the deleted field.

          my $value = $props->delete('Content-Disposition'); # => "inline"

    $bool = $props->exists( $field )
        Returns a Boolean value telling whether the specified property

          if ( $props->exists('ETag') ) {

    $self = $props->clear
        This will remove all header properties. Returns this object itself.

        Stringifies the header props. associated with this object. The
        header props. will be passed to's "header()" or "redirect()"
        method (It depends on the return value of "$props->handler"). It's
        identical to:

          my $handler = $props->handler; # => "header" or "redirect"
          $props->query->$handler( $props->header );

    The following methods were named after property names recognized by's "header" method. Most of these methods can both be used to read
    and to set the value of a property.

    If you pass an argument to the method, the property value will be set,
    and also the current object itself will be returned ; therefore you can
    chain methods as follows:


    If no argument is supplied, the property value will be returned. If the
    given property doesn't exist, "undef" will be returned.

    $self = $props->attachment( $filename )
    $filename = $props->attachment
        Get or set the "attachment" property. Can be used to turn the page
        into an attachment. Represents suggested name for the saved file.

          my $filename = $props->attachment; # => "genome.jpg"

        In this case, the outgoing header will be formatted as:

          Content-Disposition: attachment; filename="genome.jpg"

    $self = $props->charset( $character_set )
    $character_set = $props->charset
        Get or set the "charset" property. Represents the character set sent
        to the browser.

    $self = $props->cookie( @cookies )
    @cookies = $props->cookie
        Get or set the "cookie" property. The parameter can be a list of
        CGI::Cookie objects.

    $props->push_cookie( @cookies )
        Given a list of CGI::Cookie objects, appends them to the "cookie"

    $self = $props->expires( $format )
    $format = $props->expires
        Get or set the "expires" property. 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:

          $props->expires('+30s'); # 30 seconds from now
          $props->expires('+10m'); # ten minutes from now
          $props->expires( '+1h'); # one hour from now
          $props->expires( 'now'); # immediately
          $props->expires( '+3M'); # in three months
          $props->expires('+10y'); # in ten years time

          # at the indicated time & date
          $props->expires('Thu, 25 Apr 1999 00:40:33 GMT');

        If set to a true value, the "date" property will be removed

    $self = $props->location( $url )
    $url = $props->location
        Get or set the Location header.


    $self = $props->nph( $bool )
    $bool = $props->nph
        Get or set the "nph" property. If set to a true value, will issue
        the correct headers to work with a NPH (no-parse-header) script.


    $self = $props->p3p( @tags )
    @tags = $props->p3p
        Get or set the "p3p" property. The parameter can be an array or a
        space-delimited string. Returns a list of P3P tags. (In scalar
        context, returns the number of P3P tags.)

          $props->p3p(qw/CAO DSP LAW CURa/);
          # or
          $props->p3p('CAO DSP LAW CURa');

          my @tags = $props->p3p; # => ("CAO", "DSP", "LAW", "CURa")
          my $size = $props->p3p; # => 4

        In this case, the outgoing header will be formatted as:

          P3P: policyref="/w3c/p3p.xml", CP="CAO DSP LAW CURa"

    $props->push_p3p( @tags )
        Given a list of P3P tags, appends them to the "p3p" property.

    $self = $props->status( $status )
    $status = $props->status
        Get or set the Status header.

          $props->status('304 Not Modified');

    $self = $props->target( $window_target )
    $window_target = $props->target
        Get or set the Window-Target header.


    $self = $props->type( $media_type )
    $media_type = $props->type
        Get or set the "type" property. Represents the media type of the
        message content.



    Ryo Anazawa (

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

Something went wrong with that request. Please try again.