README.md
1# Low-level PHP binding for libvips
2
3This extension lets you use the libvips image processing library from PHP 7. It
4is intentionally very low-level: modules such as
5https://github.com/libvips/php-vips try to layer a nice API on top of this.
6
7libvips is fast and needs little memory. The [`vips-php-bench`](
8https://github.com/jcupitt/php-vips-bench) repository tests
9`php-vips` against `imagick` and `gd`: on that test, and on my laptop,
10`php-vips` is around four times faster than `imagick` and needs 10 times less
11memory.
12
13### Example
14
15```php
16#!/usr/bin/env php
17<?php
18
19$x = vips_image_new_from_file($argv[1])["out"];
20$x = vips_call("invert", $x)["out"];
21vips_image_write_to_file($x, $argv[2]);
22```
23
24Almost all operations return an array of result values. Usually there is a
25single result called `"out"`.
26
27Use `vips_call()` to call any operation in the vips library. There are around
28around 300 operations available, see the vips docs for an introduction:
29
30http://libvips.github.io/libvips/API/current/
31
32Arguments can be long, double, image, array of long, array of double or array
33of image. The final argument to `vips_call()` is an array of operation options.
34
35`php-vips` layers a nice API, including full docs, on top of this extension,
36see:
37
38https://github.com/libvips/php-vips
39
40### Installing
41
42First install the libvips library. It will be in your package manager on linux,
43it's in brew and MacPorts on macOS, or the vips website has Windows binaries.
44
45Next, install this extension:
46
47```
48$ pecl install vips
49```
50
51And add:
52
53```
54extension=vips.so
55```
56
57to your `php.ini`.
58
59Finally, add `vips` to your `composer.json` to pull in the high-level PHP API.
60
61```
62 "require": {
63 "jcupitt/vips" : "1.0.0"
64 }
65```
66
67The high-level API has all the documentation, see:
68
69https://github.com/libvips/php-vips
70
71### Development: preparation
72
73PHP is normally built for speed and is missing a lot of debugging support you
74need for extension development. For testing and dev, build your own php.
75I used 7.0.11 and configured with:
76
77```
78$ ./configure --prefix=/home/john/vips --enable-debug --enable-maintainer-zts \
79 --enable-cgi --enable-cli --with-readline --with-openssl --with-zlib \
80 --with-gd --with-jpeg-dir=/usr --with-libxml-dir=/usr --enable-mbstring
81```
82
83You'll need libvips 8.2 or later, including all the headers for
84development. On linux, install with your package manager. On macOS,
85install with `brew` or MacPorts. For Windows, download a zip from the
86libvips website, or build your own.
87
88### Development: regenerate build system
89
90```
91$ pear package
92```
93
94to make `vips-1.0.9.tgz`.
95
96To install by hand:
97
98```
99$ phpize
100```
101
102To scan `config.m4` and your php install and regenerate the build system.
103
104### Development: configure
105
106Run
107
108```
109$ ./configure
110```
111
112Check the output carefully for errors, and obviously check that it found your
113libvips.
114
115### Development: make, test and install
116
117Run:
118
119```
120$ make
121```
122
123To build the module to the `modules/` directory in this repository.
124
125Don't post php-vips test results to php.net! Stop this with:
126
127```
128$ export NO_INTERACTION=1
129```
130
131Test with:
132
133```
134$ make test
135```
136
137Finally, install to your php extensions area with:
138
139```
140$ make install
141```
142
143Add `extension=vips.so` to `php.ini`, perhaps in `~/vips/lib/php.ini`,
144if you configured php as above.
145
146### Links
147
148http://php.net/manual/en/internals2.php
149
150https://devzone.zend.com/303/extension-writing-part-i-introduction-to-php-and-zend/
151
152https://devzone.zend.com/317/extension-writing-part-ii-parameters-arrays-and-zvals/
153
154https://devzone.zend.com/446/extension-writing-part-iii-resources/
155