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 overrided 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@verticalone.pt"

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.

