NAME

Catalyst::Engine::Embeddable - Use a Catalyst application as an object

SYNOPSIS

  # after creating the application using this engine, you can just
  my $http_response;
  my $response_code $app->handle_request(
           $http_request, \$http_response);

ABSTRACT

Enables a Catalyst application to be used as a standard Perl object.

SUMMARY

This module provides a way to embed a Catalyst application in any other program using standard Perl Object Orientation to do a request and get the response.

It works by using the arguments that are passed from the handle_request method in the Catalyst module to the prepare_request method in the engine, which will then handle the request as coming from the HTTP::Request object passed, instead of trying to fetch the elements from the ENV, like the CGI engine does.

As the handle_request method only returns the response code and not the response object at all, in the case you want the complete response you need to pass a second argument which is a scalar ref where the HTTP::Response object will be stored in the "finalize" phase of the processing.

This engine provides complete compatibility with any plugin the application may use, in a way that different embedded applications may use different plugins and still be used side-by-side.

There's one important consideration regarding the URI in the request. For the means of the Catalyst processing, the base path for the script is always constructed as the "/" path of the same URI as the request.

METHODS

The following methods were overriden from Catalyst::Engine.

$engine->prepare_request($c, $http_request, $http_response_ret_ref)

This method is overriden in order to store the request and the response in $c as to continue the processing later. The scalar ref here will be used to set the response object, as there is no other way to obtain the response.

This information will be stored as $c->req->{_engine_embeddable}{req} and $c->req->{_engine_embeddable}{res} for future usage.

$engine->prepare_headers($c)

This is where the headers are fetched from the HTTP::Request object and set into $c->req.

$engine->prepare_path($c)

Get the path info from the HTTP::Request object.

$engine->prepare_query_parameters($c)

Set the query params from the HTTP::Request to the catalyst request.

$engine->prepare_body($c)

Gets the body of the HTTP::Request, creates an HTTP::Body object, and set it in $c->req->{_body}, then being compatible with Catalyst::Engine from now on.

$engine->finalize_headers($c)

Set the "Status" header in the response and store the headers from the catalyst response object to the HTTP::Response object.

$engine->finalize_body($c)

Copies the body from the catalyst response to the HTTP::Response object.

SEE ALSO

Catalyst::Engine, Catalyst::Engine::CGI, HTTP::Request, HTTP::Reponse, Catalyst

AUTHORS

Daniel Ruoso daniel@ruoso.com

Currently maintained by Tomas Doran (t0m) bobtfish@bobtfish.net

BUG REPORTS

Please submit all bugs regarding Catalyst::Engine::Embeddable to bug-catalyst-engine-embeddable@rt.cpan.org

LICENSE

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