NAME

Maypole::Plugin::Config::Apache - read config settings from httpd.conf

SYNOPSIS

    use Maypole::Application qw( Config::Apache -Setup );
    
    
    # in httpd.conf
    
    # same as $config->application_name( "The Beer Database" )
    PerlSetVar MaypoleApplicationName "The Beer Database"
    
    PerlSetVar MaypoleDsn   dbi:mysql:BeerDB
    PerlSetVar MaypoleUser  username
    PerlSetVar MaypolePass  password
    
    # same as $config->display_tables( [ qw( beer brewery pub style ) ] )
    PerlAddVar MaypoleDisplayTables  beer 
    PerlAddVar MaypoleDisplayTables  brewery 
    PerlAddVar MaypoleDisplayTables  pub 
    PerlAddVar MaypoleDisplayTables  style
    
    # same as $config->masonx( { data_dir   => '/home/beerdb/www/beerdb/mdata', 
    #                            in_package => 'BeerDB::TestApp',
    #                            comp_root  => [ [ factory => '/usr/local/www/maypole/factory' ] ],
    #                            } )
    PerlAddVar MaypoleMasonx "data_dir   => '/home/beerdb/www/beerdb/mdata'"
    PerlAddVar MaypoleMasonx "in_package => 'BeerDB::TestApp'"
    PerlAddVar MaypoleMasonx "comp_root => [ [ factory => '/usr/local/www/maypole/factory' ] ]"
    
    # set something from arbitrary Perl code 
    PerlSetVar MaypoleEvalDisplayTables "[ qw( beer brewery pub style ) ]"
    
    # merging a hash of hashes - 
    #           $config->session( { args => { Directory     => '/tmp/sessions/beerdb',
    #                                         LockDirectory => '/tmp/sessionlocks/beerdb',
    #                                         }
    #                               } )
    PerlAddVar MaypoleSession "args => { Directory     => '/tmp/sessions/beerdb' }"
    PerlAddVar MaypoleSession "args => { LockDirectory => '/tmp/sessionlocks/beerdb' }"
    
    
    # merging a hash of arrayrefs involves a nasty hack...
    #           $config->masonx->{comp_root} = [ [ factory => '/usr/local/www/maypole/factory' ],
    #                                            [ library => '/usr/local/www/mason/lib' ],
    #                                            ];
    PerlAddVar MaypoleMasonx "comp_root => [ [ factory => '/usr/local/www/maypole/factory' ] ]"
    PerlAddVar MaypoleMasonx "comp_root =>   [ library => '/usr/local/www/mason/lib' ]"
    
    # ...more clearly shown here. To build up a hash of arrayrefs, the first value must 
    # be an array ref (to set up the value as an arrayref), while subsequent items are scalars
    # and are pushed onto the arrayref:
    #           $config->masonx->{plugins} = [ MasonX::Plugin::Foo->new,
    #                                          MasonX::Plugin::Bar->new,
    #                                          MasonX::Plugin::Baz->new,
    #                                          ];
    PerlAddVar MaypoleMasonx "plugins => [ MasonX::Plugin::Foo->new ]"
    PerlAddVar MaypoleMasonx "plugins =>   MasonX::Plugin::Bar->new"
    PerlAddVar MaypoleMasonx "plugins =>   MasonX::Plugin::Baz->new"
    
    

DESCRIPTION

Anything starting with Maypole or MaypoleEval is taken to be a config setting for Maypole. Everything after the Maypole or MaypoleEval is the variable name, in StudlyCaps form.

Values from MaypoleEval variables are run through an eval, allowing arbitrarily complex data structures to be set, including coderefs, if anything needed that.

Any value from a PerlAddVar that contains a => symbol is also run through an eval, so any valid perl expression for a hash value can be used.

An attempt is made to intelligently merge hash entries in multiple PerlAddVar statements. Multiple entries with the same key are merged into a single hashref or arrayref value.

Put Config::Apache at the front of the Maypole::Application call, so that later plugins have access to the configuration settings. If your httpd.conf contains all of your Maypole settings, you can add the -Setup flag, which calls __PACKAGE__->setup for you.

METHODS

setup

EXAMPLE

With all the config moved to httpd.conf, the actual driver is reduced to a few lines of code. Why not inline that in httpd.conf too?

    <VirtualHost xxx.xxx.xx.xx>
        
        ServerName beerdb.riverside-cms.co.uk
        ServerAdmin cpan@riverside-cms.co.uk
    
        DocumentRoot /home/beerdb/www/beerdb/htdocs
        
        #
        # Set up Maypole via Maypole::Plugin::Config::Apache
        #
        PerlSetVar MaypoleApplicationName "The Beer Database"
        PerlSetVar MaypoleUriBase         /beerdb
        PerlSetVar MaypoleTemplateRoot    /home/beerdb/www/beerdb/htdocs
        PerlSetVar MaypoleRowsPerPage     10
        
        PerlSetVar MaypoleDsn             "dbi:mysql:BeerDB"
        PerlSetVar MaypoleUser            username
        PerlSetVar MaypolePass            password
        
        PerlAddVar MaypoleDisplayTables  beer 
        PerlAddVar MaypoleDisplayTables  brewery 
        PerlAddVar MaypoleDisplayTables  pub 
        PerlAddVar MaypoleDisplayTables  style
        
        PerlAddVar MaypoleMasonx "comp_root  => [ [ factory => '/usr/local/www/maypole/factory' ] ]"
        PerlAddVar MaypoleMasonx "data_dir   => '/home/beerdb/www/beerdb/mdata'"
        PerlAddVar MaypoleMasonx "in_package => 'BeerDB::TestApp'"
        
        PerlAddVar MaypoleRelationships     "a brewery produces beers"
        PerlAddVar MaypoleRelationships     "a style defines beers"
        PerlAddVar MaypoleRelationships     "a pub has beers on handpumps"
        
        <Directory /home/beerdb/www/beerdb/htdocs/>
            Allow from all
            AllowOverride none
            Order allow,deny
    
            <Perl>
            {
                package BeerDB;
                use Maypole::Application qw( Config::Apache MasonX AutoUntaint Relationship -Setup -Debug2 );
                BeerDB->auto_untaint;
                BeerDB->init;
            }
            </Perl>
            
            SetHandler perl-script
            PerlHandler BeerDB
        </Directory>
        
        CustomLog /home/beerdb/www/beerdb/logs/access.log combined env=log
        ErrorLog  /home/beerdb/www/beerdb/logs/error.log    
        
    </VirtualHost>

Watch out for the chicken and the egg. The Perl section defining the BeerDB package must come after all the Maypole config settings (or else the settings won't yet exist when BeerDB tries to read them), but before the PerlHandler BeerDB directive (because the package needs to exist by then).

AUTHOR

David Baird, <cpan@riverside-cms.co.uk>

BUGS

Won't work for config variables with capital letters in them.

Strange things will happen to anything containing '=>' that should not be interpreted as a hash entry.

Please report any bugs or feature requests to bug-maypole-plugin-config-apache@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Maypole-Plugin-Config-Apache. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2005 David Baird, All Rights Reserved.

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