The document presents a detailed overview of extending HHVM (HipHop Virtual Machine) with a focus on how to create and compile a simple PHP extension using C++. It covers key concept introductions, code examples for defining and using extensions, debugging techniques, and when to consider writing extensions, as well as resources for further learning. The presentation is aimed at PHP developers interested in integrating HHVM extensions into their workflows.

1. Diving into
HHVM Extensions
James Titcumb
PHPNW Conference 2015

2. James Titcumb
www.jamestitcumb.com
www.roave.com
www.phphants.co.uk
www.phpsouthcoast.co.uk
@asgrim
Who is this guy?

3. First, some background...
source: Microsoft

7. How PHP works
PHP code
OpCache
Execute (VM)
Lexer + Parser
Compiler

8. How HHVM works
PHP code
OpCache
Execute (VM)
Lexer + Parser
Compiler
JIT
Execute (Native)

9. Hack features
● Return/parameter type hints
● ?nullable
● Collections (Vectors, Sets, Maps, etc.)
● Async functions
● Enums
● Generics
● Lambda expressions ==>
● XHP
● more stuff

10. The HHVM codebase

11. The Engine
hphp/parser

12. The Engine
hphp/parser
hphp/compiler

13. The Engine
hphp/parser
hphp/compiler
hphp/hhbbc

14. The Engine
hphp/parser
hphp/compiler
hphp/hhbbc
hphp/hhvm

15. The Engine
hphp/parser
hphp/compiler
hphp/hhbbc
hphp/hhvm
hphp/runtime/vm

16. The Engine
hphp/parser
hphp/compiler
hphp/hhbbc
hphp/hhvm
hphp/runtime/vm
hphp/runtime/vm/jit

17. The Extensions
hphp/runtime/ext

18. The Extensions
hphp/runtime/ext
hphp/system/php

19. Compile HHVM?

20. source: https://xkcd.com/303/

21. My First HHVM Extension™

22. config.cmake
HHVM_EXTENSION(calc ext_calc.cpp)

23. ext_calc.cpp
#include "hphp/runtime/ext/extension.h"
namespace HPHP {
static class CalcExtension : public Extension {
public:
CalcExtension(): Extension("calc") {}
virtual void moduleInit() {}
} s_calc_extension;
HHVM_GET_MODULE(calc);
} // namespace HPHP

24. ext_calc.cpp
#include "hphp/runtime/ext/extension.h"
namespace HPHP {
static class CalcExtension : public Extension {
public:
CalcExtension(): Extension("calc") {}
virtual void moduleInit() {}
} s_calc_extension;
HHVM_GET_MODULE(calc);
} // namespace HPHP

25. ext_calc.cpp
#include "hphp/runtime/ext/extension.h"
namespace HPHP {
static class CalcExtension : public Extension {
public:
CalcExtension(): Extension("calc") {}
virtual void moduleInit() {}
} s_calc_extension;
HHVM_GET_MODULE(calc);
} // namespace HPHP

26. ext_calc.cpp
#include "hphp/runtime/ext/extension.h"
namespace HPHP {
static class CalcExtension : public Extension {
public:
CalcExtension(): Extension("calc") {}
virtual void moduleInit() {}
} s_calc_extension;
HHVM_GET_MODULE(calc);
} // namespace HPHP

27. ext_calc.cpp
#include "hphp/runtime/ext/extension.h"
namespace HPHP {
static class CalcExtension : public Extension {
public:
CalcExtension(): Extension("calc") {}
virtual void moduleInit() {}
} s_calc_extension;
HHVM_GET_MODULE(calc);
} // namespace HPHP

28. … that’s it.
<?php
var_dump(extension_loaded('calc'));
test.php

29. Compile it.
(waaaat?!)

30. Compile & run the test
#!/bin/bash
hphpize
cmake . && make
/usr/bin/hhvm
-d extension_dir=.
-d hhvm.extensions[]=calc.so
test.php

31. Compile & run the test
$ ./build.sh
bool(true)
$

32. Hack it!

33. source: http://goo.gl/kUAxBI

34. config.cmake
HHVM_EXTENSION(calc ext_calc.cpp)
HHVM_SYSTEMLIB(calc ext_calc.php)

35. ext_calc.cpp
#include "hphp/runtime/ext/extension.h"
namespace HPHP {
static class CalcExtension : public Extension {
public:
CalcExtension(): Extension("calc") {}
virtual void moduleInit() {
loadSystemlib();
}
} s_calc_extension;
HHVM_GET_MODULE(calc);
} // namespace HPHP

36. ext_calc.php
<?hh
function calc_sub(int $a, int $b): int {
return $a - $b;
}

37. … that’s it.
<?php
var_dump(extension_loaded('calc'));
var_dump(calc_sub(5, 3));
test.php

38. Compile & run the test
$ ./build.sh
bool(true)
int(2)
$

39. Sprinkle some C++ in
for good measure

40. ext_calc.cpp
// ... SNIP ...
virtual void moduleInit() {
HHVM_FE(calc_add);
loadSystemlib();
}
// ... SNIP ...

41. ext_calc.cpp
// ... SNIP ...
static int64_t HHVM_FUNCTION(calc_add, int64_t a, int64_t b) {
return a + b;
}
// ... SNIP ...

42. in php extensions...
PHP_FUNCTION(calc_add)
{
// ... SNIP ...
#ifndef FAST_ZPP
if (zend_parse_parameters(ZEND_NUM_ARGS(), "ll", &a, &b) == FAILURE) {
return;
}
#else
ZEND_PARSE_PARAMETERS_START(2, 2)
Z_PARAM_LONG(a)
Z_PARAM_LONG(b)
ZEND_PARSE_PARAMETERS_END();
#endif
// ... SNIP ...

43. ext_calc.php
<?hh
<<__Native>>
function calc_add(int $a, int $b): int;
function calc_sub(int $a, int $b): int {
return $a - $b;
}

44. … that’s it.
<?php
var_dump(extension_loaded('calc'));
var_dump(calc_sub(5, 3));
var_dump(calc_add(5, 3));
test.php

45. Compile & run the test
$ ./build.sh
bool(true)
int(2)
int(8)
$

46. Debugging?!

47. source: http://www.gnu.org/software/gdb/

48. Add debug mode
#!/bin/bash
hphpize
cmake
-DCMAKE_C_FLAGS="-O0 -ggdb3"
-DCMAKE_CXX_FLAGS="-O0 -ggdb3"
-DCMAKE_BUILD_TYPE=Debug
.
make
# ... SNIP ...

49. Run with gdb
$ gdb --args
/usr/bin/hhvm
-d extension_dir=.
-d hhvm.extensions[]=calc.so
test.php
GNU gdb (Ubuntu 7.9-1ubuntu1) 7.9
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.
org/licenses/gpl.html>
--- snip ---
Reading symbols from /usr/bin/hhvm...done.
(gdb)

50. Breakpoints
(gdb) b ext_calc.cpp:6
No source file named ext_calc.cpp.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (ext_calc.cpp:6) pending.
(gdb)

51. Running
(gdb) r
Starting program: /usr/bin/hhvm -d extension_dir=. -d hhvm.extensions[]
=calc.so smoke.php
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
Breakpoint 2, HPHP::f_calc_add (a=5, b=3) at /home/james/workspace/hhvm-
calc/ext_calc.cpp:6
6 return a + b;
(gdb) p a
$1 = 5
(gdb) p b
$2 = 3
(gdb)

52. Handy commands
c continue / step out
n step over
s step into
p x print the value of a variable (x)
set x = y set a variable (x) to value (y)
bt print backtrace
q quit :)

53. When NOT to write extensions

54. When to write extensions

55. BUCKLE UP.

56. source: https://goo.gl/x7Srhe

57. Integrating OpenGL
into an HHVM extension

58. Don’t try this in
production!

59. srsly.

60. Extension
Browser

61. What I did

63. huh?!

64. Make it OOOOOOO

65. ext_foo.php
<?hh
<<__NativeData("Foo")>>
class Foo {
<<__Native>>
public function bar(): int;
}

66. C++ object
!==
PHP object

67. source: http://goo.gl/HORwLQ

68. HHVM Universe
<?php
$o = new Foo();
$o->bar();
PHP Land
class Foo {
public:
Foo() {}
~Foo() {}
int value = 5;
}
Planet C++
int64_t HHVM_METHOD(Foo,bar)
{
auto data =
Native::data<Foo>(this_);
return data->value;
}
Time Vortex!?!?!
C++ object !== PHP object

69. HHVM Universe
<?php
$o = new Foo();
$o->bar();
PHP Land
class Foo {
public:
Foo() {}
~Foo() {}
int value = 5;
}
Planet C++
int64_t HHVM_METHOD(Foo,bar)
{
auto data =
Native::data<Foo>(this_);
return data->value;
}
Time Vortex!?!?!
C++ object !== PHP object

70. HHVM Universe
<?php
$o = new Foo();
$o->bar();
PHP Land
class Foo {
public:
Foo() {}
~Foo() {}
int value = 5;
}
Planet C++
int64_t HHVM_METHOD(Foo,bar)
{
auto data =
Native::data<Foo>(this_);
return data->value;
}
Time Vortex!?!?!
C++ object !== PHP object

71. HHVM Universe
<?php
$o = new Foo();
$o->bar();
PHP Land
class Foo {
public:
Foo() {}
~Foo() {}
int value = 5;
}
Planet C++
int64_t HHVM_METHOD(Foo,bar)
{
auto data =
Native::data<Foo>(this_);
return data->value;
}
Time Vortex!?!?!
C++ object !== PHP object

72. this slide is intentionally left blank

73. ext_foo.php
<?hh
class Foo {
private int $value
public function bar(): int
{
return $this->value;
}
}

74. Demo?

76. source: http://goo.gl/7gWfNz

77. Resources
● OpenGL Tutorial
○ http://www.opengl-tutorial.org/
● HHVM Example Extension
○ https://github.com/hhvm/extension-example
● Sara Golemon - HHVM extension blog series
○ http://blog.golemon.com/2015/01/hhvm-extension-writing-part-iii.html
● Derick Rethans’ extension API cookbook
○ https://github.com/derickr/hhvm-hni-cookbook
● The official API documentation
○ https://github.com/facebook/hhvm/wiki/Extension%20API
● Journey of a Thousand Bytecodes
○ http://hhvm.com/blog/6323/the-journey-of-a-thousand-bytecodes

78. Any questions? :)
https://joind.in/15434
James Titcumb @asgrim