KPHP functions extending PHP

Here we list functions, that extend PHP standard library and are available in KPHP natively.

Type system

These are keywords (language constructs), described in the type system article.

Functions for casting instances, described here.

arrays

Since KPHP doesn't support internal array pointers and functions like end(), it's a typed alternative.

Since PHP arrays can be keyed with both integers and strings, array_keys() returns mixed[].

But if you know, that your particular array carries only one type of keys, use these functions with clean types.

Swaps two elements in the array, like tmp = a[idx1]; a[idx1] = a[idx2]; a[idx2] = tmp, but more effeciently, especially for vectors.

Same as $dest = array_merge($dest, $another), but without creating a temporary array.

Find an element in an array with callback.
tuple[0] is corresponding key (null if not exists).
tuple[1] is a found value (empty T if not exists).

Since array_filter() in KPHP doesn't accept ARRAY_FILTER_USE_KEY, it's an alternative.
(as support of ARRAY_FILTER_USE_KEY can't be done without callback argument type spoiling)

Unsets an element by key and returns that (removed) element, per one hashtable lookup.

Returns whether an array is stored internally as a true vector, not a hashtable. It means that it has only successive int keys [0..N] and it was never converted to a map (e.g. at first [1] was set and then [0]: it would be a map). Empty arrays are also vectors.

Reserve array memory — if you know in advance, how many elements will be inserted to it.
Effectife especially for vectors, as there will be no reallocations on insertion.

The same as array_reserve(), but takes all sizes (length, key type, is vector) from array $base.

A KPHP extension of ArrayIterator API. Re-initializes $iter with another array. In KPHP it returns the same ArrayIterator that is ready to be used. In PHP (via polyfills) it returns a newly allocated object.

Async programming

Read about coroutines (forks).

Sends the 103 HTTP header and continues execution. Used from PHP code to push links to CSS/JS so that a client browser starts downloading them until a server still serves the request. No global buffers are modified, header() would still append headers for a regular HTTP answer.

RPC calls

Read about TL schema and RPC calls.

Shared memory (instance cache)

Read about shared memory.

Memory stats

Returns an array ["$var_name" => size_in_bytes]
Don't use it in production — only to debug, which globals/statics allocate huge pieces of memory.
While compiling, a special env variable should be set: KPHP_ENABLE_GLOBAL_VARS_MEMORY_STATS=1

Returns currently used and dirty memory (in bytes).

Returns heap memory usage (system heap, not script allocator) (in bytes).

Returns a hashmap with lots of internal memory info: ['memory_used'=>N, 'defragmentation_calls'=>M, ...].

Returns a tuple of (num_allocations, memory_allocated). The benefit of this function is that it can be used to measure allocations between two execution points: how many allocations happened and how much memory we allocated. Since it returns a tuple instead of array, it doesn't do any heap allocations on its own.

Returns an approximate amount of bytes used to store a variable. Use this for logging static class fields and global variables (probably used as key-value caches at script executions) to measure how huge they actually are at runtime.

Serialization to binary format

Read about serialization and msgpack.

Profiling

Read about embedded profiler.

FFI

Read about FFI.

Misc

Same as PHP trigger_error($str, E_USER_WARNING); (KPHP doesn't have a trigger_error() function).

Useful for dev purposes: this callback is invoked when a runtime warning occurs.
It can be shown on screen for the developer, for example.
Do not use it in production! Use json log analyzer and trace C++ → PHP mapper instead.
$callback is invoked with 2 arguments: 1) $message: warning text; 2) $stacktrace: function names demangled from cpp trace, even without debug symbols — but slow, only for dev

Like register_kphp_on_warning_callback(), but it is not linked to any runtime error: instead, it allows getting current demangled backtrace at the execution point.
Note! Demangling works slowly, don't use it in high-loaded places!

Defines a context for runtime warnings (to be written to json error logs).
$tags — key-value tags (treated like an aggregate)
$extra_info — key-value extra arbitrary data (not an aggregator)
$env — environment (e.g.: staging / production)

When enabled, KPHP won't output an error into json logs in case of script timeout.

Special intrinsic to wrap conditions inside if, like if (likely($x > 10)) — when you suppose that condition is much likely to happen than not (unlikely() is vice versa).
This can slightly pre-warm the CPU branch predictor.