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.