Many extension-writing guides focus on simple examples first and ignore the
requirements of more complex implementations until later. Often such guides
must repeat themselves over and over in order to describe these new
features. This section describes extension structure from the perspective of
a mature, practical implementation, in order to prepare users for needs and
issues they will almost always encounter in the process of extension
development.
Files which make up an extension
Whether created by hand, using ext_skel, or by an
alternate extension generator, such as
» CodeGen,
all extensions will have at least four files:
When building an extension as static module into the PHP binary the
build system expects a header file with php_
prepended to the extension name which includes a declaration for a
pointer to the extension's module structure. This file usually contains
additional macros, prototypes, and globals, just like any header.
counter.c
Main extension source file. By convention, the name of this file
is the extension name, but this is not a requirement. This file
contains the module structure declaration, INI entries, management
functions, userspace functions, and other requirements of an extension.
The buildsystem files are discussed elsewhere; this section concentrates on
the rest. These four files make up the bare minimum for an extension, which
may also contain any number of headers, source files, unit tests, and other
support files. The list of files in the counter extension might look like
this:
Example #1 Files in the counter extension, in no particular order
The .cvsignore file is used for extensions which are
checked into one of the PHP CVS repositories (usually
» PECL); the one generated by ext_skel contains:
.deps
*.lo
*.la
These lines tell CVS to ignore interim files generated
by the PHP buildsystem. This is only a convenience, and can be omitted
completely without ill effect.
The CREDITS file lists the contributors and/or
maintainers of the extension in plain text format. The main purpose of
this file is generating the credits information for bundled extensions as
used by phpcredits(). By convention the first line of
the file should hold the name of the extension, the second a comma
separated list of contributors. The contributors are usually ordered by the
chronological order of their contributions. In a » PECL package,
this information is already maintained in package.xml,
for example. This is another file which can be omitted without ill effect.
The package.xml file is specific to » PECL-based
extensions; it is a metainformation file which gives details about an
extension's dependencies, authors, installation requirements, and other
tidbits. In an extension not being hosted in » PECL, this file is
extraneous.