[Catalyst-commits] r9489 - in trunk/examples/CatalystAdvent/root:
2005 2006 2007
dandv at dev.catalyst.perl.org
dandv at dev.catalyst.perl.org
Wed Mar 11 08:18:38 GMT 2009
Author: dandv
Date: 2009-03-11 08:18:38 +0000 (Wed, 11 Mar 2009)
New Revision: 9489
Modified:
trunk/examples/CatalystAdvent/root/2005/10.pod
trunk/examples/CatalystAdvent/root/2005/11.pod
trunk/examples/CatalystAdvent/root/2005/12.pod
trunk/examples/CatalystAdvent/root/2005/13.pod
trunk/examples/CatalystAdvent/root/2005/17.pod
trunk/examples/CatalystAdvent/root/2005/6.pod
trunk/examples/CatalystAdvent/root/2005/7.pod
trunk/examples/CatalystAdvent/root/2005/8.pod
trunk/examples/CatalystAdvent/root/2005/9.pod
trunk/examples/CatalystAdvent/root/2006/6.pod
trunk/examples/CatalystAdvent/root/2007/14.pod
Log:
Updated various outdated entries with links to the Caatlyst wiki. CRLF-separated PODs were converted to LF-only.
Modified: trunk/examples/CatalystAdvent/root/2005/10.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/10.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/10.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,44 +1,47 @@
-=head1 Catalyst Advent - Day 10 - Catalyst on shared hosting
-
-So, you want to put your Catalyst app out there for the whole world to
-see, but you don't want to break the bank. There is an answer - if you can
-get shared hosting with FastCGI and a shell, you can install your Catalyst
-app. First, run
-
- perl -MCPAN -e shell
-
-and go through the standard CPAN configuration process. Then exit out
-without installing anything. Next, open your .bashrc and add
-
- export PATH=$HOME/local/bin:$HOME/local/script:$PATH
- perlversion=`perl -v | grep 'built for' | awk '{print $4}' | sed -e 's/v//;'`
- export PERL5LIB=$HOME/local/share/perl/$perlversion:$HOME/local/lib/perl/$perlversion:$HOME/local/lib:$PERL5LIB
-
-and log out, then back in again (or run ". .bashrc" if you prefer). Finally,
-edit .cpan/CPAN/MyConfig.pm and add
-
- 'make_install_arg' => qq[SITEPREFIX=$ENV{HOME}/local],
- 'makepl_arg' => qq[INSTALLDIRS=site install_base=$ENV{HOME}/local],
-
-Now you can install the modules you need with CPAN as normal, and perl will
-pick them up. Finally, change directory into the root of your virtual host
-and symlink your application's script directory in -
-
- cd path/to/mydomain.com
- ln -s ~/lib/MyApp/script script
-
-And add the following lines to your .htaccess file (assuming the server is
-setup to handle .pl as fcgi - you may need to rename the script to
-myapp_fastcgi.fcgi and/or use a SetHandler directive) -
-
- RewriteEngine On
- RewriteCond %{REQUEST_URI} !^/?script/myapp_fastcgi.pl
- RewriteRule ^(.*)$ script/myapp_fastcgi.pl/$1 [PT,L]
-
-http://mydomain.com/ should now Just Work. Congratulations, now you can
-tell your friends about your new website (or in our case, tell the client
-it's time to pay the invoice :)
-
- -- mst
-
-=cut
+=head1 Catalyst Advent - Day 10 - Catalyst on shared hosting
+
+B<NOTE>: This article was written in 2005. Make sure to check the
+Catalyst Wiki (L<http://dev.catalyst.perl.org/wiki>) for updated information.
+
+So, you want to put your Catalyst app out there for the whole world to
+see, but you don't want to break the bank. There is an answer - if you can
+get shared hosting with FastCGI and a shell, you can install your Catalyst
+app. First, run
+
+ perl -MCPAN -e shell
+
+and go through the standard CPAN configuration process. Then exit out
+without installing anything. Next, open your .bashrc and add
+
+ export PATH=$HOME/local/bin:$HOME/local/script:$PATH
+ perlversion=`perl -v | grep 'built for' | awk '{print $4}' | sed -e 's/v//;'`
+ export PERL5LIB=$HOME/local/share/perl/$perlversion:$HOME/local/lib/perl/$perlversion:$HOME/local/lib:$PERL5LIB
+
+and log out, then back in again (or run ". .bashrc" if you prefer). Finally,
+edit .cpan/CPAN/MyConfig.pm and add
+
+ 'make_install_arg' => qq[SITEPREFIX=$ENV{HOME}/local],
+ 'makepl_arg' => qq[INSTALLDIRS=site install_base=$ENV{HOME}/local],
+
+Now you can install the modules you need with CPAN as normal, and perl will
+pick them up. Finally, change directory into the root of your virtual host
+and symlink your application's script directory in -
+
+ cd path/to/mydomain.com
+ ln -s ~/lib/MyApp/script script
+
+And add the following lines to your .htaccess file (assuming the server is
+setup to handle .pl as fcgi - you may need to rename the script to
+myapp_fastcgi.fcgi and/or use a SetHandler directive) -
+
+ RewriteEngine On
+ RewriteCond %{REQUEST_URI} !^/?script/myapp_fastcgi.pl
+ RewriteRule ^(.*)$ script/myapp_fastcgi.pl/$1 [PT,L]
+
+http://mydomain.com/ should now Just Work. Congratulations, now you can
+tell your friends about your new website (or in our case, tell the client
+it's time to pay the invoice :)
+
+ -- mst
+
+=cut
Modified: trunk/examples/CatalystAdvent/root/2005/11.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/11.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/11.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,125 +1,128 @@
-=head1 Catalyst Advent - Day 11 - Caching
-
-Catalyst makes it easy to employ several different types of caching to speed
-up your applications.
-
-=head2 Cache Plugins
-
-There are three wrapper plugins around common CPAN cache modules:
-Cache::FastMmap, Cache::FileCache, and Cache::Memcached. These can be used
-to cache the result of slow operations.
-
-This very page you're viewing makes use of the FileCache plugin to cache the
-rendered XHTML version of the source POD document. This is an ideal
-application for a cache because the source document changes infrequently but
-may be viewed many times.
-
- use Catalyst qw/Cache::FileCache/;
-
- ...
-
- use File::stat;
- sub render_pod : Local {
- my ( self, $c ) = @_;
-
- # the cache is keyed on the filename and the modification time
- # to check for updates to the file.
- my $file = $c->path_to( 'root', '2005', '11.pod' );
- my $mtime = ( stat $file )->mtime;
-
- my $cached_pod = $c->cache->get("$file $mtime");
- if ( !$cached_pod ) {
- $cached_pod = do_slow_pod_rendering();
- # cache the result for 12 hours
- $c->cache->set( "$file $mtime", $cached_pod, '12h' );
- }
- $c->stash->{pod} = $cached_pod;
- }
-
-We could actually cache the result forever, but using a value such as 12 hours
-allows old entries to be automatically expired when they are no longer needed.
-
-=head2 Page Caching
-
-Another method of caching is to cache the entire HTML page. While this is
-traditionally handled by a front-end proxy server like Squid, the Catalyst
-PageCache plugin makes it trivial to cache the entire output from
-frequently-used or slow actions.
-
-Many sites have a busy content-filled front page that might look something
-like this. It probably takes a while to process, and will do the exact same
-thing for every single user who views the page.
-
- sub front_page : Path('/') {
- my ( $self, $c ) = @_;
-
- $c->forward( 'get_news_articles' );
- $c->forward( 'build_lots_of_boxes' );
- $c->forward( 'more_slow_stuff' );
-
- $c->stash->{template} = 'index.tt';
- }
-
-We can add the PageCache plugin to speed things up.
-
- use Catalyst qw/Cache::FileCache PageCache/;
-
- sub front_page : Path ('/') {
- my ( $self, $c ) = @_;
-
- $c->cache_page( 300 );
-
- # same processing as above
- }
-
-Now the entire output of the front page, from <html> to </html>, will be
-cached for 5 minutes. After 5 minutes, the next request will rebuild the
-page and it will be re-cached.
-
-Note that the page cache is keyed on the page URI plus all parameters, so
-requests for / and /?foo=bar will result in different cache items. Also,
-only GET requests will be cached by the plugin.
-
-You can even get that front-end Squid proxy to help out by enabling HTTP
-headers for the cached page.
-
- MyApp->config->{page_cache}->{set_http_headers} = 1;
-
-This would now set the following headers so proxies and browsers may cache
-the content themselves.
-
- Cache-Control: max-age=($expire_time - time)
- Expires: $expire_time
- Last-Modified: $cache_created_time
-
-=head2 Template Caching
-
-Template Toolkit provides support for caching compiled versions of your
-templates. To enable this in Catalyst, use the following configuration.
-TT will cache compiled templates keyed on the file mtime, so changes will
-still be automatically detected.
-
- package MyApp::View::TT;
-
- use strict;
- use warnings;
- use base 'Catalyst::View::TT';
-
- __PACKAGE__->config(
- COMPILE_DIR => '/tmp/template_cache',
- );
-
- 1;
-
-=head2 More Info
-
-See the documentation for each cache plugin for more details and other
-available configuration options.
-
-L<http://search.cpan.org/dist/Catalyst-Plugin-Cache-FastMmap/lib/Catalyst/Plugin/Cache/FastMmap.pm>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Cache-FileCache/lib/Catalyst/Plugin/Cache/FileCache.pm>
-L<http://search.cpan.org/dist/Catalyst-Plugin-Cache-Memcached/lib/Catalyst/Plugin/Cache/Memcached.pm>
-L<http://search.cpan.org/dist/Catalyst-Plugin-PageCache/lib/Catalyst/Plugin/PageCache.pm>
-L<http://search.cpan.org/dist/Template-Toolkit/lib/Template/Manual/Config.pod#Caching_and_Compiling_Options>
-
--- Andy Grundman
+=head1 Catalyst Advent - Day 11 - Caching
+
+B<NOTE>: This article was written in 2005. Make sure to check the
+Catalyst Wiki (L<http://dev.catalyst.perl.org/wiki>) for updated information.
+
+Catalyst makes it easy to employ several different types of caching to speed
+up your applications.
+
+=head2 Cache Plugins
+
+There are three wrapper plugins around common CPAN cache modules:
+Cache::FastMmap, Cache::FileCache, and Cache::Memcached. These can be used
+to cache the result of slow operations.
+
+This very page you're viewing makes use of the FileCache plugin to cache the
+rendered XHTML version of the source POD document. This is an ideal
+application for a cache because the source document changes infrequently but
+may be viewed many times.
+
+ use Catalyst qw/Cache::FileCache/;
+
+ ...
+
+ use File::stat;
+ sub render_pod : Local {
+ my ( self, $c ) = @_;
+
+ # the cache is keyed on the filename and the modification time
+ # to check for updates to the file.
+ my $file = $c->path_to( 'root', '2005', '11.pod' );
+ my $mtime = ( stat $file )->mtime;
+
+ my $cached_pod = $c->cache->get("$file $mtime");
+ if ( !$cached_pod ) {
+ $cached_pod = do_slow_pod_rendering();
+ # cache the result for 12 hours
+ $c->cache->set( "$file $mtime", $cached_pod, '12h' );
+ }
+ $c->stash->{pod} = $cached_pod;
+ }
+
+We could actually cache the result forever, but using a value such as 12 hours
+allows old entries to be automatically expired when they are no longer needed.
+
+=head2 Page Caching
+
+Another method of caching is to cache the entire HTML page. While this is
+traditionally handled by a front-end proxy server like Squid, the Catalyst
+PageCache plugin makes it trivial to cache the entire output from
+frequently-used or slow actions.
+
+Many sites have a busy content-filled front page that might look something
+like this. It probably takes a while to process, and will do the exact same
+thing for every single user who views the page.
+
+ sub front_page : Path('/') {
+ my ( $self, $c ) = @_;
+
+ $c->forward( 'get_news_articles' );
+ $c->forward( 'build_lots_of_boxes' );
+ $c->forward( 'more_slow_stuff' );
+
+ $c->stash->{template} = 'index.tt';
+ }
+
+We can add the PageCache plugin to speed things up.
+
+ use Catalyst qw/Cache::FileCache PageCache/;
+
+ sub front_page : Path ('/') {
+ my ( $self, $c ) = @_;
+
+ $c->cache_page( 300 );
+
+ # same processing as above
+ }
+
+Now the entire output of the front page, from <html> to </html>, will be
+cached for 5 minutes. After 5 minutes, the next request will rebuild the
+page and it will be re-cached.
+
+Note that the page cache is keyed on the page URI plus all parameters, so
+requests for / and /?foo=bar will result in different cache items. Also,
+only GET requests will be cached by the plugin.
+
+You can even get that front-end Squid proxy to help out by enabling HTTP
+headers for the cached page.
+
+ MyApp->config->{page_cache}->{set_http_headers} = 1;
+
+This would now set the following headers so proxies and browsers may cache
+the content themselves.
+
+ Cache-Control: max-age=($expire_time - time)
+ Expires: $expire_time
+ Last-Modified: $cache_created_time
+
+=head2 Template Caching
+
+Template Toolkit provides support for caching compiled versions of your
+templates. To enable this in Catalyst, use the following configuration.
+TT will cache compiled templates keyed on the file mtime, so changes will
+still be automatically detected.
+
+ package MyApp::View::TT;
+
+ use strict;
+ use warnings;
+ use base 'Catalyst::View::TT';
+
+ __PACKAGE__->config(
+ COMPILE_DIR => '/tmp/template_cache',
+ );
+
+ 1;
+
+=head2 More Info
+
+See the documentation for each cache plugin for more details and other
+available configuration options.
+
+L<http://search.cpan.org/dist/Catalyst-Plugin-Cache-FastMmap/lib/Catalyst/Plugin/Cache/FastMmap.pm>
+L<http://search.cpan.org/dist/Catalyst-Plugin-Cache-FileCache/lib/Catalyst/Plugin/Cache/FileCache.pm>
+L<http://search.cpan.org/dist/Catalyst-Plugin-Cache-Memcached/lib/Catalyst/Plugin/Cache/Memcached.pm>
+L<http://search.cpan.org/dist/Catalyst-Plugin-PageCache/lib/Catalyst/Plugin/PageCache.pm>
+L<http://search.cpan.org/dist/Template-Toolkit/lib/Template/Manual/Config.pod#Caching_and_Compiling_Options>
+
+-- Andy Grundman
Modified: trunk/examples/CatalystAdvent/root/2005/12.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/12.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/12.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,35 +1,38 @@
-=head1 Catalyst Advent - Day 12 - L<Catalyst::Plugin::Subrequest>
-
-=head2 Component based sub-requests.
-
-This is actually one of the features we brought over from L<Maypole>. There it
-was called L<Maypole::Plugin::Component>. Basically, the idea is to set up
-new request/response objects, and do an internal request, then return the
-output. It's quite handy for various situations, Simon's example was a
-shopping portal. I'm frequently using it to render parts of my site that I'm
-also rendering with ajax, to avoid duplication of code.
-
-It's quite simple in use. You just call $c->subreq('</public/url>'); (or
-with TT, [% c.subreq('/public/url') %] .) This will localize enough
-of your request/response object so that it shouldn't affect your current
-request, set up a new path/uri, and call the Dispatcher to force a full
-request chain, including begin/end/auto/default and whatever else applies.
-if you don't like 'subreq', theres an alias as well: 'sub_request'.
-
-You can also set up the stash before the request, as well as pass parameters
-to the request like a normal form POST by passing optional hashrefs to the
-subreq method. for example:
-
- my $text=$c->subreq('/foo',{ bar=>$c->stash->{bar} }, {id=>23});
-
-This will dispatch to whatever handles '/foo', with bar in the stash, and
-$c->req->param('id') returning 23. After the request, $text will contain
-whatever's in $c->res->output.
-
-Note, by the way, that the uri path is relative to the application root,
-and not necessesarily the webserver root.
-
-
--- Marcus Ramberg
-
-=cut
+=head1 Catalyst Advent - Day 12 - L<Catalyst::Plugin::Subrequest>
+
+B<NOTE>: This article was written in 2005. Make sure to check the
+Catalyst Wiki (L<http://dev.catalyst.perl.org/wiki>) for updated information.
+
+=head2 Component based sub-requests.
+
+This is actually one of the features we brought over from L<Maypole>. There it
+was called L<Maypole::Plugin::Component>. Basically, the idea is to set up
+new request/response objects, and do an internal request, then return the
+output. It's quite handy for various situations, Simon's example was a
+shopping portal. I'm frequently using it to render parts of my site that I'm
+also rendering with ajax, to avoid duplication of code.
+
+It's quite simple in use. You just call $c->subreq('</public/url>'); (or
+with TT, [% c.subreq('/public/url') %] .) This will localize enough
+of your request/response object so that it shouldn't affect your current
+request, set up a new path/uri, and call the Dispatcher to force a full
+request chain, including begin/end/auto/default and whatever else applies.
+if you don't like 'subreq', theres an alias as well: 'sub_request'.
+
+You can also set up the stash before the request, as well as pass parameters
+to the request like a normal form POST by passing optional hashrefs to the
+subreq method. for example:
+
+ my $text=$c->subreq('/foo',{ bar=>$c->stash->{bar} }, {id=>23});
+
+This will dispatch to whatever handles '/foo', with bar in the stash, and
+$c->req->param('id') returning 23. After the request, $text will contain
+whatever's in $c->res->output.
+
+Note, by the way, that the uri path is relative to the application root,
+and not necessesarily the webserver root.
+
+
+-- Marcus Ramberg
+
+=cut
Modified: trunk/examples/CatalystAdvent/root/2005/13.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/13.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/13.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,5 +1,8 @@
=head1 Catalyst Advent - Day 13 - DBIx::Class as Catalyst Model
+B<NOTE>: This article was written in 2005. Make sure to check the
+Catalyst Wiki (L<http://dev.catalyst.perl.org/wiki>) for updated information.
+
=head2 Our Database
This text will show you how to start using DBIx::Class as your model within
Modified: trunk/examples/CatalystAdvent/root/2005/17.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/17.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/17.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,106 +1,109 @@
-=head1 Catalyst Advent - Day 17 - FastCGI Deployment
-
-As a companion to Day 7's mod_perl article, today's article is about
-production FastCGI deployment.
-
-=head2 Pros
-
-=head3 Speed
-
-FastCGI performs equally as well as mod_perl. Don't let the 'CGI' fool you;
-your app runs as multiple persistent processes ready to receive connections
-from the web server.
-
-=head3 App Server
-
-When using external FastCGI servers, your application runs as a standalone
-application server. It may be restarted independently from the web server.
-This allows for a more robust environment and faster reload times when
-pushing new app changes. The frontend server can even be configured to
-display a friendly "down for maintenance" page while the application is
-restarting.
-
-=head3 Load-balancing
-
-You can launch your application on multiple backend servers and allow the
-frontend web server to load-balance between all of them. And of course, if
-one goes down, your app continues to run fine.
-
-=head3 Multiple versions of the same app
-
-Each FastCGI application is a separate process, so you can run different
-versions of the same app on a single server.
-
-=head3 Can run with threaded Apache
-
-Since your app is not running inside of Apache, the faster mpm_worker module
-can be used without worrying about the thread safety of your application.
-
-=head2 Cons
-
-=head3 More complex environment
-
-With FastCGI, there are more things to monitor and more processes running
-than when using mod_perl.
-
-=head2 Setup
-
-=head3 1. Install Apache with mod_fastcgi
-
-mod_fastcgi for Apache is a third party module, and can be found at
-L<http://www.fastcgi.com/>. It is also packaged in many distributions, for
-example, libapache2-mod-fastcgi in Debian.
-
-=head3 2. Configure your application
-
- # Serve static content directly
- DocumentRoot /var/www/MyApp/root
- Alias /static /var/www/MyApp/root/static
-
- FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -processes 3
- Alias /myapp/ /var/www/MyApp/script/myapp_fastcgi.pl/
-
- # Or, run at the root
- Alias / /var/www/MyApp/script/myapp_fastcgi.pl/
-
-The above commands will launch 3 app processes and make the app available at
-/myapp/
-
-=head2 Standalone server mode
-
-While not as easy as the previous method, running your app as an external
-server gives you much more flexibility.
-
-First, launch your app as a standalone server listening on a socket.
-
- script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 -p /tmp/myapp.pid -d
-
-You can also listen on a TCP port if your web server is not on the same
-machine.
-
- script/myapp_fastcgi.pl -l :8080 -n 5 -p /tmp/myapp.pid -d
-
-You will probably want to write an init script to handle starting/stopping
-of the app using the pid file.
-
-Now, we simply configure Apache to connect to the running server.
-
- # 502 is a Bad Gateway error, and will occur if the backend server is down
- # This allows us to display a friendly static page that says "down for
- # maintenance"
- Alias /_errors /var/www/MyApp/root/error-pages
- ErrorDocument 502 /_errors/502.html
-
- FastCgiExternalServer /tmp/myapp -socket /tmp/myapp.socket
- Alias /myapp/ /tmp/myapp/
-
- # Or, run at the root
- Alias / /tmp/myapp/
-
-=head2 More Info
-
-Lots more information is available in the new and expanded FastCGI docs that
-will be part of Catalyst 5.62. For now you may read them here:
-L<http://dev.catalyst.perl.org/file/trunk/Catalyst/lib/Catalyst/Engine/FastCGI.pm>
-
---Andy Grundman
+=head1 Catalyst Advent - Day 17 - FastCGI Deployment
+
+B<NOTE>: This article was written in 2005. For more up-to-date information
+on deplyoment, please see L<http://dev.catalyst.perl.org/wiki/deployment>
+
+As a companion to Day 7's mod_perl article, today's article is about
+production FastCGI deployment.
+
+=head2 Pros
+
+=head3 Speed
+
+FastCGI performs equally as well as mod_perl. Don't let the 'CGI' fool you;
+your app runs as multiple persistent processes ready to receive connections
+from the web server.
+
+=head3 App Server
+
+When using external FastCGI servers, your application runs as a standalone
+application server. It may be restarted independently from the web server.
+This allows for a more robust environment and faster reload times when
+pushing new app changes. The frontend server can even be configured to
+display a friendly "down for maintenance" page while the application is
+restarting.
+
+=head3 Load-balancing
+
+You can launch your application on multiple backend servers and allow the
+frontend web server to load-balance between all of them. And of course, if
+one goes down, your app continues to run fine.
+
+=head3 Multiple versions of the same app
+
+Each FastCGI application is a separate process, so you can run different
+versions of the same app on a single server.
+
+=head3 Can run with threaded Apache
+
+Since your app is not running inside of Apache, the faster mpm_worker module
+can be used without worrying about the thread safety of your application.
+
+=head2 Cons
+
+=head3 More complex environment
+
+With FastCGI, there are more things to monitor and more processes running
+than when using mod_perl.
+
+=head2 Setup
+
+=head3 1. Install Apache with mod_fastcgi
+
+mod_fastcgi for Apache is a third party module, and can be found at
+L<http://www.fastcgi.com/>. It is also packaged in many distributions, for
+example, libapache2-mod-fastcgi in Debian.
+
+=head3 2. Configure your application
+
+ # Serve static content directly
+ DocumentRoot /var/www/MyApp/root
+ Alias /static /var/www/MyApp/root/static
+
+ FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -processes 3
+ Alias /myapp/ /var/www/MyApp/script/myapp_fastcgi.pl/
+
+ # Or, run at the root
+ Alias / /var/www/MyApp/script/myapp_fastcgi.pl/
+
+The above commands will launch 3 app processes and make the app available at
+/myapp/
+
+=head2 Standalone server mode
+
+While not as easy as the previous method, running your app as an external
+server gives you much more flexibility.
+
+First, launch your app as a standalone server listening on a socket.
+
+ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 -p /tmp/myapp.pid -d
+
+You can also listen on a TCP port if your web server is not on the same
+machine.
+
+ script/myapp_fastcgi.pl -l :8080 -n 5 -p /tmp/myapp.pid -d
+
+You will probably want to write an init script to handle starting/stopping
+of the app using the pid file.
+
+Now, we simply configure Apache to connect to the running server.
+
+ # 502 is a Bad Gateway error, and will occur if the backend server is down
+ # This allows us to display a friendly static page that says "down for
+ # maintenance"
+ Alias /_errors /var/www/MyApp/root/error-pages
+ ErrorDocument 502 /_errors/502.html
+
+ FastCgiExternalServer /tmp/myapp -socket /tmp/myapp.socket
+ Alias /myapp/ /tmp/myapp/
+
+ # Or, run at the root
+ Alias / /tmp/myapp/
+
+=head2 More Info
+
+Lots more information is available in the new and expanded FastCGI docs that
+will be part of Catalyst 5.62. For now you may read them here:
+L<http://dev.catalyst.perl.org/file/trunk/Catalyst/lib/Catalyst/Engine/FastCGI.pm>
+
+--Andy Grundman
Modified: trunk/examples/CatalystAdvent/root/2005/6.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/6.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/6.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,89 +1,92 @@
-=head1 Catalyst Advent - Day 6 - Building PAR Packages
-
-You know the problem, you got a application perfectly running on your
-development box, but then *shudder* you have to quickly move it to
-another one for demonstration/deployment/testing...
-
-PAR packages can save you from a lot of trouble here.
-They are usual Zip files that contain a blib tree, you can even
-include all prereqs and a perl interpreter by setting a few flags!
-
-=head2 Follow these few points to try it out!
-
-1. Install Catalyst 5.61 (or later) and PAR 0.89
-
- % perl -MCPAN -e 'install Catalyst'
- ...
- % perl -MCPAN -e 'install PAR'
- ...
-
-2. Create a application
-
- % catalyst.pl MyApp
- ...
- % cd MyApp
-
-3. Add these lines to Makefile.PL (below "catalyst_files();")
-
- catalyst_par_core(); # Include modules that are also included
- # in the standard Perl distribution,
- # this is optional but highly suggested
-
- catalyst_par(); # Generate a PAR as soon as the blib
- # directory is ready
-
-4. Prepare the Makefile, test your app, create a PAR (the two Makefile.PL calls are no typo)
-
- % perl Makefile.PL
- ...
- % make test
- ...
- % perl Makefile.PL
- ...
-
-Future versions of Catalyst (5.62 and newer) will use a similar but more elegant calling convention.
-
- % perl Makefile.PL
- ...
- % make catalyst_par
- ...
-
-Congratulations! Your package "myapp.par" is ready, the following
-steps are just optional.
-
-5. Test your PAR package with "parl" (no typo) :)
-
- % parl myapp.par
- Usage:
- [parl] myapp[.par] [script] [arguments]
-
- Examples:
- parl myapp.par myapp_server.pl -r
- myapp myapp_cgi.pl
-
- Available scripts:
- myapp_cgi.pl
- myapp_create.pl
- myapp_fastcgi.pl
- myapp_server.pl
- myapp_test.pl
-
- % parl myapp.par myapp_server.pl
- You can connect to your server at http://localhost:3000
-
-Yes, this nifty little starter application gets automatically included.
-You can also use "catalyst_par_script('myapp_server.pl')" to set a
-default script to execute.
-
-6. Want to create a binary that includes the Perl interpreter? No
-problem!
-
- % pp -o myapp myapp.par
- % ./myapp myapp_server.pl
- You can connect to your server at http://localhost:3000
-
-Have fun!
-
--- sri
-
-=cut
+=head1 Catalyst Advent - Day 6 - Building PAR Packages
+
+B<NOTE>: This article was written in 2005. For more up-to-date information
+on deplyoment, please see L<http://dev.catalyst.perl.org/wiki/deployment>
+
+You know the problem, you got a application perfectly running on your
+development box, but then *shudder* you have to quickly move it to
+another one for demonstration/deployment/testing...
+
+PAR packages can save you from a lot of trouble here.
+They are usual Zip files that contain a blib tree, you can even
+include all prereqs and a perl interpreter by setting a few flags!
+
+=head2 Follow these few points to try it out!
+
+1. Install Catalyst 5.61 (or later) and PAR 0.89
+
+ % perl -MCPAN -e 'install Catalyst'
+ ...
+ % perl -MCPAN -e 'install PAR'
+ ...
+
+2. Create a application
+
+ % catalyst.pl MyApp
+ ...
+ % cd MyApp
+
+3. Add these lines to Makefile.PL (below "catalyst_files();")
+
+ catalyst_par_core(); # Include modules that are also included
+ # in the standard Perl distribution,
+ # this is optional but highly suggested
+
+ catalyst_par(); # Generate a PAR as soon as the blib
+ # directory is ready
+
+4. Prepare the Makefile, test your app, create a PAR (the two Makefile.PL calls are no typo)
+
+ % perl Makefile.PL
+ ...
+ % make test
+ ...
+ % perl Makefile.PL
+ ...
+
+Future versions of Catalyst (5.62 and newer) will use a similar but more elegant calling convention.
+
+ % perl Makefile.PL
+ ...
+ % make catalyst_par
+ ...
+
+Congratulations! Your package "myapp.par" is ready, the following
+steps are just optional.
+
+5. Test your PAR package with "parl" (no typo) :)
+
+ % parl myapp.par
+ Usage:
+ [parl] myapp[.par] [script] [arguments]
+
+ Examples:
+ parl myapp.par myapp_server.pl -r
+ myapp myapp_cgi.pl
+
+ Available scripts:
+ myapp_cgi.pl
+ myapp_create.pl
+ myapp_fastcgi.pl
+ myapp_server.pl
+ myapp_test.pl
+
+ % parl myapp.par myapp_server.pl
+ You can connect to your server at http://localhost:3000
+
+Yes, this nifty little starter application gets automatically included.
+You can also use "catalyst_par_script('myapp_server.pl')" to set a
+default script to execute.
+
+6. Want to create a binary that includes the Perl interpreter? No
+problem!
+
+ % pp -o myapp myapp.par
+ % ./myapp myapp_server.pl
+ You can connect to your server at http://localhost:3000
+
+Have fun!
+
+-- sri
+
+=cut
Modified: trunk/examples/CatalystAdvent/root/2005/7.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/7.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/7.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,134 +1,137 @@
-=head1 Catalyst Advent - Day 7 - mod_perl Deployment
-
-In today's entry, I'll be talking about deploying an application in
-production using Apache and mod_perl.
-
-=head2 Pros & Cons
-
-mod_perl is the best solution for many applications, but I'll list some pros
-and cons so you can decide for yourself. The other production deployment
-option is FastCGI, which I'll talk about in a future calendar article.
-
-=head3 Pros
-
-=head4 Speed
-
-mod_perl is very fast and your app will benefit from being loaded in memory
-within each Apache process.
-
-=head4 Shared memory for multiple apps
-
-If you need to run several Catalyst apps on the same server, mod_perl will
-share the memory for common modules.
-
-=head3 Cons
-
-=head4 Memory usage
-
-Since your application is fully loaded in memory, every Apache process will
-be rather large. This means a large Apache process will be tied up while
-serving static files, large files, or dealing with slow clients. For this
-reason, it is best to run a two-tiered web architecture with a lightweight
-frontend server passing dynamic requests to a large backend mod_perl
-server.
-
-=head4 Reloading
-
-Any changes made to the core code of your app require a full Apache restart.
-Catalyst does not support Apache::Reload or StatINC. This is another good
-reason to run a frontend web server where you can set up an
-C<ErrorDocument 502> page to report that your app is down for maintenance.
-
-=head4 Cannot run multiple versions of the same app
-
-It is not possible to run two different versions of the same application in
-the same Apache instance because the namespaces will collide.
-
-=head2 Setup
-
-Now that we have that out of the way, let's talk about setting up mod_perl
-to run a Catalyst app.
-
-=head3 1. Install Catalyst::Engine::Apache
-
-You should install the latest versions of both Catalyst and
-Catalyst::Engine::Apache. The Apache engines were separated from the
-Catalyst core in version 5.50 to allow for updates to the engine without
-requiring a new Catalyst release.
-
-=head3 2. Install Apache with mod_perl
-
-Both Apache 1.3 and Apache 2 are supported, although Apache 2 is highly
-recommended. With Apache 2, make sure you are using the prefork MPM and not
-the worker MPM. The reason for this is that many Perl modules are not
-thread-safe and may have problems running within the threaded worker
-environment. Catalyst is thread-safe however, so if you know what you're
-doing, you may be able to run using worker.
-
-In Debian, the following commands should get you going.
-
- apt-get install apache2-mpm-prefork
- apt-get install libapache2-mod-perl2
-
-=head3 3. Configure your application
-
-Every Catalyst application will automagically become a mod_perl handler
-when run within mod_perl. This makes the configuration extremely easy.
-Here is a basic Apache 2 configuration.
-
- PerlSwitches -I/var/www/MyApp/lib
- PerlModule MyApp
-
- <Location />
- SetHandler modperl
- PerlResponseHandler MyApp
- </Location>
-
-The most important line here is C<PerlModule MyApp>. This causes mod_perl
-to preload your entire application into shared memory, including all of your
-controller, model, and view classes and configuration. If you have -Debug
-mode enabled, you will see the startup output scroll by when you first
-start Apache.
-
-For an example Apache 1.3 configuration, please see the documentation for
-Catalyst::Engine::Apache::MP13 L</[1]>.
-
-=head2 Test It
-
-That's it, your app is now a full-fledged mod_perl application! Try it out
-by going to http://your.server.com/.
-
-=head2 Other Options
-
-=head3 Non-root location
-
-You may not always want to run your app at the root of your server or virtual
-host. In this case, it's a simple change to run at any non-root location
-of your choice.
-
- <Location /myapp>
- SetHandler modperl
- PerlResponseHandler MyApp
- </Location>
-
-When running this way, it is best to make use of the C<uri_for> method in
-Catalyst for constructing correct links.
-
-=head3 Static file handling
-
-Static files can be served directly by Apache for a performance boost.
-
- DocumentRoot /var/www/MyApp/root
- <Location /static>
- SetHandler default-handler
- </Location>
-
-This will let all files within root/static be handled directly by Apache. In
-a two-tiered setup, the frontend server should handle static files.
-The configuration to do this on the frontend will vary.
-
---Andy Grundman
-
-=head4 [1]
-
-L<http://search.cpan.org/dist/Catalyst-Engine-Apache/lib/Catalyst/Engine/Apache/MP13.pm>
+=head1 Catalyst Advent - Day 7 - mod_perl Deployment
+
+B<NOTE>: This article was written in 2005. For more up-to-date information
+on deplyoment, please see L<http://dev.catalyst.perl.org/wiki/deployment>
+
+In today's entry, I'll be talking about deploying an application in
+production using Apache and mod_perl.
+
+=head2 Pros & Cons
+
+mod_perl is the best solution for many applications, but I'll list some pros
+and cons so you can decide for yourself. The other production deployment
+option is FastCGI, which I'll talk about in a future calendar article.
+
+=head3 Pros
+
+=head4 Speed
+
+mod_perl is very fast and your app will benefit from being loaded in memory
+within each Apache process.
+
+=head4 Shared memory for multiple apps
+
+If you need to run several Catalyst apps on the same server, mod_perl will
+share the memory for common modules.
+
+=head3 Cons
+
+=head4 Memory usage
+
+Since your application is fully loaded in memory, every Apache process will
+be rather large. This means a large Apache process will be tied up while
+serving static files, large files, or dealing with slow clients. For this
+reason, it is best to run a two-tiered web architecture with a lightweight
+frontend server passing dynamic requests to a large backend mod_perl
+server.
+
+=head4 Reloading
+
+Any changes made to the core code of your app require a full Apache restart.
+Catalyst does not support Apache::Reload or StatINC. This is another good
+reason to run a frontend web server where you can set up an
+C<ErrorDocument 502> page to report that your app is down for maintenance.
+
+=head4 Cannot run multiple versions of the same app
+
+It is not possible to run two different versions of the same application in
+the same Apache instance because the namespaces will collide.
+
+=head2 Setup
+
+Now that we have that out of the way, let's talk about setting up mod_perl
+to run a Catalyst app.
+
+=head3 1. Install Catalyst::Engine::Apache
+
+You should install the latest versions of both Catalyst and
+Catalyst::Engine::Apache. The Apache engines were separated from the
+Catalyst core in version 5.50 to allow for updates to the engine without
+requiring a new Catalyst release.
+
+=head3 2. Install Apache with mod_perl
+
+Both Apache 1.3 and Apache 2 are supported, although Apache 2 is highly
+recommended. With Apache 2, make sure you are using the prefork MPM and not
+the worker MPM. The reason for this is that many Perl modules are not
+thread-safe and may have problems running within the threaded worker
+environment. Catalyst is thread-safe however, so if you know what you're
+doing, you may be able to run using worker.
+
+In Debian, the following commands should get you going.
+
+ apt-get install apache2-mpm-prefork
+ apt-get install libapache2-mod-perl2
+
+=head3 3. Configure your application
+
+Every Catalyst application will automagically become a mod_perl handler
+when run within mod_perl. This makes the configuration extremely easy.
+Here is a basic Apache 2 configuration.
+
+ PerlSwitches -I/var/www/MyApp/lib
+ PerlModule MyApp
+
+ <Location />
+ SetHandler modperl
+ PerlResponseHandler MyApp
+ </Location>
+
+The most important line here is C<PerlModule MyApp>. This causes mod_perl
+to preload your entire application into shared memory, including all of your
+controller, model, and view classes and configuration. If you have -Debug
+mode enabled, you will see the startup output scroll by when you first
+start Apache.
+
+For an example Apache 1.3 configuration, please see the documentation for
+Catalyst::Engine::Apache::MP13 L</[1]>.
+
+=head2 Test It
+
+That's it, your app is now a full-fledged mod_perl application! Try it out
+by going to http://your.server.com/.
+
+=head2 Other Options
+
+=head3 Non-root location
+
+You may not always want to run your app at the root of your server or virtual
+host. In this case, it's a simple change to run at any non-root location
+of your choice.
+
+ <Location /myapp>
+ SetHandler modperl
+ PerlResponseHandler MyApp
+ </Location>
+
+When running this way, it is best to make use of the C<uri_for> method in
+Catalyst for constructing correct links.
+
+=head3 Static file handling
+
+Static files can be served directly by Apache for a performance boost.
+
+ DocumentRoot /var/www/MyApp/root
+ <Location /static>
+ SetHandler default-handler
+ </Location>
+
+This will let all files within root/static be handled directly by Apache. In
+a two-tiered setup, the frontend server should handle static files.
+The configuration to do this on the frontend will vary.
+
+--Andy Grundman
+
+=head4 [1]
+
+L<http://search.cpan.org/dist/Catalyst-Engine-Apache/lib/Catalyst/Engine/Apache/MP13.pm>
Modified: trunk/examples/CatalystAdvent/root/2005/8.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/8.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/8.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,56 +1,56 @@
-=head1 Catalyst Advent - Day 8 - Don't Repeat Yourself
-
-DRY is a central principle in Catalyst, yet there is one piece of code
-that is identical in 90% of all Catalyst applications.
-
- sub end : Private {
- my ($self,$c) = @_;
- return 1 if $c->res->body;
- return 1 if $c->response->status =~ /^3\d\d$/;
- $c->forward( 'MyApp::View::TT' );
- }
-
-Basically, we want to render a template unless we already have a response,
-or are redirecting.
-
-=head2 Catalyst::Plugin::DefaultEnd to the rescue!
-
-So, rather than doing this again and again, I've made a plugin for you to use.
-sure, it's not much code, but at least it's one function less to worry about.
-
-Here's how to use it:
-
-1. Open up MyApp.pm.
-
-2. Add the DefaultEnd plugin like this:
-
- use Catalyst qw/-Debug DefaultEnd Static::Simple/;
-
-3. There is no step 3 :)
-
-As an added bonus, you can now set dump_info=1 as a url parameter to force
-the end action to die, and display the debug info. Note that this is only
-provided in Debug mode.
-
-By default, DefaultEnd will forward to the first view it can find. If you have
-more than one view, you might want to specifiy the active one, by setting
-$c->config->{view}.
-
-If you need to add more things to your end action, you can extend it like this.
-
- sub end : Private {
- my ( $self, $c ) = @_;
-
- ... #code before view
-
- $c->NEXT::end( $c );
-
- ... #code after view
- }
-
-
-Have fun!
-
--- marcus
-
-=cut
+=head1 Catalyst Advent - Day 8 - Don't Repeat Yourself
+
+DRY is a central principle in Catalyst, yet there is one piece of code
+that is identical in 90% of all Catalyst applications.
+
+ sub end : Private {
+ my ($self,$c) = @_;
+ return 1 if $c->res->body;
+ return 1 if $c->response->status =~ /^3\d\d$/;
+ $c->forward( 'MyApp::View::TT' );
+ }
+
+Basically, we want to render a template unless we already have a response,
+or are redirecting.
+
+=head2 Catalyst::Plugin::DefaultEnd to the rescue!
+
+So, rather than doing this again and again, I've made a plugin for you to use.
+sure, it's not much code, but at least it's one function less to worry about.
+
+Here's how to use it:
+
+1. Open up MyApp.pm.
+
+2. Add the DefaultEnd plugin like this:
+
+ use Catalyst qw/-Debug DefaultEnd Static::Simple/;
+
+3. There is no step 3 :)
+
+As an added bonus, you can now set dump_info=1 as a url parameter to force
+the end action to die, and display the debug info. Note that this is only
+provided in Debug mode.
+
+By default, DefaultEnd will forward to the first view it can find. If you have
+more than one view, you might want to specifiy the active one, by setting
+$c->config->{view}.
+
+If you need to add more things to your end action, you can extend it like this.
+
+ sub end : Private {
+ my ( $self, $c ) = @_;
+
+ ... #code before view
+
+ $c->NEXT::end( $c );
+
+ ... #code after view
+ }
+
+
+Have fun!
+
+-- marcus
+
+=cut
Modified: trunk/examples/CatalystAdvent/root/2005/9.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2005/9.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2005/9.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,58 +1,63 @@
-=head1 Catalyst Advent - Day 9 - YAML, YAML, YAML!
-
-When you start a new Catalyst app you configure it directly
-with __PACKAGE__->config, thats ok for development but admins
-will hate you when they have to deploy this.
-
- __PACKAGE__->config( name => 'MyApp', 'View::TT' => { EVAL_PERL => 1 } );
-
-You didn't know you could configure your view from the application class, eh? :)
-Thats possible for every component that inherits from Catalyst::Component
-or it's subclasses (Catalyst::Base, Catalyst::Controller, Catalyst::View,
-Catalyst::Model).
-
- __PACKAGE__->config(
- name => 'MyApp',
- 'View::TT' => {
- EVAL_PERL => 1
- },
- 'Controller::Foo' => {
- fool => 'sri'
- }
- );
-
-
- package MyApp::Controller::Foo;
- use base 'Catalyst::Controller';
-
- __PACKAGE__->config( lalala => " can't sing!" );
-
- sub default : Private {
- my ( $self, $c ) = @_;
- $c->res->body( $self->{fool} . $self->{lalala} );
- }
-
-But back to the topic, lets make our admins happy with this little idiom.
-
- use YAML ();
-
- __PACKAGE__->config( YAML::LoadFile( __PACKAGE__->path_to('myapp.yml') ) );
-
-The C<path_to()> method is a nice little helper that returns paths relative to the
-current application home.
-
-Thats it, now just create a file C<myapp.yml>.
-
- ---
- name: MyApp
- View::TT:
- EVAL_PERL: 1
- Controller::Foo:
- fool: sri
-
-
-Have fun!
-
--- sri
-
-=cut
+=head1 Catalyst Advent - Day 9 - YAML, YAML, YAML!
+
+B<NOTE>: This article was written in 2005. In the meantime, Catalyst has
+switched to using Config::General as the format for its configuration files.
+YAML files being whitespace-sensitive, copy/pasting from POD often caused
+problems. See also the Catalyst Wiki (L<http://dev.catalyst.perl.org/wiki>).
+
+When you start a new Catalyst app you configure it directly
+with __PACKAGE__->config, thats ok for development but admins
+will hate you when they have to deploy this.
+
+ __PACKAGE__->config( name => 'MyApp', 'View::TT' => { EVAL_PERL => 1 } );
+
+You didn't know you could configure your view from the application class, eh? :)
+Thats possible for every component that inherits from Catalyst::Component
+or it's subclasses (Catalyst::Base, Catalyst::Controller, Catalyst::View,
+Catalyst::Model).
+
+ __PACKAGE__->config(
+ name => 'MyApp',
+ 'View::TT' => {
+ EVAL_PERL => 1
+ },
+ 'Controller::Foo' => {
+ fool => 'sri'
+ }
+ );
+
+
+ package MyApp::Controller::Foo;
+ use base 'Catalyst::Controller';
+
+ __PACKAGE__->config( lalala => " can't sing!" );
+
+ sub default : Private {
+ my ( $self, $c ) = @_;
+ $c->res->body( $self->{fool} . $self->{lalala} );
+ }
+
+But back to the topic, lets make our admins happy with this little idiom.
+
+ use YAML ();
+
+ __PACKAGE__->config( YAML::LoadFile( __PACKAGE__->path_to('myapp.yml') ) );
+
+The C<path_to()> method is a nice little helper that returns paths relative to the
+current application home.
+
+Thats it, now just create a file C<myapp.yml>.
+
+ ---
+ name: MyApp
+ View::TT:
+ EVAL_PERL: 1
+ Controller::Foo:
+ fool: sri
+
+
+Have fun!
+
+-- sri
+
+=cut
Modified: trunk/examples/CatalystAdvent/root/2006/6.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2006/6.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2006/6.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -1,116 +1,116 @@
-=head1 Day 6 - Catalyst::Controller::BindLex
-
-Tidying up controllers with BindLex
-
-=head2 The Problem
-
-If you've done any development with Catalyst, you are almost guaranteed
-to need to put data in the stash (Catalyst's name for a hash used to
-pass data within a request cycle). This isn't a problem as such, but it
-can make the code appear...unwieldy. The more heavily you use the stash,
-the messier things will be - if you are using chained actions, you'll
-probably be constantly moving things into and out of the stash as you
-move through your chain.
-
-Let's say that you want to store the results of a multi-page process
-(for example a quiz) in the session. You might do something like this:
-
- package MyApp::C::MyQuiz;
-
- use base 'Catalyst::Controller';
-
- sub take : Local {
- my ($self, $c) = @_;
-
- # Get existing state
- my $state = $c->session->{quiz_state};
-
- # Merge current state with new params - in a real app you'd do
- # something more substantial here
- $state = { %$state, %{$c->req->params} };
- $state->{q_id}++;
-
- # Put question in stash for display
- $c->stash->{question} =
- $c->model('DBIC::Quiz')->find( $state->{q_id} );
-
- # And save the updated state back in the session
- $c->session->{quiz_state} = $state;
- }
-
-The above code snippet illustrates the problem - all the instances of
-C<< $c->stash->{ >> and C<< $c->session->{ >> make the code messier
-than it needs to be.
-
-=head2 The Solution
-
-Luckily L<Catalyst::Controller::BindLex|BindLex> comes to the rescue!
-It enables us do the following:
-
- package MyApp::C::MyQuiz;
-
- # NOTE: new base class;
- use base 'Catalyst::Controller::BindLex';
-
- sub take : Local {
- my ($self, $c) = @_;
-
- # Get existing state
- my %quiz_state : Session;
-
- # Merge current state with new params - in a real app you'd do
- # something more substantial here
- %quiz_state = ( %quiz_state, %{$c->req->params} );
- $quiz_state{q_id}++;
-
- # Put question in stash for display
- my $question : Stashed
- = $c->model('DBIC::Quiz')->find( $quiz_state{q_id} );
- }
-
-Looks a bit tidier this way, doesn't it? When you give an attribute of
-C<Session> to a lexical variable ( C<my %quiz_state> in the above
-example), it is connected to C<< $c->session->{quiz_state} >>, so that
-it will have the same value as in the session, and when you change
-something in the hash it will also be updated in the session. In fact as
-far as Perl is concerned, they are the same.
-
-BindLex provides C<Session>, C<Sessioned>, C<Stash>, C<Stashed>,
-C<Flash>, and C<Flashed> attributes to connect lexicals to C<<
-$c->session >>, C<< $c->stash >> or C<< $c->flash >>
-respectively. BindLex also has the ability to use your own custom
-attributes - see the docs for details of how to do this.
-
-It should be noted that some people view this module as a "bad thing"
-due to the modules it uses, namely L<PadWalker>, L<Array::RefElem>,
-L<Devel::Caller>, L<Devel::LexAlias>, and L<attributes>. But BindLex has
-been widely used in Catalyst applications with no ill effects observed.
-
-=head2 Current Limitations
-
-The only known current limitation of BindLex is that you cannot
-lexically bind any variable that is declared in more than one scope in a
-sub due to the specifics of perl's internals. In other words an attempt
-to use any BindLex attribute on C<$foo> in the example below will cause
-an error:
-
- sub dummy {
- my ($self, $c) = @_;
- my $foo; # First scoped here
-
- if ($c->req->arguments) {
- my $foo; # Scoped again here
- }
- }
-
-=head3 AUTHOR
-
-Ash Berlin <ash at cpan.org>
-
-=head3 COPYRIGHT
-
-Copyright 2006 Ash Berlin. This document can be freely
-redistributed and can be modified and re-distributed under the same
-conditions as Perl itself.
-
-=cut
+=head1 Day 6 - Catalyst::Controller::BindLex
+
+Tidying up controllers with BindLex
+
+=head2 The Problem
+
+If you've done any development with Catalyst, you are almost guaranteed
+to need to put data in the stash (Catalyst's name for a hash used to
+pass data within a request cycle). This isn't a problem as such, but it
+can make the code appear...unwieldy. The more heavily you use the stash,
+the messier things will be - if you are using chained actions, you'll
+probably be constantly moving things into and out of the stash as you
+move through your chain.
+
+Let's say that you want to store the results of a multi-page process
+(for example a quiz) in the session. You might do something like this:
+
+ package MyApp::C::MyQuiz;
+
+ use base 'Catalyst::Controller';
+
+ sub take : Local {
+ my ($self, $c) = @_;
+
+ # Get existing state
+ my $state = $c->session->{quiz_state};
+
+ # Merge current state with new params - in a real app you'd do
+ # something more substantial here
+ $state = { %$state, %{$c->req->params} };
+ $state->{q_id}++;
+
+ # Put question in stash for display
+ $c->stash->{question} =
+ $c->model('DBIC::Quiz')->find( $state->{q_id} );
+
+ # And save the updated state back in the session
+ $c->session->{quiz_state} = $state;
+ }
+
+The above code snippet illustrates the problem - all the instances of
+C<< $c->stash->{ >> and C<< $c->session->{ >> make the code messier
+than it needs to be.
+
+=head2 The Solution
+
+Luckily L<Catalyst::Controller::BindLex|BindLex> comes to the rescue!
+It enables us do the following:
+
+ package MyApp::C::MyQuiz;
+
+ # NOTE: new base class;
+ use base 'Catalyst::Controller::BindLex';
+
+ sub take : Local {
+ my ($self, $c) = @_;
+
+ # Get existing state
+ my %quiz_state : Session;
+
+ # Merge current state with new params - in a real app you'd do
+ # something more substantial here
+ %quiz_state = ( %quiz_state, %{$c->req->params} );
+ $quiz_state{q_id}++;
+
+ # Put question in stash for display
+ my $question : Stashed
+ = $c->model('DBIC::Quiz')->find( $quiz_state{q_id} );
+ }
+
+Looks a bit tidier this way, doesn't it? When you give an attribute of
+C<Session> to a lexical variable ( C<my %quiz_state> in the above
+example), it is connected to C<< $c->session->{quiz_state} >>, so that
+it will have the same value as in the session, and when you change
+something in the hash it will also be updated in the session. In fact as
+far as Perl is concerned, they are the same.
+
+BindLex provides C<Session>, C<Sessioned>, C<Stash>, C<Stashed>,
+C<Flash>, and C<Flashed> attributes to connect lexicals to C<<
+$c->session >>, C<< $c->stash >> or C<< $c->flash >>
+respectively. BindLex also has the ability to use your own custom
+attributes - see the docs for details of how to do this.
+
+It should be noted that some people view this module as a "bad thing"
+due to the modules it uses, namely L<PadWalker>, L<Array::RefElem>,
+L<Devel::Caller>, L<Devel::LexAlias>, and L<attributes>. But BindLex has
+been widely used in Catalyst applications with no ill effects observed.
+
+=head2 Current Limitations
+
+The only known current limitation of BindLex is that you cannot
+lexically bind any variable that is declared in more than one scope in a
+sub due to the specifics of perl's internals. In other words an attempt
+to use any BindLex attribute on C<$foo> in the example below will cause
+an error:
+
+ sub dummy {
+ my ($self, $c) = @_;
+ my $foo; # First scoped here
+
+ if ($c->req->arguments) {
+ my $foo; # Scoped again here
+ }
+ }
+
+=head3 AUTHOR
+
+Ash Berlin <ash at cpan.org>
+
+=head3 COPYRIGHT
+
+Copyright 2006 Ash Berlin. This document can be freely
+redistributed and can be modified and re-distributed under the same
+conditions as Perl itself.
+
+=cut
Modified: trunk/examples/CatalystAdvent/root/2007/14.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2007/14.pod 2009-03-11 03:06:57 UTC (rev 9488)
+++ trunk/examples/CatalystAdvent/root/2007/14.pod 2009-03-11 08:18:38 UTC (rev 9489)
@@ -4,6 +4,8 @@
model from a batch script outside Catalyst while sharing some configuration
settings such as the database connection string.
+B<UPDATE>: As of 2008, there is a new module which avoids the "kudlgy" solution
+mentioned below: L<Config::JFDI>.
=head2 Sample Application
More information about the Catalyst-commits
mailing list