Catalyst man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Catalyst(3)	      User Contributed Perl Documentation	   Catalyst(3)

NAME
       Catalyst - The Elegant MVC Web Application Framework

SYNOPSIS
       See the Catalyst::Manual distribution for comprehensive documentation
       and tutorials.

	   # Install Catalyst::Devel for helpers and other development tools
	   # use the helper to create a new application
	   catalyst.pl MyApp

	   # add models, views, controllers
	   script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
	   script/myapp_create.pl view MyTemplate TT
	   script/myapp_create.pl controller Search

	   # built in testserver -- use -r to restart automatically on changes
	   # --help to see all available options
	   script/myapp_server.pl

	   # command line testing interface
	   script/myapp_test.pl /yada

	   ### in lib/MyApp.pm
	   use Catalyst qw/-Debug/; # include plugins here as well

	   ### In lib/MyApp/Controller/Root.pm (autocreated)
	   sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
	       my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
	       $c->stash->{template} = 'foo.tt'; # set the template
	       # lookup something from db -- stash vars are passed to TT
	       $c->stash->{data} =
		 $c->model('Database::Foo')->search( { country => $args[0] } );
	       if ( $c->req->params->{bar} ) { # access GET or POST parameters
		   $c->forward( 'bar' ); # process another action
		   # do something else after forward returns
	       }
	   }

	   # The foo.tt TT template can use the stash data from the database
	   [% WHILE (item = data.next) %]
	       [% item.foo %]
	   [% END %]

	   # called for /bar/of/soap, /bar/of/soap/10, etc.
	   sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }

	   # called after all actions are finished
	   sub end : Action {
	       my ( $self, $c ) = @_;
	       if ( scalar @{ $c->error } ) { ... } # handle errors
	       return if $c->res->body; # already have a response
	       $c->forward( 'MyApp::View::TT' ); # render template
	   }

       See Catalyst::Manual::Intro for additional information.

DESCRIPTION
       Catalyst is a modern framework for making web applications without the
       pain usually associated with this process. This document is a reference
       to the main Catalyst application. If you are a new user, we suggest you
       start with Catalyst::Manual::Tutorial or Catalyst::Manual::Intro.

       See Catalyst::Manual for more documentation.

       Catalyst plugins can be loaded by naming them as arguments to the "use
       Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
       plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".

	   use Catalyst qw/My::Module/;

       If your plugin starts with a name other than "Catalyst::Plugin::", you
       can fully qualify the name by using a unary plus:

	   use Catalyst qw/
	       My::Module
	       +Fully::Qualified::Plugin::Name
	   /;

       Special flags like "-Debug" can also be specified as arguments when
       Catalyst is loaded:

	   use Catalyst qw/-Debug My::Module/;

       The position of plugins and flags in the chain is important, because
       they are loaded in the order in which they appear.

       The following flags are supported:

   -Debug
       Enables debug output. You can also force this setting from the system
       environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
       settings override the application, with <MYAPP>_DEBUG having the
       highest priority.

       This sets the log level to 'debug' and enables full debug output on the
       error screen. If you only want the latter, see $c->debug.

   -Home
       Forces Catalyst to use a specific home directory, e.g.:

	   use Catalyst qw[-Home=/usr/mst];

       This can also be done in the shell environment by setting either the
       "CATALYST_HOME" environment variable or "MYAPP_HOME"; where "MYAPP" is
       replaced with the uppercased name of your application, any "::" in the
       name will be replaced with underscores, e.g. MyApp::Web should use
       MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be
       used.

       If none of these are set, Catalyst will attempt to automatically detect
       the home directory. If you are working in a development environment,
       Catalyst will try and find the directory containing either Makefile.PL,
       Build.PL or dist.ini. If the application has been installed into the
       system (i.e.  you have done "make install"), then Catalyst will use the
       path to your application module, without the .pm extension (e.g.,
       /foo/MyApp if your application was installed at /foo/MyApp.pm)

   -Log
	   use Catalyst '-Log=warn,fatal,error';

       Specifies a comma-delimited list of log levels.

   -Stats
       Enables statistics collection and reporting.

	  use Catalyst qw/-Stats=1/;

       You can also force this setting from the system environment with
       CATALYST_STATS or <MYAPP>_STATS. The environment settings override the
       application, with <MYAPP>_STATS having the highest priority.

       Stats are also enabled if debugging  is enabled.

METHODS
   INFORMATION ABOUT THE CURRENT REQUEST
   $c->action
       Returns a Catalyst::Action object for the current action, which
       stringifies to the action name. See Catalyst::Action.

   $c->namespace
       Returns the namespace of the current action, i.e., the URI prefix
       corresponding to the controller of the current action. For example:

	   # in Controller::Foo::Bar
	   $c->namespace; # returns 'foo/bar';

   $c->request
   $c->req
       Returns the current Catalyst::Request object, giving access to
       information about the current client request (including parameters,
       cookies, HTTP headers, etc.). See Catalyst::Request.

   REQUEST FLOW HANDLING
   $c->forward( $action [, \@arguments ] )
   $c->forward( $class, $method, [, \@arguments ] )
       Forwards processing to another action, by its private name. If you give
       a class name but no method, "process()" is called. You may also
       optionally pass arguments in an arrayref. The action will receive the
       arguments in @_ and "$c->req->args". Upon returning from the function,
       "$c->req->args" will be restored to the previous values.

       Any data "return"ed from the action forwarded to, will be returned by
       the call to forward.

	   my $foodata = $c->forward('/foo');
	   $c->forward('index');
	   $c->forward(qw/Model::DBIC::Foo do_stuff/);
	   $c->forward('View::TT');

       Note that forward implies an "eval { }" around the call (actually
       execute does), thus rendering all exceptions thrown by the called
       action non-fatal and pushing them onto $c->error instead. If you want
       "die" to propagate you need to do something like:

	   $c->forward('foo');
	   die join "\n", @{ $c->error } if @{ $c->error };

       Or make sure to always return true values from your actions and write
       your code like this:

	   $c->forward('foo') || return;

       Another note is that "$c->forward" always returns a scalar because it
       actually returns $c->state which operates in a scalar context.  Thus,
       something like:

	   return @array;

       in an action that is forwarded to is going to return a scalar, i.e. how
       many items are in that array, which is probably not what you want.  If
       you need to return an array then return a reference to it, or stash it
       like so:

	   $c->stash->{array} = \@array;

       and access it from the stash.

       Keep in mind that the "end" method used is that of the caller action.
       So a "$c->detach" inside a forwarded action would run the "end" method
       from the original action requested.

   $c->detach( $action [, \@arguments ] )
   $c->detach( $class, $method, [, \@arguments ] )
   $c->detach()
       The same as forward, but doesn't return to the previous action when
       processing is finished.

       When called with no arguments it escapes the processing chain entirely.

   $c->visit( $action [, \@arguments ] )
   $c->visit( $action [, \@captures, \@arguments ] )
   $c->visit( $class, $method, [, \@arguments ] )
   $c->visit( $class, $method, [, \@captures, \@arguments ] )
       Almost the same as forward, but does a full dispatch, instead of just
       calling the new $action / "$class->$method". This means that "begin",
       "auto" and the method you go to are called, just like a new request.

       In addition both "$c->action" and "$c->namespace" are localized.	 This
       means, for example, that "$c->action" methods such as name, class and
       reverse return information for the visited action when they are invoked
       within the visited action.  This is different from the behavior of
       forward, which continues to use the $c->action object from the caller
       action even when invoked from the called action.

       "$c->stash" is kept unchanged.

       In effect, visit allows you to "wrap" another action, just as it would
       have been called by dispatching from a URL, while the analogous go
       allows you to transfer control to another action as if it had been
       reached directly from a URL.

   $c->go( $action [, \@arguments ] )
   $c->go( $action [, \@captures, \@arguments ] )
   $c->go( $class, $method, [, \@arguments ] )
   $c->go( $class, $method, [, \@captures, \@arguments ] )
       The relationship between "go" and visit is the same as the relationship
       between forward and detach. Like "$c->visit", "$c->go" will perform a
       full dispatch on the specified action or method, with localized
       "$c->action" and "$c->namespace". Like "detach", "go" escapes the
       processing of the current request chain on completion, and does not
       return to its caller.

       @arguments are arguments to the final destination of $action. @captures
       are arguments to the intermediate steps, if any, on the way to the
       final sub of $action.

   $c->response
   $c->res
       Returns the current Catalyst::Response object, see there for details.

   $c->stash
       Returns a hashref to the stash, which may be used to store data and
       pass it between components during a request. You can also set hash keys
       by passing arguments. The stash is automatically sent to the view. The
       stash is cleared at the end of a request; it cannot be used for
       persistent storage (for this you must use a session; see
       Catalyst::Plugin::Session for a complete system integrated with
       Catalyst).

	   $c->stash->{foo} = $bar;
	   $c->stash( { moose => 'majestic', qux => 0 } );
	   $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref

	   # stash is automatically passed to the view for use in a template
	   $c->forward( 'MyApp::View::TT' );

   $c->error
   $c->error($error, ...)
   $c->error($arrayref)
       Returns an arrayref containing error messages.  If Catalyst encounters
       an error while processing a request, it stores the error in $c->error.
       This method should only be used to store fatal error messages.

	   my @error = @{ $c->error };

       Add a new error.

	   $c->error('Something bad happened');

   $c->state
       Contains the return value of the last executed action.  Note that <<
       $c->state >> operates in a scalar context which means that all values
       it returns are scalar.

   $c->clear_errors
       Clear errors.  You probably don't want to clear the errors unless you
       are implementing a custom error screen.

       This is equivalent to running

	   $c->error(0);

   COMPONENT ACCESSORS
   $c->controller($name)
       Gets a Catalyst::Controller instance by name.

	   $c->controller('Foo')->do_stuff;

       If the name is omitted, will return the controller for the dispatched
       action.

       If you want to search for controllers, pass in a regexp as the
       argument.

	   # find all controllers that start with Foo
	   my @foo_controllers = $c->controller(qr{^Foo});

   $c->model($name)
       Gets a Catalyst::Model instance by name.

	   $c->model('Foo')->do_stuff;

       Any extra arguments are directly passed to ACCEPT_CONTEXT.

       If the name is omitted, it will look for
	- a model object in $c->stash->{current_model_instance}, then
	- a model name in $c->stash->{current_model}, then
	- a config setting 'default_model', or
	- check if there is only one model, and return it if that's the case.

       If you want to search for models, pass in a regexp as the argument.

	   # find all models that start with Foo
	   my @foo_models = $c->model(qr{^Foo});

   $c->view($name)
       Gets a Catalyst::View instance by name.

	   $c->view('Foo')->do_stuff;

       Any extra arguments are directly passed to ACCEPT_CONTEXT.

       If the name is omitted, it will look for
	- a view object in $c->stash->{current_view_instance}, then
	- a view name in $c->stash->{current_view}, then
	- a config setting 'default_view', or
	- check if there is only one view, and return it if that's the case.

       If you want to search for views, pass in a regexp as the argument.

	   # find all views that start with Foo
	   my @foo_views = $c->view(qr{^Foo});

   $c->controllers
       Returns the available names which can be passed to $c->controller

   $c->models
       Returns the available names which can be passed to $c->model

   $c->views
       Returns the available names which can be passed to $c->view

   $c->comp($name)
   $c->component($name)
       Gets a component object by name. This method is not recommended, unless
       you want to get a specific component by full class. "$c->controller",
       "$c->model", and "$c->view" should be used instead.

       If $name is a regexp, a list of components matched against the full
       component name will be returned.

       If Catalyst can't find a component by name, it will fallback to regex
       matching by default. To disable this behaviour set
       disable_component_resolution_regex_fallback to a true value.

	   __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );

   CLASS DATA AND HELPER CLASSES
   $c->config
       Returns or takes a hashref containing the application's configuration.

	   __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );

       You can also use a "YAML", "XML" or Config::General config file like
       "myapp.conf" in your applications home directory. See
       Catalyst::Plugin::ConfigLoader.

       Cascading configuration

       The config method is present on all Catalyst components, and
       configuration will be merged when an application is started.
       Configuration loaded with Catalyst::Plugin::ConfigLoader takes
       precedence over other configuration, followed by configuration in your
       top level "MyApp" class. These two configurations are merged, and then
       configuration data whose hash key matches a component name is merged
       with configuration for that component.

       The configuration for a component is then passed to the "new" method
       when a component is constructed.

       For example:

	   MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
	   MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });

       will mean that "MyApp::Model::Foo" receives the following data when
       constructed:

	   MyApp::Model::Foo->new({
	       bar => 'baz',
	       quux => 'frob',
	       overrides => 'me',
	   });

       It's common practice to use a Moose attribute on the receiving
       component to access the config value.

	   package MyApp::Model::Foo;

	   use Moose;

	   # this attr will receive 'baz' at construction time
	   has 'bar' => (
	       is  => 'rw',
	       isa => 'Str',
	   );

       You can then get the value 'baz' by calling $c->model('Foo')->bar (or
       $self->bar inside code in the model).

       NOTE: you MUST NOT call "$self->config" or "__PACKAGE__->config" as a
       way of reading config within your code, as this will not give you the
       correctly merged config back. You MUST take the config values supplied
       to the constructor and use those instead.

   $c->log
       Returns the logging object instance. Unless it is already set, Catalyst
       sets this up with a Catalyst::Log object. To use your own log class,
       set the logger with the "__PACKAGE__->log" method prior to calling
       "__PACKAGE__->setup".

	__PACKAGE__->log( MyLogger->new );
	__PACKAGE__->setup;

       And later:

	   $c->log->info( 'Now logging with my own logger!' );

       Your log class should implement the methods described in Catalyst::Log.

   $c->debug
       Returns 1 if debug mode is enabled, 0 otherwise.

       You can enable debug mode in several ways:

       By calling myapp_server.pl with the -d flag
       With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
       The -Debug option in your MyApp.pm
       By declaring "sub debug { 1 }" in your MyApp.pm.

       The first three also set the log level to 'debug'.

       Calling "$c->debug(1)" has no effect.

   $c->dispatcher
       Returns the dispatcher instance. See Catalyst::Dispatcher.

   $c->engine
       Returns the engine instance. See Catalyst::Engine.

   UTILITY METHODS
   $c->path_to(@path)
       Merges @path with "$c->config->{home}" and returns a Path::Class::Dir
       object. Note you can usually use this object as a filename, but
       sometimes you will have to explicitly stringify it yourself by calling
       the "->stringify" method.

       For example:

	   $c->path_to( 'db', 'sqlite.db' );

   MyApp->setup
       Initializes the dispatcher and engine, loads any plugins, and loads the
       model, view, and controller components. You may also specify an array
       of plugins to load here, if you choose to not load them in the "use
       Catalyst" line.

	   MyApp->setup;
	   MyApp->setup( qw/-Debug/ );

       Note: You should not wrap this method with method modifiers or bad
       things will happen - wrap the "setup_finalize" method instead.

   $app->setup_finalize
       A hook to attach modifiers to. This method does not do anything except
       set the "setup_finished" accessor.

       Applying method modifiers to the "setup" method doesn't work, because
       of quirky things done for plugin setup.

       Example:

	   after setup_finalize => sub {
	       my $app = shift;

	       ## do stuff here..
	   };

   $c->uri_for( $path?, @args?, \%query_values? )
   $c->uri_for( $action, \@captures?, @args?, \%query_values? )
       Constructs an absolute URI object based on the application root, the
       provided path, and the additional arguments and query parameters
       provided.  When used as a string, provides a textual URI.  If you need
       more flexibility than this (i.e. the option to provide relative URIs
       etc.) see Catalyst::Plugin::SmartURI.

       If no arguments are provided, the URI for the current action is
       returned.  To return the current action and also provide @args, use
       "$c->uri_for( $c->action, @args )".

       If the first argument is a string, it is taken as a public URI path
       relative to "$c->namespace" (if it doesn't begin with a forward slash)
       or relative to the application root (if it does). It is then merged
       with "$c->request->base"; any @args are appended as additional path
       components; and any %query_values are appended as "?foo=bar"
       parameters.

       If the first argument is a Catalyst::Action it represents an action
       which will have its path resolved using
       "$c->dispatcher->uri_for_action". The optional "\@captures" argument
       (an arrayref) allows passing the captured variables that are needed to
       fill in the paths of Chained and Regex actions; once the path is
       resolved, "uri_for" continues as though a path was provided, appending
       any arguments or parameters and creating an absolute URI.

       The captures for the current request can be found in
       "$c->request->captures", and actions can be resolved using
       "Catalyst::Controller->action_for($name)". If you have a private action
       path, use "$c->uri_for_action" instead.

	 # Equivalent to $c->req->uri
	 $c->uri_for($c->action, $c->req->captures,
	     @{ $c->req->args }, $c->req->params);

	 # For the Foo action in the Bar controller
	 $c->uri_for($c->controller('Bar')->action_for('Foo'));

	 # Path to a static resource
	 $c->uri_for('/static/images/logo.png');

   $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
   $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values?
       )
       $path
	   A private path to the Catalyst action you want to create a URI for.

	   This is a shortcut for calling
	   "$c->dispatcher->get_action_by_path($path)" and passing the
	   resulting $action and the remaining arguments to "$c->uri_for".

	   You can also pass in a Catalyst::Action object, in which case it is
	   passed to "$c->uri_for".

	   Note that although the path looks like a URI that dispatches to the
	   wanted action, it is not a URI, but an internal path to that
	   action.

	   For example, if the action looks like:

	    package MyApp::Controller::Users;

	    sub lst : Path('the-list') {}

	   You can use:

	    $c->uri_for_action('/users/lst')

	   and it will create the URI /users/the-list.

       \@captures_and_args?
	   Optional array reference of Captures (i.e. "<CaptureArgs or
	   $c-"req->captures>) and arguments to the request. Usually used with
	   Catalyst::DispatchType::Chained to interpolate all the parameters
	   in the URI.

       @args?
	   Optional list of extra arguments - can be supplied in the
	   "\@captures_and_args?" array ref, or here - whichever is easier for
	   your code.

	   Your action can have zero, a fixed or a variable number of args
	   (e.g.  Args(1) for a fixed number or "Args()" for a variable
	   number)..

       \%query_values?
	   Optional array reference of query parameters to append. E.g.

	     { foo => 'bar' }

	   will generate

	     /rest/of/your/uri?foo=bar

   $c->welcome_message
       Returns the Catalyst welcome HTML page.

   run_options
       Contains a hash of options passed from the application script,
       including the original ARGV the script received, the processed values
       from that ARGV and any extra arguments to the script which were not
       processed.

       This can be used to add custom options to your application's scripts
       and setup your application differently depending on the values of these
       options.

INTERNAL METHODS
       These methods are not meant to be used by end users.

   $c->components
       Returns a hash of components.

   $c->context_class
       Returns or sets the context class.

   $c->counter
       Returns a hashref containing coderefs and execution counts (needed for
       deep recursion detection).

   $c->depth
       Returns the number of actions on the current internal execution stack.

   $c->dispatch
       Dispatches a request to actions.

   $c->dispatcher_class
       Returns or sets the dispatcher class.

   $c->dump_these
       Returns a list of 2-element array references (name, structure) pairs
       that will be dumped on the error page in debug mode.

   $c->engine_class
       Returns or sets the engine class.

   $c->execute( $class, $coderef )
       Execute a coderef in given class and catch exceptions. Errors are
       available via $c->error.

   $c->finalize
       Finalizes the request.

   $c->finalize_body
       Finalizes body.

   $c->finalize_cookies
       Finalizes cookies.

   $c->finalize_error
       Finalizes error.

   $c->finalize_headers
       Finalizes headers.

   $c->finalize_output
       An alias for finalize_body.

   $c->finalize_read
       Finalizes the input after reading is complete.

   $c->finalize_uploads
       Finalizes uploads. Cleans up any temporary files.

   $c->get_action( $action, $namespace )
       Gets an action in a given namespace.

   $c->get_actions( $action, $namespace )
       Gets all actions of a given name in a namespace and all parent
       namespaces.

   $app->handle_request( @arguments )
       Called to handle each HTTP request.

   $class->prepare( @arguments )
       Creates a Catalyst context from an engine-specific request (Apache,
       CGI, etc.).

   $c->prepare_action
       Prepares action. See Catalyst::Dispatcher.

   $c->prepare_body
       Prepares message body.

   $c->prepare_body_chunk( $chunk )
       Prepares a chunk of data before sending it to HTTP::Body.

       See Catalyst::Engine.

   $c->prepare_body_parameters
       Prepares body parameters.

   $c->prepare_connection
       Prepares connection.

   $c->prepare_cookies
       Prepares cookies by ensuring that the attribute on the request object
       has been built.

   $c->prepare_headers
       Prepares request headers by ensuring that the attribute on the request
       object has been built.

   $c->prepare_parameters
       Prepares parameters.

   $c->prepare_path
       Prepares path and base.

   $c->prepare_query_parameters
       Prepares query parameters.

   $c->log_request
       Writes information about the request to the debug logs.	This includes:

       ·   Request method, path, and remote IP address

       ·   Query keywords (see "query_keywords" in Catalyst::Request)

       ·   Request parameters

       ·   File uploads

   $c->log_response
       Writes information about the response to the debug logs by calling
       "$c->log_response_status_line" and "$c->log_response_headers".

   $c->log_response_status_line($response)
       Writes one line of information about the response to the debug logs.
       This includes:

       ·   Response status code

       ·   Content-Type header (if present)

       ·   Content-Length header (if present)

   $c->log_response_headers($headers);
       Hook method which can be wrapped by plugins to log the response
       headers.	 No-op in the default implementation.

   $c->log_request_parameters( query => {}, body => {} )
       Logs request parameters to debug logs

   $c->log_request_uploads
       Logs file uploads included in the request to the debug logs.  The
       parameter name, filename, file type, and file size are all included in
       the debug logs.

   $c->log_request_headers($headers);
       Hook method which can be wrapped by plugins to log the request headers.
       No-op in the default implementation.

   $c->log_headers($type => $headers)
       Logs HTTP::Headers (either request or response) to the debug logs.

   $c->prepare_read
       Prepares the input for reading.

   $c->prepare_request
       Prepares the engine request.

   $c->prepare_uploads
       Prepares uploads.

   $c->prepare_write
       Prepares the output for writing.

   $c->request_class
       Returns or sets the request class. Defaults to Catalyst::Request.

   $c->response_class
       Returns or sets the response class. Defaults to Catalyst::Response.

   $c->read( [$maxlength] )
       Reads a chunk of data from the request body. This method is designed to
       be used in a while loop, reading $maxlength bytes on every call.
       $maxlength defaults to the size of the request if not specified.

       You have to set "MyApp->config(parse_on_demand => 1)" to use this
       directly.

       Warning: If you use read(), Catalyst will not process the body, so you
       will not be able to access POST parameters or file uploads via
       $c->request.  You must handle all body parsing yourself.

   $c->run
       Starts the engine.

   $c->set_action( $action, $code, $namespace, $attrs )
       Sets an action in a given namespace.

   $c->setup_actions($component)
       Sets up actions for a component.

   $c->setup_components
       This method is called internally to set up the application's
       components.

       It finds modules by calling the locate_components method, expands them
       to package names with the expand_component_module method, and then
       installs each component into the application.

       The "setup_components" config option is passed to both of the above
       methods.

       Installation of each component is performed by the setup_component
       method, below.

   $c->locate_components( $setup_component_config )
       This method is meant to provide a list of component modules that should
       be setup for the application.  By default, it will use
       Module::Pluggable.

       Specify a "setup_components" config option to pass additional options
       directly to Module::Pluggable. To add additional search paths, specify
       a key named "search_extra" as an array reference. Items in the array
       beginning with "::" will have the application class name prepended to
       them.

   $c->expand_component_module( $component, $setup_component_config )
       Components found by "locate_components" will be passed to this method,
       which is expected to return a list of component (package) names to be
       set up.

   $c->setup_component
   $c->setup_dispatcher
       Sets up dispatcher.

   $c->setup_engine
       Sets up engine.

   $c->apply_default_middlewares
       Adds the following Plack middlewares to your application, since they
       are useful and commonly needed:

       Plack::Middleware::ReverseProxy, (conditionally added based on the
       status of your $ENV{REMOTE_ADDR}, and can be forced on with
       "using_frontend_proxy" or forced off with "ignore_frontend_proxy"),
       Plack::Middleware::LighttpdScriptNameFix (if you are using Lighttpd),
       Plack::Middleware::IIS6ScriptNameFix (always applied since this
       middleware is smart enough to conditionally apply itself).

       Additionally if we detect we are using Nginx, we add a bit of custom
       middleware to solve some problems with the way that server handles
       $ENV{PATH_INFO} and $ENV{SCRIPT_NAME}

   $c->psgi_app
       Returns a PSGI application code reference for the catalyst application
       $c. This is the bare application without any middlewares applied.
       "${myapp}.psgi" is not taken into account.

       This is what you want to be using to retrieve the PSGI application code
       reference of your Catalyst application for use in .psgi files.

   $c->setup_home
       Sets up the home directory.

   $c->setup_log
       Sets up log by instantiating a Catalyst::Log object and passing it to
       "log()". Pass in a comma-delimited list of levels to set the log to.

       This method also installs a "debug" method that returns a true value
       into the catalyst subclass if the "debug" level is passed in the comma-
       delimited list, or if the $CATALYST_DEBUG environment variable is set
       to a true value.

       Note that if the log has already been setup, by either a previous call
       to "setup_log" or by a call such as "__PACKAGE__->log( MyLogger->new
       )", that this method won't actually set up the log object.

   $c->setup_plugins
       Sets up plugins.

   $c->setup_stats
       Sets up timing statistics class.

   $c->registered_plugins
       Returns a sorted list of the plugins which have either been stated in
       the import list.

       If passed a given plugin name, it will report a boolean value
       indicating whether or not that plugin is loaded.	 A fully qualified
       name is required if the plugin name does not begin with
       "Catalyst::Plugin::".

	if ($c->registered_plugins('Some::Plugin')) {
	    ...
	}

   $c->stack
       Returns an arrayref of the internal execution stack (actions that are
       currently executing).

   $c->stats
       Returns the current timing statistics object. By default Catalyst uses
       Catalyst::Stats, but can be set otherwise with stats_class.

       Even if -Stats is not enabled, the stats object is still available. By
       enabling it with " $c-"stats->enabled(1) >, it can be used to profile
       explicitly, although MyApp.pm still won't profile nor output anything
       by itself.

   $c->stats_class
       Returns or sets the stats (timing statistics) class. Catalyst::Stats is
       used by default.

   $c->use_stats
       Returns 1 when stats collection is enabled.

       Note that this is a static method, not an accessor and should be
       overridden by declaring "sub use_stats { 1 }" in your MyApp.pm, not by
       calling "$c->use_stats(1)".

   $c->write( $data )
       Writes $data to the output stream. When using this method directly, you
       will need to manually set the "Content-Length" header to the length of
       your output data, if known.

   version
       Returns the Catalyst version number. Mostly useful for "powered by"
       messages in template systems.

CONFIGURATION
       There are a number of 'base' config variables which can be set:

       ·   "default_model" - The default model picked if you say "$c->model".
	   See "$c->model($name)".

       ·   "default_view" - The default view to be rendered or returned when
	   "$c->view" is called. See "$c->view($name)".

       ·   "disable_component_resolution_regex_fallback" - Turns off the
	   deprecated component resolution functionality so that if any of the
	   component methods (e.g. "$c->controller('Foo')") are called then
	   regex search will not be attempted on string values and instead
	   "undef" will be returned.

       ·   "home" - The application home directory. In an uninstalled
	   application, this is the top level application directory. In an
	   installed application, this will be the directory containing
	   "MyApp.pm".

       ·   "ignore_frontend_proxy" - See "PROXY SUPPORT"

       ·   "name" - The name of the application in debug messages and the
	   debug and welcome screens

       ·   "parse_on_demand" - The request body (for example file uploads)
	   will not be parsed until it is accessed. This allows you to (for
	   example) check authentication (and reject the upload) before
	   actually receiving all the data. See "ON-DEMAND PARSER"

       ·   "root" - The root directory for templates. Usually this is just a
	   subdirectory of the home directory, but you can set it to change
	   the templates to a different directory.

       ·   "search_extra" - Array reference passed to Module::Pluggable to for
	   additional namespaces from which components will be loaded (and
	   constructed and stored in "$c->components").

       ·   "show_internal_actions" - If true, causes internal actions such as
	   "_DISPATCH" to be shown in hit debug tables in the test server.

       ·   "use_request_uri_for_path" - Controls if the "REQUEST_URI" or
	   "PATH_INFO" environment variable should be used for determining the
	   request path.

	   Most web server environments pass the requested path to the
	   application using environment variables, from which Catalyst has to
	   reconstruct the request base (i.e. the top level path to / in the
	   application, exposed as "$c->request->base") and the request path
	   below that base.

	   There are two methods of doing this, both of which have advantages
	   and disadvantages. Which method is used is determined by the
	   "$c->config(use_request_uri_for_path)" setting (which can either be
	   true or false).

	   use_request_uri_for_path => 0
	       This is the default (and the) traditional method that Catalyst
	       has used for determining the path information.  The path is
	       generated from a combination of the "PATH_INFO" and
	       "SCRIPT_NAME" environment variables.  The allows the
	       application to behave correctly when "mod_rewrite" is being
	       used to redirect requests into the application, as these
	       variables are adjusted by mod_rewrite to take account for the
	       redirect.

	       However this method has the major disadvantage that it is
	       impossible to correctly decode some elements of the path, as
	       RFC 3875 says: ""Unlike a URI path, the PATH_INFO is not
	       URL-encoded, and cannot contain path-segment parameters."" This
	       means PATH_INFO is always decoded, and therefore Catalyst can't
	       distinguish / vs %2F in paths (in addition to other encoded
	       values).

	   use_request_uri_for_path => 1
	       This method uses the "REQUEST_URI" and "SCRIPT_NAME"
	       environment variables. As "REQUEST_URI" is never decoded, this
	       means that applications using this mode can correctly handle
	       URIs including the %2F character (i.e. with
	       "AllowEncodedSlashes" set to "On" in Apache).

	       Given that this method of path resolution is provably more
	       correct, it is recommended that you use this unless you have a
	       specific need to deploy your application in a non-standard
	       environment, and you are aware of the implications of not being
	       able to handle encoded URI paths correctly.

	       However it also means that in a number of cases when the app
	       isn't installed directly at a path, but instead is having paths
	       rewritten into it (e.g. as a .cgi/fcgi in a public_html
	       directory, with mod_rewrite in a .htaccess file, or when SSI is
	       used to rewrite pages into the app, or when sub-paths of the
	       app are exposed at other URIs than that which the app is
	       'normally' based at with "mod_rewrite"), the resolution of
	       "$c->request->base" will be incorrect.

       ·   "using_frontend_proxy" - See "PROXY SUPPORT".

INTERNAL ACTIONS
       Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO",
       "_ACTION", and "_END". These are by default not shown in the private
       action table, but you can make them visible with a config parameter.

	   MyApp->config(show_internal_actions => 1);

ON-DEMAND PARSER
       The request body is usually parsed at the beginning of a request, but
       if you want to handle input yourself, you can enable on-demand parsing
       with a config parameter.

	   MyApp->config(parse_on_demand => 1);

PROXY SUPPORT
       Many production servers operate using the common double-server
       approach, with a lightweight frontend web server passing requests to a
       larger backend server. An application running on the backend server
       must deal with two problems: the remote user always appears to be
       127.0.0.1 and the server's hostname will appear to be "localhost"
       regardless of the virtual host that the user connected through.

       Catalyst will automatically detect this situation when you are running
       the frontend and backend servers on the same machine. The following
       changes are made to the request.

	   $c->req->address is set to the user's real IP address, as read from
	   the HTTP X-Forwarded-For header.

	   The host value for $c->req->base and $c->req->uri is set to the real
	   host, as read from the HTTP X-Forwarded-Host header.

       Additionally, you may be running your backend application on an
       insecure connection (port 80) while your frontend proxy is running
       under SSL.  If there is a discrepancy in the ports, use the HTTP header
       "X-Forwarded-Port" to tell Catalyst what port the frontend listens on.
       This will allow all URIs to be created properly.

       In the case of passing in:

	   X-Forwarded-Port: 443

       All calls to "uri_for" will result in an https link, as is expected.

       Obviously, your web server must support these headers for this to work.

       In a more complex server farm environment where you may have your
       frontend proxy server(s) on different machines, you will need to set a
       configuration option to tell Catalyst to read the proxied data from the
       headers.

	   MyApp->config(using_frontend_proxy => 1);

       If you do not wish to use the proxy support at all, you may set:

	   MyApp->config(ignore_frontend_proxy => 0);

   Note about psgi files
       Note that if you supply your own .psgi file, calling
       "MyApp->psgi_app(@_);", then this will not happen automatically.

       You either need to apply Plack::Middleware::ReverseProxy yourself in
       your psgi, for example:

	   builder {
	       enable "Plack::Middleware::ReverseProxy";
	       MyApp->psgi_app
	   };

       This will unconditionally add the ReverseProxy support, or you need to
       call "$app = MyApp->apply_default_middlewares($app)" (to conditionally
       apply the support depending upon your config).

       See Catalyst::PSGI for more information.

THREAD SAFETY
       Catalyst has been tested under Apache 2's threading "mpm_worker",
       "mpm_winnt", and the standalone forking HTTP server on Windows. We
       believe the Catalyst core to be thread-safe.

       If you plan to operate in a threaded environment, remember that all
       other modules you are using must also be thread-safe. Some modules,
       most notably DBD::SQLite, are not thread-safe.

SUPPORT
       IRC:

	   Join #catalyst on irc.perl.org.

       Mailing Lists:

	   http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
	   http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev

       Web:

	   http://catalyst.perl.org

       Wiki:

	   http://dev.catalyst.perl.org

SEE ALSO
   Task::Catalyst - All you need to start with Catalyst
   Catalyst::Manual - The Catalyst Manual
   Catalyst::Component, Catalyst::Controller - Base classes for components
   Catalyst::Engine - Core engine
   Catalyst::Log - Log class.
   Catalyst::Request - Request object
   Catalyst::Response - Response object
   Catalyst::Test - The test suite.
PROJECT FOUNDER
       sri: Sebastian Riedel <sri@cpan.org>

CONTRIBUTORS
       abw: Andy Wardley

       acme: Leon Brocard <leon@astray.com>

       abraxxa: Alexander Hartmaier <abraxxa@cpan.org>

       Andrew Bramble

       Andrew Ford <A.Ford@ford-mason.co.uk>

       Andrew Ruthven

       andyg: Andy Grundman <andy@hybridized.org>

       audreyt: Audrey Tang

       bricas: Brian Cassidy <bricas@cpan.org>

       Caelum: Rafael Kitover <rkitover@io.com>

       chansen: Christian Hansen

       chicks: Christopher Hicks

       Chisel Wright "pause@herlpacker.co.uk"

       Danijel Milicevic "me@danijel.de"

       David Kamholz <dkamholz@cpan.org>

       David Naughton, "naughton@umn.edu"

       David E. Wheeler

       dhoss: Devin Austin <dhoss@cpan.org>

       dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>

       Drew Taylor

       dwc: Daniel Westermann-Clark <danieltwc@cpan.org>

       esskar: Sascha Kiefer

       fireartist: Carl Franks <cfranks@cpan.org>

       frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>

       gabb: Danijel Milicevic

       Gary Ashton Jones

       Gavin Henry "ghenry@perl.me.uk"

       Geoff Richards

       groditi: Guillermo Roditi <groditi@gmail.com>

       hobbs: Andrew Rodland <andrew@cleverdomain.org>

       ilmari: Dagfinn Ilmari MannsA~Xker <ilmari@ilmari.org>

       jcamacho: Juan Camacho

       jester: Jesse Sheidlower "jester@panix.com"

       jhannah: Jay Hannah <jay@jays.net>

       Jody Belka

       Johan Lindstrom

       jon: Jon Schutz <jjschutz@cpan.org>

       Jonathan Rockway "<jrockway@cpan.org>"

       Kieren Diment "kd@totaldatasolution.com"

       konobi: Scott McWhirter <konobi@cpan.org>

       marcus: Marcus Ramberg <mramberg@cpan.org>

       miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>

       mst: Matt S. Trout <mst@shadowcatsystems.co.uk>

       mugwump: Sam Vilain

       naughton: David Naughton

       ningu: David Kamholz <dkamholz@cpan.org>

       nothingmuch: Yuval Kogman <nothingmuch@woobling.org>

       numa: Dan Sully <daniel@cpan.org>

       obra: Jesse Vincent

       Octavian Rasnita

       omega: Andreas Marienborg

       Oleg Kostyuk <cub.uanic@gmail.com>

       phaylon: Robert Sedlacek <phaylon@dunkelheit.at>

       rafl: Florian Ragwitz <rafl@debian.org>

       random: Roland Lammel <lammel@cpan.org>

       Robert Sedlacek "<rs@474.at>"

       SpiceMan: Marcel Montes

       sky: Arthur Bergman

       szbalint: Balint Szilakszi <szbalint@cpan.org>

       t0m: Tomas Doran <bobtfish@bobtfish.net>

       Ulf Edvinsson

       Viljo Marrandi "vilts@yahoo.com"

       Will Hawes "info@whawes.co.uk"

       willert: Sebastian Willert <willert@cpan.org>

       wreis: Wallace Reis <wallace@reis.org.br>

       Yuval Kogman, "nothingmuch@woobling.org"

       rainboxx: Matthias Dietrich, "perl@rainboxx.de"

       dd070: Dhaval Dhanani <dhaval070@gmail.com>

COPYRIGHT
       Copyright (c) 2005, the above named PROJECT FOUNDER and CONTRIBUTORS.

LICENSE
       This library is free software. You can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.14.2			  2012-03-08			   Catalyst(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net