View
126
Download
0
Category
Preview:
Citation preview
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!
https://lxr.php.net
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;dr1. install virtualbox2. install vagrant3. git clone https://github.com/rlerdorf/php7dev.git4. cd php7dev5. vagrant up6. vagrant ssh7. makephp 7
How to Play along
git clone https://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
A word about macros
• Preprocessor directives are lines included in a program that being with the character #, which make them different from a typical source code text. They are invoked by the compiler to process some programs before compilation.• A macro is a fragment of code which has been
given a name. Whenever the name is used, it is replaced by the contents of the macro.
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-MASTER/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 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
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 decimalchar* + 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 https://joind.in/talk/81b87
Questions?
HELP WITH DOCS!http://edit.php.nethttp://wiki.php.net/internals
HELP WITH THE FUTURE
http://gophp7.org/gophp7-ext
Recommended