view release on metacpan or  search on metacpan

lib/Poet/Manual/Intro.pod  view on Meta::CPAN

=item *

C<db> - database related files such as your schema

=item *

C<lib> - app-specific libraries and Poet subclasses

=item *

C<logs> - logs from web server and from explicit logging statements

=item *

C<static> - static web files - css, images, js

=item *

C<t> - unit tests

=back

=head2 Initializing Poet

Any web server or script must initialize Poet before it can use any of Poet's
features. This is accomplished by with C<Poet::Script>:

    #!/usr/local/bin/perl
    use Poet::Script qw($conf $poet);

You'll see this in C<bin/run.pl>, for example, the script you use to start your
webserver.  The C<use Poet::Script> line does several things:

=over

=item *

Searches upwards from the script for the environment root (as marked by the
C<.poet_root> file).

=item *

Reads and parses your configuration.

=item *

Unshifts onto @INC the lib/ subdirectory of your environment, so that you can
C<use> your application modules.

=item *

Imports the specified I<quick vars> - in this case C<$conf> and C<$poet> - as
well as some default utilities into the script namespace. More information
about these L<below|/QUICK VARS AND UTILITIES>.

=back

=head2 Relocatable environments

Ideally your environment will be I<relocatable> -- if you move your environment
to a different root, or checkout a second copy of it in a different root,
things should just work.

To achieve this you should never refer to exact environment directory paths in
your code; instead you'll call Poet methods that return them. e.g. instead of
this:

    system("/path/to/environment/bin/myscript.pl");

you'll do this:

    system($poet->bin_path("myscript.pl"));

(More information about this C<$poet> variable L<below|/QUICK VARS AND
UTILITIES>.)

=head2 App name

Your app name, e.g. C<MyApp>, is where you are expected to put app-specific
subclasses. For example if you have a L<DBIx::Class|DBIx::Class> schema, you'd
create it under C<MyApp::Schema> in the file C<lib/MyApp/Schema.pm>.

The app name is also where Poet will look for
L<subclasses|Poet::Manual::Subclassing> of its own classes.

=head1 CONFIGURATION AND LAYERS

Poet configuration files are kept in the C<conf> subdirectory. The files are in
L<YAML|http://www.yaml.org/> form and are merged in a particular order to
create a single configuration hash. (If you want to use something other than
YAML you can L<customize this|Poet::Manual::Subclassing>.)

Configuration files come in three varieties: C<global>, C<layer>, and C<local>,
in order from least to highest precedence.

=over

=item Global

I<Global> configuration applies to all instances of your environment, and is
typically checked into version control.

Your generated environment includes a C<conf/global.cfg>.  This is simplest to
start out with, but as a site scales in size and number of developers, you can
split out your global configuration into multiple files in
C<conf/global/*.cfg>.

=item Layer

I<Layers> allow you to have different configuration for different contexts.
With all but the simplest site you'll have at least two layers: I<development>
(the internal environment where you develop) and I<production> (the live site).
Later on, you might want a I<staging> environment (which looks like production
except for a different data source, etc.).

In general you can have as many layers as you like.  Each layer has a
corresponding configuration file in C<conf/layer/*.cfg>; only one layer file
will be loaded per environment. We recommend that these files all be checked
into version control as well, so that changes to each layer are tracked.