README-PHP: Important notes about using libguestfs from PHP
-----------------------------------------------------------

32 bit architectures
--------------------

The PHP API is not complete on 32 bit architectures.  PHP doesn't
offer any convenient 64 bit type (on 32 bit).  Any 64 bit parameters
or return values will be truncated to 32 bits on these platforms.  You
should always use these PHP bindings on a 64 bit operating system.

Installing the extension manually
---------------------------------

[Note: On packaged Linux distributions you don't need to do this]

To install the extension manually, copy guestfs_php.so into the
modules directory (eg. /usr/local/lib/php/modules/) and copy
guestfs_php.ini into the config directory (eg. /etc/php.d/).

Environment variables
---------------------

The environment may not contain the expected variables when running
PHP programs (in general).  For example, $PATH may not be set at all.

This can break libguestfs which expects some environment variables to
be set (see "ENVIRONMENT VARIABLES" in guestfs(3)).  Also if you're
using the libvirt backend, then $PATH needs to be set else libvirt
won't work at all.  You can get around this by setting $PATH (and
maybe other variables) to some safe values at the start of your
program, eg:

 putenv ('PATH=/usr/bin:/bin');

Using the libguestfs API from PHP
---------------------------------

The PHP API follows the C API.  Refer to guestfs(3) or
http://libguestfs.org/guestfs.3.html for the details of the C API.

To create a handle, use guestfs_create() like this:

  <?php
  $g = guestfs_create ();
  if ($g == false) {
    echo ("Failed to create guestfs_php handle.\n");
    exit;
  }
  ?>

Handles are closed implicitly by the PHP dtor.

All of the usual functions from the C API are available.  By
convention these return 'false' for errors.  Call guestfs_last_error
to display the underlying error from libguestfs.  So:

  <?php
  //...
  if (guestfs_launch ($g) == false) {
    echo ("Error: ".guestfs_last_error ($g)."\n");
    exit;
  }
  ?>

or:

  <?php
  //...
  $version = guestfs_version ($g);
  if ($version == false) {
    echo ("Error: ".guestfs_last_error ($g)."\n");
    exit;
  }
  echo ("libguestfs version = ".
        $version["major"].".".$version["minor"].".".$version["release"].
        $version["extra"]."\n");
  ?>

C API structs are mapped to associative arrays.  C API lists of
structs are mapped to arrays of associative arrays.  Other C API
parameters and return values are mapped to natural PHP types.