php: Revise README-PHP documentation.

php/README-PHP

@@ -1,13 +1,40 @@
-NOTE: 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.
+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/).
-[Note: On packaged Linux distributions you don't need to do this]
+
+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.
@@ -25,7 +52,8 @@ To create a handle, use guestfs_create() like this:
 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, so:
+convention these return 'false' for errors.  Call guestfs_last_error
+to display the underlying error from libguestfs.  So:
 
   <?php
   //...