NAME
PHP::Interpreter - An embedded PHP5 interpreter
SYNOPSIS
use PHP::Interpreter;
my $p = PHP::Interpreter->new();
$p->include("some_php_include.php");
my $val = $p->somePhpFunc($perlVal);DESCRIPTION
This class encapsulates an embedded PHP5 intepreter. It provides proxy methods (via AUTOLOAD) to all the functions declared in the PHP interpreter, transparent conversion of Perl datatypes to PHP (and vice-versa), and the ability for PHP to similarly call Perl subroutines and access the Perl symbol table.
The goal of this package is to construct a transaparent bridge for running PHP code and Perl code side-by-side.
INTERFACE
Constructor
new
my $php = PHP::Interpreter->new( $init );Instantiates a PHP::Interpreter object, and creates an associated PHP interpreter instance. An anonymous hash of initial values may be passed. The supported initial value keys are:
GET
An array ref that will be installed in the PHP $_GET autoglobal array.
POST
An array ref that will be installed in the PHP $_POST autoglobal array.
COOKIE
An array ref that will be installed in the PHP $_COOKIE autoglobal array.
SERVER
An array ref that will be installed in the PHP $_SERVER autoglobal array.
ENV
An array ref that will be installed in the PHP $_ENV autoglobal array.
FILES
An array ref that will be installed in the PHP $_FILES autoglobal array.
OUTPUT
Change the output handler. By default, any data sent to STDOUT in PHP will be redirected to STDOUT in Perl. If OUTPUT is a scalar reference, then instead output will be appended to that scalar reference. If OUTPUT is a coderef, then whenever PHP emits data, that coderef will be called with the output fragment as its argument.
INCLUDE_PATH
A string that overides PHP's include_path ini setting.
Any other data that is passed will be installed in the PHP global symbol table. So for instance if you set:
$php = PHP::Interpreter( BRIC => { element => $e, session => $s } );Then PHP will create the globally scoped $BRIC array with the keys 'element' and 'session', pointing at the appropriately converted or wrapped Perl variables $e and $s.
Instance Methods
eval()
$php->eval(q^ echo "hello world!\n"; ^);
my $rv = $php->eval("return file_get_contents($some_url);");Executes the PHP code passed to it, returning any value returned from the script, or true. Throw an exception on failure.
include()
$php->include("somePhpFile.php");Calls the PHP construct include on the specified file (similar to Perl's use keyword). Does not suppress duplicate usages. Throws an exception on failure.
include_once()
$php->include_once("somePhpFile.php");Calls the PHP construct include_once on the specified file (similar to Perl's use keyword). Throws an exception on failure.
is_multithreaded()
if($php->is_multithread) {
# I can instantiate a second independent interpreter
}A runtime check to determine if PHP is thread-safe - i.e. if more than one interpreter can be simultaneously instantiated. If not, further calls to PHP::Interpreter->new() will return the original PHP interpreter instance.
call()
$rv = $php->call(stroupper => $perlVar);Calls the PHP function specified by the first argument, passing the remaining arguments as parameters. Returns the converted return value of the function back into Perl. Throws an exception if an error is encountered.
set_output_handler()
my $old_hander = $php->set_output_handler(\$scalar);
$old_hander = $php->set_output_handler(\&func);Sets a new output handler, either a scalar reference or a coderef.
get_output()
my $outbuf = $php->get_output;If the output buffer is a scalar reference, this method will return its current contents.
clear_output()
my $outbuf = $php->clear_output;If the output buffer is a scalar reference, this method will set it to an empty string.
instantiate()
my $instance = $php->instantiate('stdClass', @args);Creates and returns an instance of the specified PHP class. Any additional arguments are passed to the object's constructor.
AUTOLOAD
my $retval = $php->strtoupper($string);An AUTOLOAD method allows PHP::Interpreter to call arbitrary PHP functions without using call(). Internally, this is identical to
$php->call('method', @args);The AUTOLOAD-generated method will be cached for future calls to the same PHP method.
TYPE HANDLING
In general, the PHP::Interpreter module attempts to make type conversion between Perl and PHP completely transparent. For non-tied, non-magical, and non-objects, this works well. However, when passing these special types, some considerations must be taken into account.
Perl variables passed into PHP
In PHP, magical/blessed values will appear as being of the class PerlSV::$CLASSNAME, as detailed below.
PHP variables passed into Perl
PHP has two types of 'special' variables which do not translate transparently to basic Perl types.
Resources
Resources in PHP will appear in Perl as of the type PHP::Interpreter::Resource. PHP resources have no attributes or bound methods, so this class is just an opaque container.
Objects
Object in PHP will appear in Perl as of the type PHP::Interpreter::Class::$CLASSNAME. These objects will proxy all method calls and attribute accesses through to the internal PHP object.
USING PHP
The PHP interpeter that is instantiated with PHP::Interpreter has some special classes it defines to allow PHP to interface back with its calling PHP Interpreter.
Perl
The PHP Perl class represents the calling Perl intepreter.
Constructor
The Perl class is a singleton class, and has no publc constructor.
getInstance()
<?php
$perl = Perl::getInstance();
?>Returns the valid Perl object instance.
eval()
Executes the passed perl code, returning any return value into PHP.
<?php
$perl = Perl::getInstance();
$perl->eval(q^
for(reverse(1...99)) {
print "$_ bottles of beer on the wall, $_ bottles of beer.\n";
}
^);
?>call()
Call a Perl subroutine, passing optional args and returning the return value into PHP.
<?php
$perl = Perl::getInstance();
$upper = $perl->call('ucfirst', 'hello');
?>This functionality is also available via an AUTOLOAD function described below.
new()
Create a new instance of a perl class.
<?php
$perl = Perl::getInstance();
$file = __FILE__;
$instance = $perl->new('IO::File', "<$file");
?>This will return a PHP object of type 'PerlSV::IO::File' that will proxy all the Perl classes' method calls.
call_method()
Call as static (class) method of a perl class.
<?php
$perl = Perl::getInstance();
$instance = $perl->call_method(
'DBI', 'connect',
array('dbi:SQLite:dbname=file.db, '', '')
);
?>This will effectively call "DBI->connect('dbi:SQLite:dbname=file.db')" and return a PHP object of type 'PerlSV::DBI:db' that will proxy all the Perl classes' method calls.
getVariable()
Access a Perl symbol by name.
<?php
$perl = Perl::getInstance();
$version = $perl->getVariable('$PHP::Interpreter::VERSION');
?>This works only for package variables, not lexical (my) variables.
setVariable()
Set a Perl symbol by name.
<?php
$perl = Perl::getInstance();
$arr = array('banana' => 'yellow' , 'apple' => 'red');
$perl->setVariable('$fruits', $arr);
?>This sets '$main::fruits' to be a hashref of the listed fruits. This works only for package variables, not lexical (my) variables.
Note: PHP functions are not first class objects, so you cannot set coderefs in perl.
AUTOLOAD
The Perl class provides an AUTOLOAD function to automatically call functions.
<?php
$perl = Perl::getInstance();
$upper = $perl->ucfirst('hello');
?>PerlSV
The PerlSV class is the base PHP wrapper class that serves as an opaque container for Perl objects in PHP. It proxies all method calls and attribute accesses. This class uses call and attribute accessor overloading to provide access to the object.
<?php
$perl = Perl::getInstance();
$fh = $perl->new("IO::File", "<$file");
while($fh->getline()) {
# ...
}
?>BUGS
Please send bug reports to <bug-php-interpreter@rt.cpan.org>.
AUTHORS
George Schlossnagle <george@omniti.com>
CREDITS
Development sponsored by Portugal Telecom - SAPO.pt.
COPYRIGHT AND LICENSE
Copyright (c) 2005 Kineticode, Inc. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.