mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-21 22:53:37 +00:00
83 lines
2.5 KiB
Plaintext
83 lines
2.5 KiB
Plaintext
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.
|