KPHP FFI - Speaker Deck

Slide 1

Slide 1 text

KPHP FFI Extending KPHP using foreign function interface API KPHP community

Slide 2

Slide 2 text

Before we start... Like & Subscribe

Slide 3

Slide 3 text

KPHP community chat: join today! https://t.me/kphp_chat

Slide 4

Slide 4 text

Why I’m qualiﬁed to give this talk ● I added FFI support to KPHP compiler & runtime ● I created a rogue-like game with it

Slide 5

Slide 5 text

Topics for this talk KPHP FFI SDL Gamedev Rust bindings

Slide 6

Slide 6 text

What is KPHP?

Slide 7

Slide 7 text

What is KPHP? A language with a cool mascot!

Slide 8

Slide 8 text

What is KPHP? *cough*

Slide 9

Slide 9 text

What is KPHP? ● A PHP dialect that is type-safe

Slide 10

Slide 10 text

What is KPHP? ● A PHP dialect that is type-safe ● A compiler that creates executable binaries

Slide 11

Slide 11 text

What is KPHP? ● A PHP dialect that is type-safe ● A compiler that creates executable binaries ● An open source project

Slide 12

Slide 12 text

PHP FFI

Slide 13

Slide 13 text

PHP FFI ● A mechanism to call C functions from PHP

Slide 14

Slide 14 text

PHP FFI ● A mechanism to call C functions from PHP ● It’s similar to LuaJIT FFI and CPython FFI

Slide 15

Slide 15 text

PHP FFI ● A mechanism to call C functions from PHP ● It’s similar to LuaJIT FFI and CPython FFI ● Create PHP-extensions without C code!

Slide 16

Slide 16 text

So... Why do we need FFI?

Slide 17

Slide 17 text

KPHP FFI The advantages of FFI PHP FFI

Slide 18

Slide 18 text

KPHP FFI The advantages of FFI PHP FFI ● Pure PHP bindings for C

Slide 19

Slide 19 text

KPHP FFI The advantages of FFI PHP FFI ● Pure PHP bindings for C ● More portable than C ext

Slide 20

Slide 20 text

KPHP FFI ● The only way to extend KPHP The advantages of FFI PHP FFI ● Pure PHP bindings for C ● More portable than C ext

Slide 21

Slide 21 text

KPHP FFI ● The only way to extend KPHP ● 100% compatible with PHP The advantages of FFI PHP FFI ● Pure PHP bindings for C ● More portable than C ext

Slide 22

Slide 22 text

Write a C library wrapper once, then use it from both PHP and KPHP!

Slide 23

Slide 23 text

Does KPHP support GD?

Slide 24

Slide 24 text

Does KPHP support GD? Yes.

Slide 25

Slide 25 text

Does KPHP support GD? Yes. Use FFI.

Slide 26

Slide 26 text

Simple usage example $gd = FFI::cdef(' typedef struct gdImage gdImage; gdImage *gdImageCreate(int sx, int sy); void gdImageDestroy(gdImage *image); ', 'libgd.so'); $img = $gd->gdImageCreate(32, 32); $gd->gdImageDestroy($img);

Slide 27

Slide 27 text

Simple usage example $gd = FFI::cdef(' typedef struct gdImage gdImage; gdImage *gdImageCreate(int sx, int sy); void gdImageDestroy(gdImage *image); ', 'libgd.so'); FFI::cdef creates a FFI handle from a C string and loads associated shared (dynamic) library

Slide 28

Slide 28 text

Simple usage example $gd = FFI::cdef(' typedef struct gdImage gdImage; gdImage *gdImageCreate(int sx, int sy); void gdImageDestroy(gdImage *image); ', 'libgd.so'); C declarations string (like in a C header ﬁle)

Slide 29

Slide 29 text

Simple usage example $gd = FFI::cdef(' typedef struct gdImage gdImage; gdImage *gdImageCreate(int sx, int sy); void gdImageDestroy(gdImage *image); ', 'libgd.so'); ldconﬁg-compatible name for the library lookup

Slide 30

Slide 30 text

Simple usage example $gd is our FFI library handle; it’s used to access C functions, types, variables and constants (enums, etc). $img = $gd->gdImageCreate(32, 32); $gd->gdImageDestroy($img);

Slide 31

Slide 31 text

FFI::load - load from a separate declarations ﬁle #define FFI_LIB "libgd.so" typedef struct gdImage gdImage; gdImage *gdImageCreate(int sx, int sy); void gdImageDestroy(gdImage *image); $gd = FFI::load(__DIR__ . '/gd.h'); gd.h

Slide 32

Slide 32 text

Request FFI::cdef() Request FFI::cdef() FFI::cdef usage scheme Run time

Slide 33

Slide 33 text

Request FFI::cdef() Request FFI::cdef() FFI::cdef usage scheme Bad! Parsing C declarations for every request Run time

Slide 34

Slide 34 text

Preload FFI::load() Request FFI::scope() Request FFI::scope() FFI::load() + preload usage scheme Run time

Slide 35

Slide 35 text

Preload FFI::load() Request FFI::scope() Request FFI::scope() FFI::load() + preload usage scheme Run time Good! Parsing C declarations only once

Slide 36

Slide 36 text

KPHP load/cdef ● loads shared libs ● fetches symbols ● creates a FFI obj Comparing PHP and KPHP load/cdef PHP load/cdef ● loads shared libs ● fetches symbols ● creates a FFI obj ● parses C decls

Slide 37

Slide 37 text

Slide 38

Slide 38 text

Slide 39

Slide 39 text

FFI scope object #define FFI_SCOPE foo struct Example { const char *s; int16_t i; }; char ffi_func(int16_t x, const char *s); $foo = FFI::scope("foo");

Slide 40

Slide 40 text

FFI scope object #define FFI_SCOPE foo struct Example { const char *s; int16_t i; }; char ffi_func(int16_t x, const char *s); // OK $ex = $scope->new("struct Example");

Slide 41

Slide 41 text

FFI scope object #define FFI_SCOPE foo struct Example { const char *s; int16_t i; }; char ffi_func(int16_t x, const char *s); // OK $scope->ffi_func(10, 'hello');

Slide 42

Slide 42 text

FFI scope object #define FFI_SCOPE foo struct Example { const char *s; int16_t i; }; char ffi_func(int16_t x, const char *s); // ERROR (compile-time) $scope->undefined_func();

Slide 43

Slide 43 text

KPHP C FFI php2c($v) Passing KPHP values as C func args

Slide 44

Slide 44 text

KPHP C FFI c2php($v) Mapping C func result to KPHP value

Slide 45

Slide 45 text

Auto conversions PHP C ● Passing C function argument ● Assigning to C struct/union ﬁeld ● Assigning to a pseudo cdata ﬁeld php2c($v)

Slide 46

Slide 46 text

php2c conversions PHP type C type int (long) int8_t, int16_t, ... float float, double bool bool string(1) char string const char*

Slide 47

Slide 47 text

php2c conversions PHP type C type int (long) int8_t, int16_t, ... float float, double bool bool string(1) char string const char* Only for function arguments, but not struct ﬁeld write

Slide 48

Slide 48 text

php2c conversions PHP type C type CData T FFI::addr(CData) T*

Slide 49

Slide 49 text

Auto conversions C PHP ● Assigning a (non-void) C function result ● Reading C struct/union ﬁeld ● Reading C scalar “cdata” property ● Reading Scope property (enum values, etc) Different conversion rules for call results and ﬁelds! c2php($v)

Slide 50

Slide 50 text

c2php conversions C type PHP type int8_t, int16_t, ... int float, double float bool bool char string(1) const char* string

Slide 51

Slide 51 text

c2php conversions C type PHP type int8_t, int16_t, ... int float, double float bool bool char string(1) const char* string Only for function results, but not for struct ﬁeld read

Slide 52

Slide 52 text

php2c conversions C type PHP type T CData T* CData

Slide 53

Slide 53 text

What is CData?

Slide 54

Slide 54 text

What is CData? Types that can’t be represented as normal PHP types are wrapped into CData classes.

Slide 55

Slide 55 text

CData /** @return ffi_cdata */ function f() { $cdef = FFI::cdef(' #define FFI_SCOPE "example" struct Foo { int x; }; '); return $cdef->new('struct Foo'); }

Slide 56

Slide 56 text

CData /** @return ffi_cdata */ function f() { $cdef = FFI::cdef(' #define FFI_SCOPE "example" struct Foo { int x; }; '); return $cdef->new('struct Foo'); } new(T) returns CData typed object

Slide 57

Slide 57 text

CData /** @return ffi_cdata */ function f() { $cdef = FFI::cdef(' #define FFI_SCOPE "example" struct Foo { int x; }; '); return $cdef->new('struct Foo'); } T is a type from associated FFI scope/cdef

Slide 58

Slide 58 text

CData /** @return ffi_cdata */ function f() { $cdef = FFI::cdef(' #define FFI_SCOPE "example" struct Foo { int x; }; '); return $cdef->new('struct Foo'); } PHP type hint expects both scope and type

Slide 59

Slide 59 text

FFI CData runtime representation FFI\CData template struct FFI_CData { T value; } ffi_cdata

Slide 60

Slide 60 text

Can I do gamedev in KPHP?

Slide 61

Slide 61 text

Can I do gamedev in KPHP? With things like SDL, you can!

Slide 62

Slide 62 text

SDL libraries ● libsdl2 ● libsdl2_image ● libsdl2_mixer ● libsdl2_ttf

Slide 63

Slide 63 text

SDL libraries ● libsdl2 ● libsdl2_image ● libsdl2_mixer ● libsdl2_ttf sdl.h sdl_image.h sdl_mixer.h sdl_ttf.h

Slide 64

Slide 64 text

Part 1: creating GUI window KPHP game with SDL

Slide 65

Slide 65 text

Creating our ﬁrst header ﬁle for libsdl2 #define FFI_SCOPE "sdl" #define FFI_LIB "libSDL2-2.0.so" typedef uint32_t Uint32; typedef struct SDL_Window SDL_Window; SDL_Window *SDL_CreateWindow( const char *title, int x, int y, int w, int h, Uint32 flags); sdl.h

Slide 66

Slide 66 text

Creating our ﬁrst header ﬁle for libsdl2 \FFI::load('sdl.h'); $sdl = \FFI::scope('sdl'); $w = 640; $h = 480; $window = $sdl->SDL_CreateWindow( 'Main', 0, 0, $w, $h, 0); test.php

Slide 67

Slide 67 text

No content

Slide 68

Slide 68 text

No content

Slide 69

Slide 69 text

KPHP game with SDL Part 2: creating event loop

Slide 70

Slide 70 text

Game event loop while (true) { $this->processInputs($sdl); if ($this->exit) { break; } $this->processFrame($sdl); $sdl->delay(1000 / 60); // ~60 fps } Game.php

Slide 71

Slide 71 text

Game event loop while (true) { $this->processInputs($sdl); if ($this->exit) { break; } $this->processFrame($sdl); $sdl->delay(1000 / 60); // ~60 fps } Game.php Reading all incoming input events (key press, signals, etc).

Slide 72

Slide 72 text

Game event loop while (true) { $this->processInputs($sdl); if ($this->exit) { break; } $this->processFrame($sdl); $sdl->delay(1000 / 60); // ~60 fps } Game.php If player pressed “esc” or quit signal is received, exit the event loop.

Slide 73

Slide 73 text

Game event loop while (true) { $this->processInputs($sdl); if ($this->exit) { break; } $this->processFrame($sdl); $sdl->delay(1000 / 60); // ~60 fps } Game.php Execute game logic: handle game frame for all objects (player, enemies, etc).

Slide 74

Slide 74 text

Game event loop while (true) { $this->processInputs($sdl); if ($this->exit) { break; } $this->processFrame($sdl); $sdl->delay(1000 / 60); // ~60 fps } Game.php Wait for the next frame.

Slide 75

Slide 75 text

Event handling $event = $sdl->newEvent(); while ($sdl->pollEvent($event)) { if ($event->type === EventType::QUIT) { $this->exit = true; } elseif ($event->type === EventType::KEYUP) { // handle key up event } // and so on... } Game.php

Slide 76

Slide 76 text

Slide 77

Slide 77 text

Slide 78

Slide 78 text

Adding new SDL functions to our bindings int SDL_PollEvent(SDL_Event *event); void SDL_Delay(Uint32 ms); sdl.h

Slide 79

Slide 79 text

Adding new SDL functions to our bindings int SDL_PollEvent(SDL_Event *event); void SDL_Delay(Uint32 ms); sdl.h What is SDL_Event?

Slide 80

Slide 80 text

Deﬁning SDL_Event typedef union SDL_Event { Uint32 type; SDL_KeyboardEvent key; SDL_QuitEvent quit; // + other members. } SDL_Event; sdl.h

Slide 81

Slide 81 text

Unions When declaring unions, make sure to enumerate all members (variants). Or at least include the biggest member as well as one with the most strict alignment requirements.

Slide 82

Slide 82 text

Deﬁning SDL_Event members typedef struct SDL_KeyboardEvent { Uint32 type; Uint32 timestamp; Uint32 windowID; Uint8 state; Uint8 repeat; Uint8 padding2; Uint8 padding3; SDL_Keysym keysym; } SDL_KeyboardEvent; typedef union SDL_Event { Uint32 type; SDL_KeyboardEvent key; SDL_QuitEvent quit; } SDL_Event; sdl.h

Slide 83

Slide 83 text

Deﬁning SDL_Event members typedef struct SDL_QuitEvent { Uint32 type; Uint32 timestamp; } SDL_QuitEvent; typedef union SDL_Event { Uint32 type; SDL_KeyboardEvent key; SDL_QuitEvent quit; } SDL_Event; sdl.h

Slide 84

Slide 84 text

Creating union objects /** @return ffi_cdata */ public function newEvent() { return $this->sdl->new('union SDL_Event'); } SDL.php Union objects can be created with the same new() method.

Slide 85

Slide 85 text

KPHP game with SDL Part 3: add SFX & music

Slide 86

Slide 86 text

Opening WAV ﬁles OK, Google How to load WAV with SDL?

Slide 87

Slide 87 text

Loading WAV ﬁles with Mix_LoadWAV typedef struct Mix_Chunk Mix_Chunk; Mix_Chunk *Mix_LoadWAV(char *file); sdl_mixer.h

Slide 88

Slide 88 text

Running the game $ make game $ ./bin/game

Slide 89

Slide 89 text

Running the game $ make game $ ./bin/game PHP Warning: sdl_mixer library doesn’t export Mix_LoadWAV symbol.

Slide 90

Slide 90 text

Investigating the issue Let’s open the source code It’s a macro, not a function!

Slide 91

Slide 91 text

Loading WAV ﬁles Mix_Chunk *Mix_LoadWAV(char *file); SDL_RWops *SDL_RWFromFile( const char *file, const char *mode); Mix_Chunk *Mix_LoadWAV_RW( SDL_RWops *src, int freesrc); sdl_mixer.h

Slide 92

Slide 92 text

KPHP game with SDL Part 4: other things… (I can’t cover everything in this talk.)

Slide 93

Slide 93 text

Tiles Atlas textures

Slide 94

Slide 94 text

Animations Atlas textures

Slide 95

Slide 95 text

Atlas texture rendering $texture_pos = $sdl->newRect(); $texture_pos->w = 32; $texture_pos->h = 32; $texture_pos->x = 0; $texture_pos->y = 32 * 3; $sdl->renderCopy( $texture, \FFI::addr($texture_pos), \FFI::addr($pos)); test.php

Slide 96

Slide 96 text

Slide 97

Slide 97 text

Slide 98

Slide 98 text

Slide 99

Slide 99 text

Making the code more readable Wrapper classes class Color { public int $r; public int $g; public int $b; public int $a; } Color.php

Slide 100

Slide 100 text

Making the code more readable /** * @param ffi_cdata $r */ function setDrawColor($r, Color $color): bool { $result = $this->sdl->SDL_SetRenderDrawColor( $renderer, $color->r, $color->g, $color->b, $color->a); return $result === 0; }

Slide 101

Slide 101 text

KPHP game with SDL Part 5: enjoy the result

Slide 102

Slide 102 text

No content

Slide 103

Slide 103 text

Remember the PHP-KPHP compatibility? You can actually run that game in PHP too!

Slide 104

Slide 104 text

KPHP game links ● Game source code ● SDL2 bindings composer package ● KPHP FFI documentation ● Gameplay video

Slide 105

Slide 105 text

How to use cross-lib types?

Slide 106

Slide 106 text

How to use cross-lib types?

Slide 107

Slide 107 text

Cross-library types typedef struct Foo; a.h typedef struct Foo; struct Bar { struct Foo *foo; } b.h

Slide 108

Slide 108 text

Cross-library types typedef struct Foo; a.h typedef struct Foo; struct Bar { struct Foo *foo; } b.h Incompatible types 'struct Foo*' and 'struct Foo*'

Slide 109

Slide 109 text

No content

Slide 110

Slide 110 text

No content

Slide 111

Slide 111 text

Cross-library types: solution 1 void *new_foo(); a.h struct Bar { void *foo; } b.h Use void* and give up on types

Slide 112

Slide 112 text

Cross-library types: solution 2 $foo = $a->new('struct Foo'); $a_ptr = FFI::addr($foo); $b_ptr = $b->cast('struct Foo*', $a_ptr); test.php Use FFI::cast(); Note: using FFI::cast as instance method!

Slide 113

Slide 113 text

Is there a workaround to KPHP FFI limitations?

Slide 114

Slide 114 text

Is there a workaround to KPHP FFI limitations? Consider using a thin C bridge lib.

Slide 115

Slide 115 text

KPHP C lib Bridge lib Bridge lib contains a glue code and simpliﬁed API of a target C lib PHP

Slide 116

Slide 116 text

Using a bridge lib approach 1. Identify the original C lib API problems 2. Come up with a simpler API that is suitable for FFI 3. Use original C lib in your bridge lib 4. Use bridge lib via FFI in your PHP code

Slide 117

Slide 117 text

Can I… call Rust from KPHP?

Slide 118

Slide 118 text

Can I… call Rust from KPHP? You sure can.

Slide 119

Slide 119 text

Deﬁning a simple Rust function #[no_mangle] pub extern "C" fn rust_hello() { println!("hello from Rust!"); } lib.rs

Slide 120

Slide 120 text

Building Rust project as C shared library # name = "ffi_lib" # crate-type = ["cdylib"] $ cargo build # library is located at # target/${build}/lib${name}.so

Slide 121

Slide 121 text

Deﬁning a simple Rust function rust_hello(); test.php

Slide 122

Slide 122 text

Building and running KPHP application $ kphp --enable-ffi --mode cli ./test.php $ ./kphp_out/cli hello from Rust!

Slide 123

Slide 123 text

KPHP FFI Extending KPHP using foreign function interface API KPHP community