The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Catalyst-View-Template-PHP-0.04
River stage zero No dependents
1 ++
/ Catalyst::View::Template::PHP

NAME

Catalyst::View::Template::PHP - Use PHP as a templating system within Catalyst

VERSION

Version 0.04

SYNOPSIS

    # create a PHP view in your class with the helper
    $ myapp_create.pl view PHP Template::PHP

    # in myapp.conf
    <Template::PHP>
        include_path  ...
        ...           ...
    </Template::PHP>

    # lib/MyApp/View/PHP.pm
    package MyApp::View::PHP;
    extends 'Catalyst::View::Template::PHP';

    __PACKAGE__->config->{...some php option...} = ... option value ...;

    sub preprocess {
        my ($self,$c,$params) = @_;
        # adjust params as needed to set global PHP variables
        return $params;
    }

    sub postprocess {
        my ($self,$c,$output) = @_;
        # post process the PHP output
        return $output;
    }

    # and somewhere else, maybe a controller
    $c->stash->{template} = '/path/to/some/script.php';
    $c->forward( 'MyApp::View::PHP' );

DESCRIPTION

This is a Catalyst view class for the PHP module (a Perl module for embedding PHP into Perl programs). It is similar to and inspired by the Catalyst::View::PHP view class, but that class is written for the PHP::Interpreter module.

The PHP file to be interpreted is specified in $c->stash->{template}. The view class helps set up the appropriate $_SERVER, $_ENV, $_COOKIE, $_FILES, and $_GET/$_POST/$_REQUEST variables in the PHP interpreter. In addition, the contents of $c->stash are exported as global variables (as in Template Toolkit), and the current context will be available in the global variable $c.

The workflow for this class looks like:

0. set $c->stash->{template} to the PHP script to execute. Invoke "process" in Catalyst::View::Template::PHP->process.
1. <process initializes the global variables in PHP, including
$_ENV

This is the server environment (the environment you're running Catalyst in)

$_SERVER
$_GET/$_POST/$_REQUEST

PHP observes slightly different rules for parsing form input into an associative array of parameters than Perl does, so setting these are not quite as simple as copying the relevant Catalyst request components over to PHP.

stash

As with Catalyst::View::TT, the contents of the stash ($c->stash) will be accessible in PHP as global variables.

$HTTP_RAW_POST_DATA, php://input

On POST requests where the content-type is not multipart/form-data or application/x-www-url-form-encoded, the global PHP variable $HTTP_RAW_POST_DATA and the PHP input stream php://input will be set to contain the content of the request.

Catalyst::View::Template::PHP cannot currently set up PHP's php://input stream, so $HTTP_RAW_POST_DATA is the only way to access the raw request content.

2. Invokes the "preprocess" method. Subclasses may override this method and make adjustments to the global variables before they are initialized in the PHP interpreter.
3. The PHP script is loaded and evaluated (using "include" in PHP). If the PHP interpreter calls the PHP header() function, then this class's "header_callback" method will be called with the header data. Subclasses can override the "header_callback" method to provide custom handling of headers.
4. The "postprocess" method is called with the output from PHP. Subclasses may override this method and modify the output or the headers.
5. If PHP produced a Location: ... header, this class's "on_redirect" method is called. If this method returns a true value, the process method redirects to the specified location and detaches.
6. Otherwise, the "finalize" method is called. The default behavior of this method is to set the response headers with the PHP headers and the response body with the PHP output, but this method may be overridden in a subclass to provide different behavior.

METHODS

Most of these methods are hooks into the "process" method that allow subclasses to intercept and customize the interaction between Perl and PHP.

new

View constructor

process
$self->process( $c )

Sets up the PHP interpreter instance, intializes some global variables, and invokes the interpeter on the script named in $c->stash->{template}. Output from the PHP interpreter is put into $c->response->{output}.

preprocess
$params = $self->preprocess($c, $params)

Callback just before global variables are initialized in the new PHP interpreter instance. Subclasses may override this method and make adjustments to $params, a hash reference containing the set of global variables that will be set in PHP.

postprocess
$new_output = $self->postprocess($c, $output)

Callback after the PHP interpreter has finished processing the template script. Subclasses may override this method to perform further processing on the output, before the output is passed to $c->response->output. This method MUST RETURN THE OUTPUT, or else all the output will be erased.

The postprocess method is also a good place to manipulate the headers produced by PHP (see "header_callback"), if such manipulation is desired.

handle_warning
$self->handle_warning($c, $message)

Handles a run-time warning message from the PHP interpreter. By default, this message logs a warning to Catalyst with the text "PHP warning:" prepended to the message. A subclass may override this method and do anything they wish with the warning messages.

handle_error
$self->handle_error($c, $template, $error_msg)

If the PHP interpreter encounters a run-time or compile-time error, this method will be called with the error message. The default behavior is to log a warning message, but this method can be overridden in the subclass.

header_callback
$self->header_callback($c, $header_msg, $replace)

Invoked whenever the PHP interpreter calls the PHP header(STRING) function. The default behavior of this callback is to accumulate the list of headers produced by PHP into the list reference $self->{_headers}. Subclasses may override this behavior and handle the headers from PHP anyway they like.

The $replace argument corresponds to the second argument of PHP's header() function, indicating whether a duplicate header key should replace an earlier header, or whether there should be multiple headers of the same type.

on_redirect
$proceed = $self->on_redirect($c, $location, $status [=302] )

Called if PHP produced a Location: ... header. Subclasses should override this method and return a false value if they do not want to redirect to the new location.

finalize
$self->finalize($c, $output)

The default behavior of this method is to copy the PHP response headers to the Catalyst response headers, and set the PHP output to the Catalyst response output. Subclasses may override this method to do something else.

CONFIG

include_path

a whitespace-separated list of paths where the PHP interpreter can look for scripts that were referenced in calls to the PHP include, require, include_once, or require_once functions.

debug

If non-zero, sends verbose information about the inputs and outputs of this view class to the Catalyst log (as $c->log->debug(...) messages).

WHY

If you need to ask, you probably don't need to use this module.

Some people will not need to ask.

AUTHOR

Marty O'Brien, <mob at cpan.org>

BUGS

Please report any bugs or feature requests to bug-catalyst-view-template-php at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Template-PHP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Catalyst::View::Template::PHP

You can also look for information at:

SEE ALSO

PHP (the programming language), PHP (a Perl module to provide a Perl/PHP interface), PHP::Interpreter (another fine Perl/PHP interface, but one that unfortunately doesn't [as of this release] support php v>=5.2), Catalyst::View::PHP (similar to this Catalyst view but uses PHP::Interpreter instead of PHP).

LICENSE AND COPYRIGHT

Copyright 2012-2013 Marty O'Brien.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.