Skeleton PHP extension

Skeleton project for PHP C-extension.

All other PHP extension skeletons that are available, including the one generated by PHP, are too minimalistic for practical use. Use this skeleton instead.

Includes;

• Travis (Linux) and AppVeyor (Windows) configuration for continuous integration / platform tests.
  • Automatic deployment of package to GitHub releases
• CMake config for editing in CLion. (See this article)
• Supported for pecl dependencies.

> Create a new repository, using the skeleton php extension as template.

Requirements

• PHP 7.x or 8.x

Installation

phpize
./configure
make
make test
make install

Add the following line to your php.ini

extension=skeleton.so

To try out the extension, you can run the following command

php -a -d extension=modules/skeleton.so

Functions

skeleton_nop

Return the input (which must be a string).

string skeleton_nop(string input)

Customize

To customize this skeleton for your own extension (e.g. foo_bar), edit the following files;

config.m4 and config.w32

1. Do a search/replace for HAVE_SKELETON, into HAVE_FOO_BAR.

2. Do a search/replace for the word skeleton into foo_bar.

3. If your extension name has name underscore, change the enable argument so it uses a dash.

   PHP_ARG_ENABLE(foo_bar, whether to enable foo_bar, [ --enable-foo-bar   Enable foo_bar])
   

   ARG_ENABLE("foo-bar", "enable foo_bar", "no");
   

php_skeleton.h

1. Rename the file using your extension name php_foo_bar.h.
2. Do a search/replace for PHP_SKELETON_H into PHP_FOO_BAR_H.
3. Do a search/replace for HAVE_SKELETON into HAVE_FOO_BAR.
4. Change the zend_module_entry from skeleton_module_entry to foo_bar_module_entry

skeleton.c

1. Rename the file using your extension name foo_bar.c.
2. Do a search/replace for PHP_SKELETON_H into PHP_FOO_BAR_H.
3. Change PHP_SKELETON_EXTNAME to PHP_FOO_BAR_EXTNAME
4. Change the zend_module_entry from skeleton_module_entry to foo_bar_module_entry
5. In ZEND_GET_MODULE replace skeleton to foo_bar.

.appveyor.yml and .travis.yml

Change skeleton with your extension name for the EXTNAME env var.

env:
  EXTNAME: foo_bar

Deployment

Both Travis and AppVeyor are configured to automatically deploy the generated packages to GitHub releases. In order to do so, you need to specify a GitHub API key.

1. Create a new Personal access token on GitHub via developer settings with the public_repo privilege.
2. For AppVeyor, encrypt the token using the online Encrypt Yaml tool. Replace <your encrypted toke> for the encrypted value in .appveyor.yml.
3. For Travis, install the Travis CLI (gem install travis) and use travis encrypt to encrypt the token. Replace <your encrypted toke> for the encrypted value in .travis.yml.

LICENSE

Update the LICENSE with your (company) name and the year.

You may put your name in CREDITS, but don't add you e-mail address or the build may fail.

Replace example function

Edit the header (php_foo_bar.h) and source (foo_bar.c) file, replace the declaration and implementation of PHP_FUNCTION(skeleton_nop) with your own function(s). Also update zend_function_entry functions and create the argument info for each function.

PECL package

If you wish to publish your extension to pecl.php.net, you need your package to contain a valid package.xml. Create this via

make package.xml

You can enter the release notes manually or pipe it from a source like a git commit

git log -1 --pretty=%B | make package.xml

The version is determined base on the version defined in your main header file. Make sure this is correct prior to running make package.xml.

When package.xml is first created, not all fields are filled out. Edit the file manually to fill this fields and verify it with

pecl package-validate

The make command will automatically update the package content entry and include all source and test files. Other files can be added manually. The script will only remove files that no longer exist.

Getting started with PHP internals

There is a lot of information about the internals and writing PHP extensions online. Unfortunately but this information is often outdated, including the information found in the PHP manual.

• PHP extension sample - Collection of sample features for a php extension
• phpinternals.net - An (accurate but incomplete) reference guide of PHP macros and functions
• PHP source code - If all else fails, look up examples in the PHP source code