Building Custom PHP Extensions

Building Custom PHP
Extensions

International PHP Conference 2012 Tbilisi, Georgia
Wednesday, December 12, 12

About me

‣ Ioseb Dzmanashvili
‣ Software Architect at AzRy LLC
‣ Teacher at Caucasus School of Technology
‣ V8 JavaScript engine contributor
‣ Author of uri_template PHP extension
‣ Author of Create-Form and Edit-Form link relation
types (being RFCed now).


This talk covers

‣ Setting up development environment
‣ Creating extension skeletons with automated tools
‣ Building and installing extensions
‣ Internals such as:
‣ Implementing and exposing C functions
‣ PHP parameter parsing
‣ Variables

This talk doesn’t cover

‣ Thread safety topics
‣ Networking
‣ Object oriented programming
‣ Stream wrappers
‣ Memory

My Experience

‣ URI Template Pecl extension
‣ https://github.com/ioseb/uri-template
‣ Available from Pecl channel
‣ http://pecl.php.net/package/uri_template
‣ Used by Guzzle HTTP client library and Drupal 8


What it does?

‣ Implementation of RFC6570(URI Template)
‣ Resource Identiﬁer - URI)
100% compatibility with RFC3986 (Uniform

‣ 100% compatibility with RFC3629 (UTF-8)


How to use it?

// URI Template Data
$data = array(
"id" => array("person","albums"),
"token" => "12345",
"fields" => array("id", "name", "picture"),
);

// URI Template
$template = "{/id*}{?fields,token}";

// Transformation
$result = uri_template($template, $data);

//Produces:

/person/albums?fields=id,name,picture&token=12345


Why it is important?

‣ Possibility to achieve outstanding performance
‣ Possibility to learn PHP from inside out


Preparing development
environment


Installing PHP dev package

‣ Linux(Debian)
$ sudo apt-get install php5-dev

‣ Installing with Mac Ports on Mac OS X
$ sudo port install php5-devel

‣ Use XAMPP developer package as an alternative
for Mac OS X (painless solution)


Creating extension

‣ Creating the configuration and build files
‣ Creating the header and basic C files, which includes:
‣ Creating initialization and destruction functions
‣ Including the correct headers
‣ Creating functions for use by PHP info tools
‣ Creating test files

Tools for creating extensions

‣ Create extension manually
‣ Use ext_skel to generate extension
‣ Use pecl-gen to generate extension


Generating extension
with pecl-gen

‣ Install codegen_pecl
$ pear install codegen_pecl

‣ Create XML descriptor for extension
‣ Generate extension skeleton
$ pecl-gen hello-world.xml


XML descriptor (hello-world.xml)

<?xml version="1.0" ?>
<extension name="hello_world" version="0.1.0">
<summary>Yet another hello world PHP Extension</summary>
<description>
This is a sample "hello world" extension
for demonstration purposes only.
</description>
<maintainers>
<maintainer>
<user>ioseb</user>
<name>Ioseb Dzmanashvili</name>
<email>ioseb.dzmanashvili@gmail.com</email>
<role>lead</role>
</maintainer>
</maintainers>
<license>PHP</license>
<function name="hello_world" role="public">
<proto>void hello_world( string input )</proto>
<summary>Prints a hello world message</summary>
<code><![CDATA[ // C code goes here ]]></code>
</function>
</extension>


Generated extension structure
$ tree hello_world
!"" config.m4
!"" config.w32
!"" hello-world.xml
!"" hello_world.c
!"" manual
#   !"" Makefile
#   !"" file-entities.ent
#   !"" functions.xml
#   !"" hello-world
#   #   !"" ...
#   #   !"" functions
#   #   #   $"" hello-world.xml
#   #   !"" ini.xml
#   #   $"" reference.xml
#   $"" manual.xml.in
!"" ...
!"" php_hello_world.h
$"" tests
$"" hello_world.phpt


Generated hello_world() function

PHP_FUNCTION(hello_world)
{
const char * input = NULL;
int input_len = 0;

if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
"s", &input, &input_len) == FAILURE) {
return;
}

do {
// C code goes here
} while (0);
}


Modifying hello_world() function

{
const char * input = NULL;
int input_len = 0;

if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
"s", &input, &input_len) == FAILURE) {
return;
}

// our implementation
php_printf("Hello world %s", input);
}


Installing extension

‣ Prepare build environment for PHP extension
$ phpize

‣ Conﬁgure it
$ ./configure

‣ Compile & Install
$ make && sudo make install

‣ Enable extension
$ php -d extension=hello_world.so -m

Testing hello_world() function

‣ Create test.php ﬁle
‣ Write test code
<?php

echo hello_world("PHP Rocks");

echo "n";

‣ Run script
$ php test.php

‣ If you see following line everything is OK
$ Hello world PHP Rocks

Cleaning extension folder

‣ Get rid off compilation output
$ make clean

‣ Get rid off build environment stuff
$ phpize --clean


PHP_FUNCTION


PHP_FUNCTION expansion

{
// rest of code removed for brevity
}

expands to

void zif_hello_world(
zval *return_value, // 1) variable to store return value
char return_value_used, // 2) if returned value was used
zval *this_ptr TSRMLS_DC // 3) pointer to object's internal state
)


Exposing internal function

function_entry hello_world_functions[] = {

PHP_FE(hello_world, hello_world_arg_info)
{ NULL, NULL, NULL }

};
expands to

function_entry hello_world_functions[] = {
{"hello_world", zif_hello_world, hello_world_arg_info},
{ NULL, NULL, NULL }
};


Parsing Function Parameters

{
const char *input = NULL; // variable to store parameter value
int input_len = 0; // variable to store value length

if (zend_parse_parameters(
ZEND_NUM_ARGS() TSRMLS_CC, // 1) number of arguments
"s", // 2) format string
&input, // 3) address of *input variable
&input_len // 4) address of input_len variable
) == FAILURE) {
return; // just return if something goes wrong
}

// actual implementation
php_printf("Hello world %s", input);
}


Available Parameter Types

Type Speciﬁer C datatype PHP Type
b zend_bool Boolean
l long Integer
d double Floating point
s char*, int String
r zval* Resource
a zval* Array
o zval* Object instance
O zval*, zend_class_entry* Object of a specified type

z zval* Non-specific zval
Z zval** Dereferenced zval

Examples of parameter formats

// means that function expects:
// a) required long parameter
// b) required string parameter
// c) optional long parameter
// d) optional zval of non-specific type
zend_parse_parameters(..., "ls|lz", ...)

// menas that function expects:
// a) required array parameter
// b) required array parameter
// c) required string parameter
// d) optional long parameter
zend_parse_parameters(..., "aas|l", ...)


Zval

_zval_struct {
/* Variable information */
zvalue_value value; /* value */
zend_uint refcount__gc;
zend_uchar type; /* active type */
zend_uchar is_ref__gc;
};

typedef union _zvalue_value {
long lval; /* long value */
double dval; /* double value */
struct {
char *val;
int len;
} str;
HashTable *ht; /* hash table value */
zend_object_value obj;
} zvalue_value;

typedef struct _zval_struct zval;


Zval - Graphical Representation

value

long lval

double dval

str char *val int len

HashTable *ht
zend_object_value obj

refcount__gc
type
is_ref__gc


Internal Data Types

Type Value Access Macros
IS_NULL N/A
IS_BOOL Z_BVAL_P(value)
IS_LONG Z_LVAL_P(value)
IS_DOUBLE Z_DVAL_P(value)
IS_STRING Z_STRVAL_P(value), Z_STRLEN_P(value)
IS_ARRAY Z_ARRVAL_P(value)
IS_OBJECT Z_OBJVAL_P(value)
IS_RESOURCE Z_RESVAL_P(value)

Zval Reader Example
void display_zval(zval *value)
{
switch(Z_TYPE_P(value)) {
case IS_NULL:
php_printf("NULL"); break;
case IS_BOOL:
php_printf("BOOL %d", Z_BVAL_P(value) ? 1 : 0); break;
case IS_LONG:
php_printf("LONG %ld", Z_LVAL_P(value)); break;
case IS_DOUBLE:
php_printf("DOUBLE %f", Z_DVAL_P(value)); break;
case IS_STRING:
php_printf("STRING %s", Z_STRVAL_P(value)); break;
case IS_RESOURCE:
php_printf("RES #%ld", Z_RESVAL_P(value)); break;
case IS_ARRAY:
php_printf("ARRAY"); break;
case IS_OBJECT:
php_printf("OBJECT"); break;
}
}


Returning Values

Type Value Access Macros
ZVAL_NULL(return_value) RETVAL_NULL()

ZVAL_BOOL(return_value) RETVAL_BOOL(bval)

ZVAL_TRUE(return_value) RETVAL_TRUE

ZVAL_FALSE(return_value) RETVAL_FALSE

ZVAL_LONG(return_value, lval) RETVAL_LONG(lval)

ZVAL_DOUBLE(return_value, dval) RETVAL_DOUBLE(dval)

ZVAL_STRING(return_value, str, dup) RETVAL_STRING(str, dup)

ZVAL_RESOURCE(return_value, rval) RETVAL_RESOURCE(rval)


Returning Values

PHP_FUNCTION(test_function)
{
ZVAL_NULL(return_value)
}


Books


Questions?


Thank You!


Building Custom PHP Extensions

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Destacado

Destacado (7)

Similar a Building Custom PHP Extensions

Similar a Building Custom PHP Extensions (20)

Último

Último (20)

Building Custom PHP Extensions