=encoding utf8

=head1 NAME

Any::Daemon::HTTP::VirtualHost - webserver virtual hosts

=head1 SYNOPSIS

 my $vhost  = Any::Daemon::HTTP::VirtualHost->new(@vhost_opts);
 my $daemon = Any::Daemon::HTTP->new
   ( @other_options
   , vhosts => $vhost  # or \@vhosts
   );

 # or
 my $daemon = Any::Daemon::HTTP->new(@other_opts);
 $daemon->addVirtualHost($vhost);
 $daemon->addVirtualHost(@vhost2_opts);

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

=head1 DESCRIPTION

These virtual host definitions are used by L<Any::Daemon::HTTP|Any::Daemon::HTTP>, to
implement (server) name based data seperation.  Its features resemble those
of Apache virtual hosts.

Each virtual host usually has to L<Any::Daemon::HTTP::Directory|Any::Daemon::HTTP::Directory> slaves: one
which describes the permissions for user directories (url paths in the
form C< /~user/ >) and one for data outside the user space.

=head1 METHODS

=head2 Constructors

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

=over 4

=item Any::Daemon::HTTP::VirtualHost-E<gt>B<new>(OPTIONS|HASH-of-OPTIONS)

 -Option     --Default
  aliases      []
  directories  <see text>
  documents    <undef>
  handlers     {}
  name         <required>
  rewrite      <undef>
  user_dirs    undef

=over 2

=item aliases => HOSTNAME|ARRAY-of-HOSTNAMES

=item directories => OBJECT|HASH|ARRAY

Pass one or more L<Any::Daemon::HTTP::Directory|Any::Daemon::HTTP::Directory> OBJECTS, or HASHes which will
be used to initialize them.

=item documents => DIRECTORY

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

=item handlers => CODE|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 client, the
request (HTTP::Request), uri object (URI).

=item name => HOSTNAME

=item rewrite => CODE

See L<rewrite()|Any::Daemon::HTTP::VirtualHost/"Basic daemon actions">.

=item user_dirs => undef|OBJECT|HASH

With an (empty?) HASH which contains instantiation parameter, an
L<Any::Daemon::HTTP::UserDirs|Any::Daemon::HTTP::UserDirs> is created for you, with
standard Apache behavior.  You may provide your own OBJECT.  Without
this parameter, there are no public user pages.

=back

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<aliases>()

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

=item $obj-E<gt>B<name>()

Returns the primary name for this server.

=back

=head2 Handler

=over 4

=item $obj-E<gt>B<addHandler>(CODE|(PATH => CODE)-LIST|HASH)

When only CODE is set, then this will be the default handler for all
paths (under '/', top).  You may also pass a list or HASH of PAIRS.

example: 

  $vhost->addHandler('/' => \&default_handler,
      '/upload' => \&upload_handler);

  $vhost->addHandler(\&default_handler);

=item $obj-E<gt>B<findHandler>(URI|PATH|PATH-SEGMENTS)

=back

=head2 Access permissions

=over 4

=item $obj-E<gt>B<handleRequest>(SERVER, SESSION, REQUEST, [URI])

=back

=head2 Basic daemon actions

=over 4

=item $obj-E<gt>B<allow>(SESSION, REQUEST, URI)

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 L</Allow access>.

=item $obj-E<gt>B<rewrite>(URI)

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

=back

=head2 Directories

=over 4

=item $obj-E<gt>B<addDirectory>(OBJECT|HASH|OPTIONS)

Either pass a L<Any::Daemon::HTTP::Directory|Any::Daemon::HTTP::Directory> OBJECT or the OPTIONS to
create the object.  When OPTIONS are provided, they are passed to
L<Any::Daemon::HTTP::Directory::new()|Any::Daemon::HTTP::Directory/"Constructors"> to create the OBJECT.

=item $obj-E<gt>B<directoryOf>(PATH|PATH_SEGMENTS)

Find the best matching L<Any::Daemon::HTTP::Directory|Any::Daemon::HTTP::Directory> object.

=item $obj-E<gt>B<filename>(URI)

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

=back

=head1 DETAILS

=head2 URI Rewrite

For each request, the L<rewrite()|Any::Daemon::HTTP::VirtualHost/"Basic daemon actions"> 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.

=head1 SEE ALSO

This module is part of Any-Daemon-HTTP distribution version 0.20,
built on October 11, 2013. Website: F<http://perl.overmeer.net/any-daemon/>

=head1 LICENSE

Copyrights 2013 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 F<http://www.perl.com/perl/misc/Artistic.html>

