View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Mark Overmeer > HTTP-Server-Multiplex > HTTP::Server::VirtualHost



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.11   Source  


HTTP::Server::VirtualHost - base-class for virtual host definitions


 HTTP::Server::VirtualHost is extended by


 use HTTP::Server::Multiplex;

 my $vhost  = HTTP::Server::VirtualHost->new(@vhost_opts);
 my $daemon = HTTP::Server::Multiplex->new
   ( @other_options
   , vhosts => $vhost

 # or
 my $daemon = HTTP::Server::Multiplex->new(@other_opts);

 # create object which extends HTTP::Server::VirtualHost
 my $myvhost = MyVHost->new(...);


These virtual host definitions are used by HTTP::Server::Multiplex, to implement (server) name based data seperation. Its features resemble those of Apache virtual hosts.

Each virtual host usually has to HTTP::Server::Directory slaves: one which describes the permissions for user directories (url paths in the form /~user/ ) and one for data outside the user space.



You may avoid the creation of extension classes for each virtual host, by using these options.


 Option        --Default
 aliases         []
 directories     <see text>
 directory_list  <false>
 documents       <undef>
 handlers        {}
 index_file      ['index.html', 'index.htm']
 name            <required>
 rewrite         <undef>
 user_dirs       <see text>


. directories => OBJECT|HASH|ARRAY

Pass one or more HTTP::Server::Directory OBJECTS, or HASHes which will be used to initialize them. If no information is provided, then only /~user urls and scripts can be used.

. directory_list => BOOLEAN

Enables the display of a directory, when it does not contain one of the index_file prepared defaults.

. documents => DIRECTORY

An absolute DIRECTORY for the location of the source files. Creates the most free HTTP::Server::Directory object. If you need things like access restrictions, then do not use this option but the directories option.

. handlers => HASH

The keys are path names, part of the request URIs. The values are CODE-references, called when that URI is addressed. The access rules are taken from the directory definition which is selected by the path, for that's all.

The handlers are called with a the connection (HTTP::Server::Connection), request (HTTP::Request), uri object (URI).

. index_file => STRING|ARRAY

When a directory is addressed, it is scanned whether one of these files exist. If so, the content will be shown.

. name => HOSTNAME

. rewrite => CODE

See rewrite().

. user_dirs => undef|OBJECT|HASH

If not specified, a HTTP::Server::Directory::UserDirs is created for you, with standard Apache behavior. You may provide your own OBJECT or a HASH which contains the parameters to create it. When you explicitly specify an undef value, then user directories will not be allowed.



Returns a list of all aliases (alternative names) for this server.


Returns the primary name for this server.


$obj->handleRequest(CONNECTION, REQUEST)


Re-check whether a request is really for this virtual host.

$obj->showDirectory(CONNECTION, REQUEST, PATH, LIST)

Overrule this method with the way you would like to display an automatically generated directory index.

Basic daemon actions


BE WARNED that the URI is the rewrite of the REQUEST uri, and therefore you should use that URI. The SESSION represents a user.

See "Allow access".


Returns an URI object as result, which may be the original in case of no rewrite was needed. See "URI Rewrite".



Either pass a HTTP::Server::Directory OBJECT or the OPTIONS to create the object.


Find the best matching HTTP::Server::Directory object.


Translate the URI into a filename, without checking for existence. Returns <undef> is not possible.

Access permissions


URI Rewrite

For each request, the rewrite() method is called to see whether a rewrite of the URI is required. The method must return the original URI object (the only parameter) or a new URI object.

example: rewrite URI

  package My::Virtual::Host;
  use base 'HTTP::Server::VirtualHost';

  my %lookup =
    ( '/'     => '/index-en.html'
    , '/news' => ''

  sub rewrite($)
  {  my ($self, $uri) = @_;

     # with lookup table
     $uri = URI->new_abs($lookup{$uri->path}, $uri)
         if exists $lookup{$uri->path};

     # whole directory trees
     $uri = URI->new_abs('/somewhere/else'.$1, $uri)
         if $uri->path =~ m!^/some/dir(/.*|$)!;
     # maybe more work in the base class


This module is part of HTTP-Server-Multiplex distribution version 0.11, built on October 01, 2008. Website:


Copyrights 2008 by Mark Overmeer. For other contributors see ChangeLog.

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

syntax highlighting: