[svn:PHP-Sandwich] rev 1422 - PHP-Sandwich/trunk/lib/PHP

Author: gschlossnagle
Date: Fri Jul 29 14:41:57 2005
New Revision: 1422

Modified:
   PHP-Sandwich/trunk/lib/PHP/Interpreter.pm
Log:
initial perl docs


Modified: PHP-Sandwich/trunk/lib/PHP/Interpreter.pm
==============================================================================
--- PHP-Sandwich/trunk/lib/PHP/Interpreter.pm	(original)
+++ PHP-Sandwich/trunk/lib/PHP/Interpreter.pm	Fri Jul 29 14:41:57 2005
@@ -1,10 +1,46 @@
 package PHP::Interpreter;
 
+=head1 NAME
+
+PHP::Interpreter - An embedded PHP5 interpreter
+
+=head1 VERSION
+
+1.0
+
+=head1 DATE
+
+$LastChangedDate$
+
+=head1 SYNOPSIS
+
+  use PHP::Interpreter;
+  
+  my $p = PHP::Interpreter->new();
+  $p->include("some_php_include.php");
+
+  my $val = $p->somePhpFunc($perlVal);
+
+=head1 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.
+
+=cut
+
+
+
 require DynaLoader;
 
 use strict;
 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);
-$VERSION = "0.9";
+$VERSION = "1.0";
 @ISA = qw(Exporter DynaLoader);
 bootstrap PHP::Interpreter || die "couldn't bootstrap PHP::Interpreter";
 
@@ -24,3 +60,186 @@ sub AUTOLOAD {
 1;
 
 __END__
+
+=head1 METHODS
+
+=head2 Constructor
+
+=over 4
+
+=item 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:
+
+=over 4
+
+=item *
+
+GET - An array ref that will be installed in the PHP $_GET autoglobal array.
+
+=item *
+
+POST - An array ref that will be installed in the PHP $_POST autoglobal array.
+
+=item *
+
+COOKIE - An array ref that will be installed in the PHP $_COOKIE autoglobal array.
+
+=item *
+
+SERVER - An array ref that will be installed in the PHP $_SERVER autoglobal array.
+
+=item *
+
+ENV - An array ref that will be installed in the PHP $_ENV autoglobal array.
+
+=item *
+
+FILES - An array ref that will be installed in the PHP $_FILES autoglobal array.
+
+=item *
+
+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. 
+
+=item *
+
+INCLUDE_PATH - A string that overides PHP's include_path ini setting.
+
+=item *
+
+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.
+
+=back
+
+=head2 Public Class Methods
+
+=head3 eval()
+
+=over
+ 
+=item $php->eval(q^ echo "hello world!\n"; ^);
+
+=item 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.  
+
+B<Throws:>
+
+=over 4
+ 
+=item *
+
+PHP Error in eval
+
+=back 4
+
+=back 
+
+=head3 include()
+
+=over
+
+=item $php->include("somePhpFile.php");
+
+Calls the PHP construct include on the specified file (similar to Perl's 'use').  
+
+B<Throws:>
+
+=over 4
+
+=item * 
+
+Error including (...)
+
+=back 4
+
+=back
+
+=head3 call()
+
+=over
+
+=item $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.
+
+B<Throws:>
+
+=over 4
+
+=item *
+
+A PHP error occured
+
+=back 4
+
+=back
+
+=head3 set_output_hander()
+
+=over
+
+=item my $old_hander = $php->set_output_handler(\$scalar);
+
+=item my $old_hander = $php->set_output_handler(\&func);
+
+
+Set a new output handler, either a scalar reference or a coderef.
+
+=back
+
+=head3 get_output()
+
+=over
+
+=item my $outbuf = $php->get_output();
+
+
+If the output buffer is a scalar reference, this will return it's current contents.
+
+=back
+
+=head3 clear_output()
+
+=over
+
+=item my $outbuf = $php->clear_output();
+
+
+If the output buffer is a scalar reference, this will set it to an empty string.
+
+=back
+
+=head3 instantiate()
+
+=over
+
+=item my $instance = $php->instantiate('stdClass', @args);
+
+
+Create and return an instance of the specified PHP class.  Any additional args are passed to the object''s constructor.
+
+=back
+
+=head3 AUTOLOAD
+
+=over
+
+=item my $retval = $php->strtoupper($string);
+
+An AUTOLOAD function is provided to allow PHP::Interpreter to call arbitrary PHP functions without using call().  Internally, this is identical to 
+
+$php->call('method', @args);
+
+=back