1# How to create a self-contained PHP extension
2
3A self-contained extension can be distributed independently of the PHP source.
4To create such an extension, two things are required:
5
6* Configuration file (config.m4)
7* Source code for your module
8
9We will describe now how to create these and how to put things together.
10
11## Preparing your system
12
13While the result will run on any system, a developer's setup needs these tools:
14
15* GNU autoconf
16* GNU libtool
17* GNU m4
18
19All of these are available from
20
21    ftp://ftp.gnu.org/pub/gnu/
22
23## Converting an existing extension
24
25Just to show you how easy it is to create a self-contained extension, we will
26convert an embedded extension into a self-contained one. Install PHP and execute
27the following commands.
28
29```bash
30mkdir /tmp/newext
31cd /tmp/newext
32```
33
34You now have an empty directory. We will copy the files from the mysqli
35extension:
36
37```bash
38cp -rp php-src/ext/mysqli/* .
39```
40
41It is time to finish the module. Run:
42
43```bash
44phpize
45```
46
47You can now ship the contents of the directory - the extension can live
48completely on its own.
49
50The user instructions boil down to
51
52```bash
53./configure \
54    [--with-php-config=/path/to/php-config] \
55    [--with-mysqli=MYSQL-DIR]
56make install
57```
58
59The MySQL module will either use the embedded MySQL client library or the MySQL
60installation in MYSQL-DIR.
61
62## Defining the new extension
63
64Our demo extension is called "foobar".
65
66It consists of two source files `foo.c` and `bar.c` (and any arbitrary amount of
67header files, but that is not important here).
68
69The demo extension does not reference any external libraries (that is important,
70because the user does not need to specify anything).
71
72`LTLIBRARY_SOURCES` specifies the names of the sources files. You can name an
73arbitrary number of source files here.
74
75## Creating the M4 configuration file
76
77The m4 configuration can perform additional checks. For a self-contained
78extension, you do not need more than a few macro calls.
79
80```m4
81PHP_ARG_ENABLE([foobar],
82  [whether to enable foobar],
83  [AS_HELP_STRING([--enable-foobar],
84    [Enable foobar])])
85
86if test "$PHP_FOOBAR" != "no"; then
87  PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
88fi
89```
90
91`PHP_ARG_ENABLE` will automatically set the correct variables, so that the
92extension will be enabled by `PHP_NEW_EXTENSION` in shared mode.
93
94The first argument of `PHP_NEW_EXTENSION` describes the name of the extension.
95The second names the source-code files. The third passes `$ext_shared` which is
96set by `PHP_ARG_ENABLE/WITH` to `PHP_NEW_EXTENSION`.
97
98Please use always `PHP_ARG_ENABLE` or `PHP_ARG_WITH`. Even if you do not plan to
99distribute your module with PHP, these facilities allow you to integrate your
100module easily into the main PHP module framework.
101
102## Create source files
103
104`ext_skel.php` can be of great help when creating the common code for all
105modules in PHP for you and also writing basic function definitions and C code
106for handling arguments passed to your functions. See `./ext/ext_skel.php --help`
107for further information.
108
109As for the rest, you are currently alone here. There are a lot of existing
110modules, use a simple module as a starting point and add your own code.
111
112## Creating the self-contained extension
113
114Put `config.m4` and the source files into one directory. Then, run `phpize`
115(this is installed during `make install` by PHP).
116
117For example, if you configured PHP with `--prefix=/php`, you would run
118
119```bash
120/php/bin/phpize
121```
122
123This will automatically copy the necessary build files and create configure from
124your `config.m4`.
125
126And that's it. You now have a self-contained extension.
127
128## Installing a self-contained extension
129
130An extension can be installed by running:
131
132```bash
133./configure \
134    [--with-php-config=/path/to/php-config]
135make install
136```
137
138## Adding shared module support to a module
139
140In order to be useful, a self-contained extension must be loadable as a shared
141module. The following will explain now how you can add shared module support to
142an existing module called `foo`.
143
1441. In `config.m4`, use `PHP_ARG_WITH/PHP_ARG_ENABLE`. Then you will
145   automatically be able to use `--with-foo=shared[,..]` or
146   `--enable-foo=shared[,..]`.
147
1482. In `config.m4`, use `PHP_NEW_EXTENSION(foo,.., $ext_shared)` to enable
149   building the extension.
150
1513. Add the following lines to your C source file:
152
153```c
154#ifdef COMPILE_DL_FOO
155    ZEND_GET_MODULE(foo)
156#endif
157```
158
159## PECL site conformity
160
161If you plan to release an extension to the PECL website, there are several
162points to be regarded.
163
1641. Add `LICENSE` or `COPYING` to the `package.xml`
165
1662. The following should be defined in one of the extension header files
167
168```c
169#define PHP_FOO_VERSION "1.2.3"
170```
171
172This macro has to be used within your foo_module_entry to indicate the
173extension version.
174