appliance: Ignore unreadable dbus service file (Fedora 15).
[libguestfs.git] / php / README-PHP
1 NOTE: The PHP API is not complete on 32 bit architectures.  PHP
2 doesn't offer any convenient 64 bit type (on 32 bit).  Any 64 bit
3 parameters or return values will be truncated to 32 bits on these
4 platforms.  You should always use these PHP bindings on a 64 bit
5 operating system.
6
7 To install the extension manually, copy guestfs_php.so into the
8 modules directory (eg. /usr/local/lib/php/modules/) and copy
9 guestfs_php.ini into the config directory (eg. /etc/php.d/).
10 [Note: On packaged Linux distributions you don't need to do this]
11
12 The PHP API follows the C API.  Refer to guestfs(3) or
13 http://libguestfs.org/guestfs.3.html for the details of the C API.
14
15 To create a handle, use guestfs_create() like this:
16
17   <?php
18   $g = guestfs_create ();
19   if ($g == false) {
20     echo ("Failed to create guestfs_php handle.\n");
21     exit;
22   }
23   ?>
24
25 Handles are closed implicitly by the PHP dtor.
26
27 All of the usual functions from the C API are available.  By
28 convention these return 'false' for errors, so:
29
30   <?php
31   //...
32   if (guestfs_launch ($g) == false) {
33     echo ("Error: ".guestfs_last_error ($g)."\n");
34     exit;
35   }
36   ?>
37
38 or:
39
40   <?php
41   //...
42   $version = guestfs_version ($g);
43   if ($version == false) {
44     echo ("Error: ".guestfs_last_error ($g)."\n");
45     exit;
46   }
47   echo ("libguestfs version = ".
48         $version["major"].".".$version["minor"].".".$version["release"].
49         $version["extra"]."\n");
50   ?>
51
52 C API structs are mapped to associative arrays.  C API lists of
53 structs are mapped to arrays of associative arrays.  Other C API
54 parameters and return values are mapped to natural PHP types.