PHP bindings.

Note that these are not complete on 32 bit architectures.  PHP doesn't
offer any convenient 64 bit type (on 32 bit).  Therefore you should
always use these PHP bindings on 64 bit.

8 files changed, 265 insertions, 0 deletions

diff --git a/php/Makefile.am b/php/Makefile.am
new file mode 100644
index 00000000..49efcde0
--- /dev/null
+++ b/php/Makefile.am
@@ -0,0 +1,58 @@
+# libguestfs PHP bindings
+# Copyright (C) 2010 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+include $(top_srcdir)/subdir-rules.mk
+
+generator_built = \
+	extension/php_guestfs_php.h \
+	extension/guestfs_php.c
+
+EXTRA_DIST = \
+	$(generator_built) \
+	run-php-tests.sh \
+	extension/guestfs_php_*.phpt \
+	extension/config.m4 \
+	README-PHP \
+	guestfs_php.ini
+
+if HAVE_PHP
+
+phpdir = $(sysconfdir)/php.d
+php_DATA = guestfs_php.ini
+
+# In theory: EXTRA_LIBS="-lguestfs"  In fact this doesn't work
+# and we need to add the library to EXTRA_LDFLAGS.
+all: extension/config.h
+	$(MAKE) -C extension \
+	  EXTRA_INCLUDES="-I$(abs_srcdir)/../src" \
+	  EXTRA_LDFLAGS="-L$(abs_srcdir)/../src/.libs -lguestfs" \
+	  all
+
+extension/config.h: extension/config.m4 ../config.status
+	cd extension && phpize
+	cd extension && ./configure --prefix=$(prefix) --libdir=$(libdir)
+	test -f "$@" && touch -- $@
+
+TESTS = run-php-tests.sh
+
+clean-local:
+	$(MAKE) -C extension clean
+
+install-data-hook:
+	$(MAKE) -C extension INSTALL_ROOT=$(DESTDIR) install
+
+endif
diff --git a/php/README-PHP b/php/README-PHP
new file mode 100644
index 00000000..b5ad3c3a
--- /dev/null
+++ b/php/README-PHP
@@ -0,0 +1,54 @@
+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.
+
+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]
+
+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, 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.
diff --git a/php/extension/config.m4 b/php/extension/config.m4
new file mode 100644
index 00000000..2bac2ea5
--- /dev/null
+++ b/php/extension/config.m4
@@ -0,0 +1,24 @@
+# libguestfs PHP bindings
+# Copyright (C) 2010 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+PHP_ARG_ENABLE(guestfs_php, enable libguestfs PHP bindings,
+               [ --enable-guestfs-php   Enable libguestfs support])
+
+if test "$PHP_GUESTFS_PHP" = "yes"; then
+  AC_DEFINE(HAVE_GUESTFS_PHP, 1, [Whether you have libguestfs PHP bindings])
+  PHP_NEW_EXTENSION(guestfs_php, guestfs_php.c, $ext_shared)
+fi
diff --git a/php/extension/guestfs_php_001.phpt b/php/extension/guestfs_php_001.phpt
new file mode 100644
index 00000000..771592ff
--- /dev/null
+++ b/php/extension/guestfs_php_001.phpt
@@ -0,0 +1,17 @@
+--TEST--
+Load the module and create a handle.
+--FILE--
+<?php
+
+// See comment in php/run-php-tests.sh.
+//putenv ('LIBGUESTFS_DEBUG=1');
+
+$g = guestfs_create ();
+if ($g == false) {
+  echo ("Failed to create guestfs_php handle.\n");
+  exit;
+}
+echo ("Created guestfs_php handle.\n");
+?>
+--EXPECT--
+Created guestfs_php handle.
diff --git a/php/extension/guestfs_php_002.phpt b/php/extension/guestfs_php_002.phpt
new file mode 100644
index 00000000..48ee0b60
--- /dev/null
+++ b/php/extension/guestfs_php_002.phpt
@@ -0,0 +1,36 @@
+--TEST--
+Launch the appliance.
+--FILE--
+<?php
+
+// See comment in php/run-php-tests.sh.
+//putenv ('LIBGUESTFS_DEBUG=1');
+
+$g = guestfs_create ();
+if ($g == false) {
+  echo ("Failed to create guestfs_php handle.\n");
+  exit;
+}
+if (guestfs_add_drive ($g, "/dev/null") == false) {
+  echo ("Error: ".guestfs_last_error ($g)."\n");
+  exit;
+}
+if (guestfs_launch ($g) == false) {
+  echo ("Error: ".guestfs_last_error ($g)."\n");
+  exit;
+}
+$version = guestfs_version ($g);
+if ($version == false) {
+  echo ("Error: ".guestfs_last_error ($g)."\n");
+  exit;
+}
+if (!is_int ($version["major"]) ||
+    !is_int ($version["minor"]) ||
+    !is_int ($version["release"]) ||
+    !is_string ($version["extra"])) {
+  echo ("Error: incorrect return type from guestfs_version\n");
+}
+echo ("OK\n");
+?>
+--EXPECT--
+OK
diff --git a/php/extension/guestfs_php_003.phpt b/php/extension/guestfs_php_003.phpt
new file mode 100644
index 00000000..c4eb5b0a
--- /dev/null
+++ b/php/extension/guestfs_php_003.phpt
@@ -0,0 +1,39 @@
+--TEST--
+Create a disk containing LV and filesystem.
+--FILE--
+<?php
+
+// See comment in php/run-php-tests.sh.
+//putenv ('LIBGUESTFS_DEBUG=1');
+
+$g = guestfs_create ();
+if ($g == false) {
+  die ("Failed to create guestfs_php handle.\n");
+}
+
+$tmp = dirname(__FILE__)."/test.img";
+$size = 100 * 1024 * 1024;
+if (! $fp = fopen ($tmp, 'r+')) {
+  die ("Error: cannot create file '".$tmp."'\n");
+}
+ftruncate ($fp, $size);
+fclose ($fp);
+
+if (! guestfs_add_drive ($g, "test.img") ||
+    ! guestfs_launch ($g) ||
+    ! guestfs_part_disk ($g, "/dev/sda", "mbr") ||
+    ! guestfs_pvcreate ($g, "/dev/sda") ||
+    ! guestfs_vgcreate ($g, "VG", array ("/dev/sda")) ||
+    ! guestfs_lvcreate ($g, "LV", "VG", 64) ||
+    ! guestfs_mkfs ($g, "ext2", "/dev/VG/LV")) {
+  die ("Error: ".guestfs_last_error ($g)."\n");
+}
+echo ("OK\n");
+?>
+--CLEAN--
+<?php
+$tmp = dirname(__FILE__)."/test.img";
+unlink ($tmp);
+?>
+--EXPECT--
+OK
diff --git a/php/guestfs_php.ini b/php/guestfs_php.ini
new file mode 100644
index 00000000..b490a445
--- /dev/null
+++ b/php/guestfs_php.ini
@@ -0,0 +1,2 @@
+; Enable guestfs_php extension module
+extension=guestfs_php.so
diff --git a/php/run-php-tests.sh b/php/run-php-tests.sh
new file mode 100755
index 00000000..38a5e38f
--- /dev/null
+++ b/php/run-php-tests.sh
@@ -0,0 +1,35 @@
+#!/bin/sh -
+# Copyright (C) 2010 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+set -e
+cd extension
+
+TESTS=$(echo guestfs_php_*.phpt)
+echo TESTS: $TESTS
+
+# The PHP test script cleans the environment, so LIBGUESTFS_DEBUG=1
+# won't get passed down to the script.  Furthermore, setting
+# LIBGUESTFS_DEBUG=1 isn't very useful anyway because the PHP test
+# script mixes stdout and stderr together and compares this to the
+# expected output, so you'd just get failures for every test.  So
+# there is no good way to debug libguestfs failures in PHP tests, but
+# if an individual test fails locally then you can edit the
+# guestfs_php_*.phpt and uncomment the putenv statement, then look at
+# the output.
+unset LIBGUESTFS_DEBUG
+
+make test TESTS="$TESTS"