Kotlin Native PHP extension generator

PHP version >= 7.0

Linux

How it works

You describe PHP extension by provided DSL and run make.

Build script do:

1. Compile and run code-generator utility
2. Generate template .c file for PHP extension
3. Generate config.m4 file for autoconf
4. Bind Kotlin function to php functions calls
5. Generate .kt file with declared constants
6. Compile static library from .kt sources
7. Run phpize, configure and make to produce shared PHP library from generated .c file and the resultant Kotlin static library

Scope

Can

1. Functions
2. Supported arguments types: int, float, string, boolean, mixed, array, null, object
3. Optional arguments
4. Extension constants
5. Declare and read INI-entries as String
6. Call Zend C-functions from Kotlin
7. Add logic to MINIT, RINIT, MSHUTDOWN and RSHUTDOWN
8. Define classes with methods, properties and constants

Can't

1. Arguments by reference
2. Resources and callable as arguments or return value

Files

./konfigure/*       Code generator, DSL, zend interop classes
./tests/*           .phpt tests for example extension
Makefile            Makefile
extension.kt        Mandatory. Write your DSL of PHP extension here
lifecycle.kt        Mandatory. Write your lifecycle hooks here
example_double.kt   Example extension functions
example_strings.kt  Example extension functions

Prerequisites

1. Install KOTLINC compiler

2. Install php and php-devel packages

3. Change PHP_HOME and KOTLIN_HOME variables in Makefile

   PHP_HOME must point at home PHP directory, where located ./bin and ./include directories

   KOTLIN_HOME must point at directory, where located kotlinc binary

   example:

   KOTLIN_HOME=/root/kotlin-native-linux-0.7.1/bin
   PHP_HOME=/opt/rh/rh-php71/root/usr
   

Writing extension

Extension consist of two or mode .kt files.

Mandatory one is extension.kt, where you describe your extension with DSL.

All others contains your extension logic.

Let's make example extension with three functions.

First, make file example.kt, that contains realization of those functions.

fun hello(name: String, lang: String?) = "${if (lang ?: "" == "") HELLO_EN else lang} $name!!!\n"

fun helloWorld() = println("Hello $EXAMPLE_WORLD!!!")

fun multiple2(num: Double) = num * 2

NOTE! In current version of KN have a bug with unitialized char *. Because of this, you must handle an empty string instead of null.

First function receive String and return String.

Second function receive String and return nothing (NULL by default).

Third function receive Double and return Double.

Also let's add som constants and INI-setting.

Second, write DSL with description of extension.

import php.extension.dsl.*

val dsl = extension("example", "0.1") {
    ini("example.count","10")

    constant("EXAMPLE_WORLD", "World")
    constant("EXAMPLE_LONG", 10L)

    constant("HELLO_EN", "Hello")
    constant("HELLO_ES", "Hola")
    constant("HELLO_RU", "Привет")

    function("hello", ArgumentType.PHP_STRING) {
        arg(ArgumentType.PHP_STRING, "name")
        arg(ArgumentType.PHP_STRING, "lang", true)
    }

    function("helloWorld")

    function("multiple2", ArgumentType.PHP_DOUBLE) {
        arg(ArgumentType.PHP_DOUBLE, "number")
    }
}

fun main(args: Array<String>) = dsl.make()

NOTE! Your .kt files MUST contains functions with names equals to described by DSL. Also they MUST receive all described arguments of corresponding types in described order.

NOTE! Corresponding K/N constants will generated automatically. Do not declare them in .kt files.

Third, just run make.

If no errors occuried then example.so will be created inside ./modules directory.

If you does not want run phpize, configure and make after generation of C-code, just use parameter make kotlin.

Don't forget to run make test.

DSL description

extension(name, version){
    ini(name, defaultValue)
    ...
    externalIni(name)
    ...
    constant(name, value)
    ...
    function(name [, returnType = NULL]){
        arg(type, name [, isOptional = false])
        ...
    }
    ...
    class(name){
        constant(name, value)
        property(name, value){
            [static()]
            [private() | protected()]
        }
        method(name [, returnType = NULL]){
            arg(type, name [, isOptional = false])
            ...
            [static()]
            [private() | protected()]
            [abstract() | final()]
        }
    }
    ...
}

Types

Hooks

You can provide Kotlin function for following hooks by editing lifecycle.kt file

Reference

Helper classes

High order functions

Additional properties

Class PhpArray

PhpArray implements interface MutableMap<PhpMixed, PhpMixed>. Thus, it contains all the required properties and methods.

Non-standard properties and methods

Class PhpObject