Php extensions

PHP EXTENSIONSMaking the language even better

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

WARNING!The things shown here to apply to PHP 7 only!

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

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

Wrapper Extension

Speed and/or Algorithm Extension

Zend Extension

SAPI

Engine - Lexer, AST,

Parser

But I don’t know C!1. compiled2. strictly typed3. php internals do “hard” stuff4. copy and paste! boilerplate and macros5. cairo, pecl_http, date6. Don’t do the hard stuff first!

lxr.php.nethttps://php-lxr.adamharvey.name/source/

But I want to learn C

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

Practice Practice Practice!

Preparing to CompileThe big list

Quick Setup Needs1. compiler 2. sdk3. tools4. dependencies5. code

phpize is your friend!

How to Compile an Extension1. phpize 2. ./configure3. make4. make install5. make test

configure might require –with-php-config=/path/to/somethingbut…

But wait – there’s more!• Compile your own PHP source, use a –prefix

/usr/local/php-7.0-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

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. makephp 7

How to Play alonggit clone https://github.com/auroraeosrose/php-extensions-code.git

git clone git://github.com/auroraeosrose/php-extensions-code.git git checkout scaffoldingphpize./configuremakemake test

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

1. Set up compile environment2. Write a module definition3. Learn about the PHP lifecycle4. Learn about zvals5. Add functions6. ???7. Profit!

Every Other Extensions Talk

DOIN IT RONG

Which do YOU want?

1. Do something you can’t do in userland2. Utilize a C library3. Make slow code faster

Maybe you should just use ffi!

Step 1. Why?

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…

FFI

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• There’s MFFI but it’s not done

https://github.com/mgdm/MFFI

• Are you interested and not afraid? See me!

1. I hate parsing URIs2. PHP’s parse_url is… not the best3. How about an extension that wraps

something that parses uris in an excellent fashion

4. RESEARCH TIME

Step 2. What

Google says…

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/

1. Think about what the API should be2. Look at the C APIs but don’t mimic them3. Write an example of how you WANT it to

work4. Write more then one example!5. Turn these examples into your first tests6. Yes this is TDD

Step 3. How

1. This is copy and paste1. config.m4 & config.w322. macros for version api changes if

necessary3. main module file (php_{$ext}.c)4. main header file (php_{$ext}.h)

2. Compile it and test!

Step 6. Extension Scaffolding

Configure files

Module struct

Scaffolding rules1. make sure you name your files in a standard

way2. document! use a license header, proto

statements3. read the coding standards

http://lxr.php.net/xref/PHP_5_6/CODING_STANDARDS

4. FOLLOW THE CODING STANDARDS5. use version control early on – github is easy!

php –d extension=myext.so –m

The scaffold extension should show up in the list

Make sure to 1. define a version constant2. read and use PHP code standards

Check if it works

1. run-test.php2. 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

PHPT tests

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

ZvalThe guts behind PHP’s type system

Typing systems comparedStatic 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

zval

zval continued…

For more on the new zvalhttps://nikic.github.io/2015/05/05/Internal-value-representation-in-PHP-7-part-1.html

long any numeric

double numeric with decimal

char* + size_t

(length)strings, binary

Hashtable dictionaries, arrays,structs

object any complicated type

For more on the new string type

http://jpauli.github.io/2015/09/18/php-string-management.html

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_OBJ(zval) Z_OBJ_P(zval_p) Z_OBJVAL_PP(zval_pp)Z_OBJ_HANDLE(zval)

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)

My extension does nothing!Back to our regularly schedule content

1. tell it to link to our C library2. add a function3. learn how to get data4. learn how to return data

Step 8. Actually do something

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)

Anatomy of a Function

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

php type code c typearray or object a zval *boolean b zend_boolclass C zend_class_entry *double d doublecallable f zend_fcall_info

andzend_fcall_info_cachearray or HASH_OF(object) H HashTable*

array h HashTable*integer l zend_longinteger L zend_long with LONG_MAX, LONG_MIN

limitsobject o zval *object of specific type O zval *, zend_class_entrystring (no null bytes) p char*, size_tresource r zval *string (possible null bytes)

s char*, size_t

actual zval z zval *actual zval Z zval**

zend_parse_parameterstype code

variable args (any) * int, zval**

variable args (1 or more) + int, zval**

| anything after is optional, use defaults

/ use SEPARATE_ZVAL_IF_NOT_REFdoesn’t apply to b, l, and d ! C NULL for zval null

return_valueRETURN_RES(l)RETURN_BOOL(b) RETURN_NULL()RETURN_LONG(l)

RETURN_DOUBLE(d) RETURN_STRING(s)RETURN_STRINGL(s, l)RETURN_EMPTY_STRING()RETURN_ZVAL(zv, copy, dtor) RETURN_FALSE RETURN_TRUE

RETVAL_RES(l)RETVAL_BOOL(b) RETVAL_NULL()RETVAL_LONG(l)

RETVAL_DOUBLE(d) RETVAL_STRING(s)RETVAL_STRINGL(s, l)RETVAL_EMPTY_STRING()RETVAL_ZVAL(zv, copy, dtor) RETVAL_FALSE RETVAL_TRUE

Complex Dataarray_init(

)add_(index|assoc)_long()

add_(index|assoc)_bool()

add_(index|assoc)_string()

object_init()

add_property_long()

add_property_bool()

add_property_string()

Now to visit the attach-library branch…

1. namespaces2. classes3. methods4. constants

Step 9. Make it shiny

Classes1. name, parent, and flags2. hashtables of methods, default methods,

static methods3. hashtables of static properties, default

properties, and properties4. object handlers 5. union of either file information, or

internal structures (for internal classes)

add-basic-class branch

LifecycleLet’s take a moment to learn about how PHP works internally

Lifecycle

PHP stops

MSHUTDOWN – for each extension

RSHUTDOWN – for each requestcleanup after test.php

RINIT – for each requestexecute test.php

MINIT – for each extensionrequest/parse test.php

PHP startsphp test.php

Lifecycle Threaded

PHP stops

MSHUTDOWN – for each extension

request index.php request foo.phpRINIT – 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

Class Properties

add-class-properties branch

Class Constants

add-class-constants branch

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

Class Methods

add-class-methods branch

Alter $this

manipulate this branch

Abstract, Interface, TraitClass MethodZEND_ACC_IMPLICIT_ABSTRACT_CLASS

ZEND_ACC_STATIC

ZEND_ACC_EXPLICIT_ABSTRACT_CLASS

ZEND_ACC_ABSTRACT

ZEND_ACC_FINAL_CLASS ZEND_ACC_FINAL ZEND_ACC_INTERFACE ZEND_ACC_PUBLIC ZEND_ACC_TRAIT ZEND_ACC_PROTECTED

ZEND_ACC_PRIVATEZEND_ACC_CTORZEND_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)

1. globals2. memory management3. custom objects4. object handlers5. thread safety

Step 10: Advanced topics

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)

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

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

1. http://edit.php.net 2. http://svn.php.net/viewvc/phpdoc/en/trunk/refere

nce/3. PhD is awesomesauce• http://doc.php.net/phd/

4. email pecl-dev@lists.php.net 1. who you are2. 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

Stuff I didn’t talk about1. resources (use custom objects instead)2. ini entries (just DON’T)3. threading and parallel processing4. engine hooking5. streams and transports6. Complex objects with handlers

About Me http://emsmith.net auroraeosrose@gmail.com twitter - @auroraeosrose IRC – freenode –

auroraeosrose #phpmentoring #gophp7-ext https://joind.in/talk/56f05

Questions?

HELP WITH DOCS!http://edit.php.nethttp://wiki.php.net/internals

HELP WITH THE FUTURE

http://gophp7.org/gophp7-ext