NAME

VBTK::PHttpd - Generic web server built on the HTTP::Daemon library

SYNOPSIS

  use VBTK::PHtml;
  use VBTK::PHttpd;

  # Pass most of the parameters on to create a PHttpd object    
  my $phttpd = new VBTK::PHttpd(
    LocalPort    => '80',
    LocalAddr    => undef,
    DocRoot      => '/mydocroot'
  );

  $phttpd->run;

DESCRIPTION

VBTK::PHttpd is a very simple web server built on the HTTP::Daemon library. It can be setup to fork off a handler for each request, or can be run in a single-threaded mode. It's probably not a good choice for highly scalable applications, but it works great if you're just trying to add a simple web interface to a perl application. It supports various features such as redirection, special handling of files based on file type, user authentication, etc. It works especially well with the VBTK::PHtml library.

So why use this rather than just setup Apache and PHP? Well, I decided to do it this way, because I wanted to add a web interface into an existing perl program rather than convert it to run under Apache or PHP. I just think it's simpler this way and there's less to install.

METHODS

The following methods are supported

$httpd = new VBTK::PHttpd (<parm1> => <val1>, <parm2> => <val2>, ...)

The constructor passes many of it's parameters on in a call to HTTP::Daemon. All of these parms will default to a useable value if not specified, except for the 'DocRoot' parm which is required. This call initializes the daemon, but does not start it listening yet. The allowed parameters are:

DocRoot

The directory to be used as the docroot by the web server. (Required)

LocalPort

The TCP port number on which the daemon will start it's web server listening for requests. See HTTP::Daemon. (Defaults to 80)

LocalAddr

The IP address to which the daemon will bind itself. If none is supplied, the daemon will bind itself to '*'. (Default is none.)

ListenQueue

The size of the listener queue. See HTTP::Daemon for more details. (Defaults to 10)

IndexNames

A string containing a comma-separated list of file names to be treated as directory indexes when a requesting URL specifies a directory. (Defaults to 'index.html,index.htm,index.phtml' )

Handlers

A pointer to a hash containing pairs of filename patterns and pointers to subroutines. This is used to specify alternate sub-routines to handle specific file types. (Defaults to { '.phtml$' => \&defaultPHtmlHandler } ) The handler subroutine will be called whenever there is a match between the URL and the pattern. The handler will be passed the following:

  $_[0] - Connection object from HTTP::Daemon
  $_[1] - Request object from HTTP::Daemon
  $_[2] - Full path to file to be handled
  $_[3] - Docroot path for this server
  $_[4] - Pointer to a hash containing name/value pairs for all parameters
          passed in the request.

The handler should then make the appropriate calls to handle the request, form an HTTP::Response object, and transmit the response. An example handler, which simply serves up the file would be something like:

  sub myHandler 
  {
    my($conn,$req,$target,$docRoot,$parms) = @_;

    my $fh = new FileHandle "$target";

    # Check for errors
    unless($fh)
    {
        $conn->send_error(RC_NOT_FOUND);
        return;
    }

    # Slurp mode
    local $/:

    my $html = <$fh>;
    $fh->close;

    # Setup a response object    
    my $resp = new HTTP::Response;
    $response->content($html);

    # Return a response
    $conn->send_response($response);
  }

Redirects

A pointer to a hash containing pairs of URL patterns and URL's to redirect to. This is used when you want to redirect from an old location to a new one.

    Redirects => {
        'oldurl'  => 'newurl',
        'oldurl2' => 'newurl2' },

AuthList

A pointer to a hash containing pairs of filename patterns and pointers to authentication subroutines. This is used to restrict access to certain URL's in your docroot.

    AuthList => {
        'protectedURL1' => \&authSub1,
        'protectedURL2' => \&authSub2 },
        

When the protected URL is accessed, the user will be prompted to enter a username and password, which will then be passed as $_[0] and $_[1] respectively to the specified &authSub. The authSub should then return true if the user is allowed access, or false if not. Two pre-defined &authSub subroutines are provided, unixAuth and unixAuthWGroup. See their descriptions below for more details.

AuthRealm

A string containing a message which will be passed to the browser and displayed to the user when prompting them for their username and password. (Defaults to 'Perl PHttpd')

    AuthRealm => 'My Server',

DontForkList

A string containing a comma-separated list of URL patterns which, if they match the incoming HTTP request, will cause the server to not fork off a child process to handle the request. Instead, the process will be handled in-line. This is normally used when calling a '.phtml' URL which changes the value of something in memory, and so you don't want it to fork or the change won't happen in the right process. You can also set this to '.*' if you want to disable forking completely.

    DontForkList => 'setStatus.phtml,changeValue.phtml',

ReqTimeout

A number containing the maximum number of seconds to wait for the requestor to issue their request. The requestor could be a VBClient process reporting in or it might be a user's web browser. This prevents a single hung requestor from hanging up the entire server. (Defaults to 6 seconds).

    ReqTimeout => 6,

$httpd->run ( <return_after_sec> )

This call starts the daemon listening for and handling requests. If a 'return_after_sec' value is supplied, the daemon will return back after approximately 'return_after_sec' seconds. This enables the running of housekeeping tasks on a specified interval. So an example might be:

  while ( 1 )
  {
    $httpd->run(60);
    &runHousekeepingTasks;
  }

unixAuth (<username>,<password>)

This subroutine is provided for use in authenticating users. It requires the ability to lookup the user's encrypted unix password via the getpwnam system call. So it probably won't work unless you're running NIS. Returns true if the user was successfully authenticated, false otherwise.

unixAuthWGroup (<username>,<password>,<comma-separated-group-list>)

Same as 'unixAuth', but it also checks that the user is one of the groups in the specified 'comma-separated group list'.

SEE ALSO

HTTP::Daemon, VBTK::PHtml

AUTHOR

Brent Henry, vbtoolkit@yahoo.com

COPYRIGHT

Copyright (C) 1996-2002 Brent Henry

This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation available at: http://www.gnu.org/copyleft/gpl.html

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. See the GNU General Public License for more details.