Writing extensions for PHP

1. PHP EXTENSIONS
Making the language even better

2. Congratulations!
• You’ve decided to learn “down the stack”
• You’ll learn more than you do “across the stack”
• Your brain will hurt a bit
• This will require you to be involved in your own
learning process
• It is HARD WORK to be good at anything new

3. WARNING!
The things shown here to apply to PHP 5.4 – PHP 5.x

4. Why do extensions?
• Talk to a C or C++ library
• Modify the way the engine works (zend extensions
usually)
• Make slow parts of code run faster

5. But I want to
change the
engine!
Baby steps, baby steps

6. Wrapper
Extension
Speed and/or
Algorithm
Extension
Zend
Extension
SAPI
Engine - Lexer,
AST, Parser

7. But I don’t know C!
1. compiled
2. strictly typed
3. php internals do “hard” stuff
4. copy and paste! boilerplate and macros
5. cairo, pecl_http, date
6. Don’t do the hard stuff first!
lxr.php.net

8. But I want to learn C

9. Also try:
• http://www.learn-c.org/
• http://c.learncodethehardway.org/book/
• http://aelinik.free.fr/c/
Practice Practice Practice!

10. Preparing to
Compile
The big list

11. Quick Setup Needs
1. compiler
2. sdk
3. tools
4. dependencies
5. code
phpize is your friend!

12. How to Compile an Extension
1. phpize
2. ./configure
3. make
4. make install
5. make test
configure might require –with-php-config=/path/to/something
but…

13. But wait – there’s more!
• Compile your own PHP source, use a –prefix
 /usr/local/php-5.6-debug-zts is one I use
 I also have 20 php’s installed 
• We want developer specific flags
 --enable-maintainer-zts and --enable-debug
 optionally –enable-gcov
• install gdb and valgrind and optionally lcov
• this is easy on Ubuntu and similar systems where
packages are easy to get
• You can also compile php with clang instead of gcc
and do things like use static analysis

14. Rasmus to the Rescue!
• https://github.com/rlerdorf/php7dev/blob/master/README.md
tl;dr
1. install virtualbox
2. install vagrant
3. git clone https://github.com/rlerdorf/php7dev.git
4. cd php7dev
5. vagrant up
6. vagrant ssh
7. sudo newphp 56 debug zts

15. How to Play along
git clone https://github.com/auroraeosrose/php-extensions-
code.git
git clone git://github.com/auroraeosrose/php-
extensions-code.git
git checkout scaffolding
bookmark lxr.php.net – you will be using it a lot
phpize
./configure
make
make test

16. Let’s write an
extension!
But wait – there’s more….

17. 1. Set up compile environment
2. Write a module definition
3. Learn about the PHP lifecycle
4. Learn about zvals
5. Add functions
6. ???
7. Profit!
Every Other Extensions Talk

18. DOIN IT RONG

19. Which do YOU want?

20. 1. Do something you can’t do in userland
2. Utilize a C library
3. Make slow code faster
Maybe you should just use ffi!
Step 1. Why?

21. What is FFI?
• Foreign function interface
• Java calls it JNI
• HHVM calls it HNI
• Python calls it “ctypes” (do not ask, stupidest name
ever)
• C# calls it P/Invoke
• Ruby calls it FFI
• PHP calls it…

22. FFI

23. Oh wait…
• php’s ffi is rather broken (last release is 2004-01-20)
• php’s ffi has no maintainer (ilia and wez were doing
it)
• It needs some TLC
• Are you interested and not afraid? See me!

24. 1. I hate parsing URIs
2. PHP’s parse_url is… not the best
3. How about an extension that wraps something
that parses uris in an excellent fashion
4. RESEARCH TIME
Step 2. What

25. Google says…

26. C library to the rescue!
• uriparser.sourceforge.net
• strictly RFC 3986 compliant
• available on many systems as packages
• cross platform
• documented
http://uriparser.sourceforge.net/doc/html/

27. 1. Think about what the API should be
2. Look at the C APIs but don’t mimic them
3. Write an example of how you WANT it to work
4. Write more then one example!
5. Turn these examples into your first tests
6. Yes this is TDD
Step 3. How

29. 1. This is copy and paste
1. config.m4 & config.w32
2. macros for version api changes if necessary
3. main module file (php_{$ext}.c)
4. main header file (php_{$ext}.h)
2. Compile it and test!
Step 6. Extension Scaffolding

30. Configure files

31. Module struct

32. Scaffolding rules
1. make sure you name your files in a standard way
2. document! use a license header, proto statements
3. read the coding standards
http://lxr.php.net/xref/PHP_5_6/CODING_STANDA
RDS
4. FOLLOW THE CODING STANDARDS
5. use version control early on – github is easy!

33. php –d extension=myext.so –m
The scaffold extension should show up in the list
Make sure to
1. define a version constant
2. read and use PHP code standards
Check if it works

34. 1. run-test.php
2. make test will magically have output
more at http://qa.php.net/write-test.php and docs
at http://qa.php.net/phpt_details.php
Step 7. Write the test

35. PHPT tests

36. Let’s take a break here for
some semi-live demos…

37. Zval
The guts behind PHP’s type system

38. Typing systems compared
Static Typing (C)
• Variables must be declared
before use
• Variables must be given a
type at declaration
• “compile time” checking
Dynamic Typing (PHP)
• Variables don’t have to be
declared before use
• Variables can change types
• “run time” checking

39. zval

40. long any numeric
double numeric with decimal
char* + int
(length) strings, binary
Hashtable dictionaries, arrays,structs
object any complicated type

41. How do I get C types from a ZVAL?
Z_LVAL(zval) Z_LVAL_P(zval_p) Z_LVAL_PP(zval_pp)
Z_BVAL(zval) Z_BVAL_P(zval_p) Z_BVAL_PP(zval_pp)
Z_DVAL(zval) Z_DVAL_P(zval_p) Z_DVAL_PP(zval_pp)
Z_STRVAL(zval) Z_STRVAL_P(zval_p) Z_STRVAL_PP(zval_pp)
Z_STRLEN(zval) Z_STRLEN_P(zval_p) Z_STRLEN_PP(zval_pp)
Z_ARRVAL(zval) Z_ARRVAL_P(zval_p) Z_ARRVAL_PP(zval_pp)
Z_OBJVAL(zval) Z_OBJVAL_P(zval_p) Z_OBJVAL_PP(zval_pp)
Z_OBJ_HANDLE(zv
al)
Z_OBJ_HANDLE_P(zval
_p)
Z_OBJ_HANDLE_PP(zval_
pp)
Z_OBJ_HT(zval) Z_OBJ_HT_P(zval_p) Z_OBJ_HT_PP(zval_pp)
Z_OBJCE(zval) Z_OBJCE_P(zval_p) Z_OBJCE_PP(zval_pp)
Z_OBJPROP(zval) Z_OBJPROP_P(zval_p) Z_OBJPROP_PP(zval_pp)
Z_TYPE(zval) Z_TYPE_P(zval_p) Z_TYPE_PP(zval_pp)

42. My extension
does nothing!
Back to our regularly schedule content

43. 1. tell it to link to our C library
2. add a function
3. learn how to get data
4. learn how to return data
Step 8. Actually do something

44. I hate autotools…
• Also known as the gnu build system
• provider of much pain, but much good use as well
• autoconf – generates a configure script (we cheat
with phpize on shared extensions)
 makes a configure we run to set up our information,
mainly a config.h file
• automake – creates makefiles
• libtool – creates static and dynamic libraries
• Windows? Well php wrote it’s own version of
autotools – in jscript (windows javascript variant)

45. Anatomy of a Function

46. Wait – what was that?
• Define your function in C
 use a special call to parse parameters passed by the
user
 use a special zval to return data to the user
• Tell PHP your extension provides this function
 put it in your “giant struct of doom” that lists them all
 send it to php when in your module struct
• Tell PHP what arguments your extension provides
 If your argument information and zpp argue users will be
angry
 Yes it sucks you can’t just do one 

47. php type code
c type
array or object a zval *
boolean b zend_bool
class C zend_class_entry *
double d double
callable f zend_fcall_info andzend_fcall_info_cache
array or HASH_OF(object) H HashTable*
array h HashTable*
integer l long (NOT INT)
integer L long with LONG_MAX, LONG_MIN limits
object o zval *
object of specific type O zval *, zend_class_entry
string (no null bytes) p char*, int
resource r zval *
string (possible null bytes) s char*, int
actual zval z zval *
actual zval Z zval**

48. zend_parse_parameters
type code
variable args (any) * int, zval***
variable args (1 or more) + int, zval***
| anything after is optional, use defaults
/ use SEPARATE_ZVAL_IF_NOT_REF
doesn’t apply to b, l, and d ! C NULL for zval null

49. return_value
RETURN_RESOURCE(l)
RETURN_BOOL(b)
RETURN_NULL()
RETURN_LONG(l)
RETURN_DOUBLE(d)
RETURN_STRING(s, duplicate)
RETURN_STRINGL(s, l, duplicate)
RETURN_EMPTY_STRING()
RETURN_ZVAL(zv, copy, dtor)
RETURN_FALSE
RETURN_TRUE
RETVAL_RESOURCE(l)
RETVAL_BOOL(b)
RETVAL_NULL()
RETVAL_LONG(l)
RETVAL_DOUBLE(d)
RETVAL_STRING(s, duplicate)
RETVAL_STRINGL(s, l, duplicate)
RETVAL_EMPTY_STRING()
RETVAL_ZVAL(zv, copy, dtor)
RETVAL_FALSE
RETVAL_TRUE

50. Complex Data
array_init()
add_(index|assoc)_long()
add_(index|assoc)_bool()
add_(index|assoc)_string()
object_init()
add_property_long()
add_property_bool()
add_property_string()

51. Now to visit the attach-library
branch…

52. 1. namespaces
2. classes
3. methods
4. constants
Step 9. Make it shiny

53. Classes
1. name, parent, and flags
2. hashtables of methods, default methods, static
methods
3. hashtables of static properties, default
properties, and properties
4. object handlers
5. union of either file information, or internal
structures (for internal classes)

56. add-basic-class branch

57. Lifecycle
Let’s take a moment to learn about how PHP works
internally

58. Lifecycle
PHP stops
MSHUTDOWN – for each extension
RSHUTDOWN – for each request
cleanup after test.php
RINIT – for each request
execute test.php
MINIT – for each extension
request/parse test.php
PHP starts
php test.php

59. Lifecycle Threaded
PHP stops
MSHUTDOWN – for each extension
request index.php request foo.php
RINIT – for each request
• execute test.php
RSHUTDOWN – for each request
• cleanup after test.php
RINIT – for each request
• execute test.php
RSHUTDOWN – for each request
• cleanup after test.php
MINIT – for each extension
apache starts

60. Class Properties

61. add-class-properties branch

62. Class Constants

63. add-class-constants branch

64. My class does
nothing!
Methods are where it’s at

65. Class Methods

66. add-class-methods branch

67. Alter $this

68. manipulate this branch

69. Abstract, Interface, Trait
Class Method
ZEND_ACC_IMPLICIT_ABSTRACT_CLA
SS
ZEND_ACC_STATIC
ZEND_ACC_EXPLICIT_ABSTRACT_CLA
SS
ZEND_ACC_ABSTRACT
ZEND_ACC_FINAL_CLASS ZEND_ACC_FINAL
ZEND_ACC_INTERFACE ZEND_ACC_PUBLIC
ZEND_ACC_TRAIT ZEND_ACC_PROTECTED
ZEND_ACC_PRIVATE
ZEND_ACC_CTOR
ZEND_ACC_DTOR
ZEND_ACC_CLONE
spl_ce_FilterIterator->ce_flags |=
ZEND_ACC_EXPLICIT_ABSTRACT_CLASS;
PHP_ME(DateTime, __construct, arginfo_date_create,
ZEND_ACC_CTOR|ZEND_ACC_PUBLIC)

70. 1. globals
2. memory management
3. custom objects
4. object handlers
5. thread safety
Step 10: Advanced topics

71. 1. in your header – use
ZEND_BEGIN|END_MODULE_GLOBALS
2. create the global access macro in your header
(copy and paste)
3. ZEND_DECLARE_MODULE_GLOBALS in
every file where you will use them
4. use the macro to access
COUNTER_G(basic_counter_value)); }
5. Create ginit/gshutdown functions if your globals
need initializing , etc
Global Variables (threads = evil)

72. emalloc( )
• allocates the specified number of bytes
safe_emalloc()
• like emalloc but adds a special protection against overflows
efree( )
• releases the specified block of memory back to the system
estrdup( )
• allocate a buffer and copy the string into that buffer
estrndup( )
• same as estrdup when you already know the length of the string
ecalloc( )
• allocates the number of bytes and initializes them to zero
erealloc( )
• resizes the specified block of memory
https://wiki.php.net/internals/zend_mm

74. 1. clean up what you emalloc (C level destructor)
2. read wiki on how to make them extendable!

75. Object Handlers (black magic)
https://wiki.php.net/internals/engine/objects

76. TSRM
thread safe resource manager
ZTS
zend thread safety
• tsrm_lsTSRMLS_C
• void ***tsrm_lsTSRMLS_D
• , tsrm_lsTSRMLS_CC
• , void ***tsrm_lsTSRMLS_DC

77. 1. http://edit.php.net
2. http://svn.php.net/viewvc/phpdoc/en/trunk/reference/
3. PhD is awesomesauce
• http://doc.php.net/phd/
4. email pecl-dev@lists.php.net
1. who you are
2. what you wrote (with links to your code!)
3. why you think it should be in pecl
5. poke me (or other devs)
Document, PECL, release

78. Stuff I didn’t talk about
1. resources (use custom objects instead)
2. ini entries (just DON’T)
3. threading and parallel processing
4. engine hooking
5. streams and transports

79. PHP 7 is coming!
gophp7-ext and php extension ecosystems

80. About Me
 http://emsmith.net
 auroraeosrose@gmail.com
 twitter - @auroraeosrose
 IRC – freenode – auroraeosrose
 #phpmentoring
 #gophp7-ext

81. Questions?
HELP WITH DOCS!
http://edit.php.net
http://wiki.php.net/internals
HELP WITH THE FUTURE
http://gophp7.org/gophp7-ext