bext-php 0.2.0

Embedded PHP runtime for bext — custom SAPI linking libphp via Rust FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

//! bext PHP SAPI — C bridge between libphp and bext's Rust runtime.
//!
//! Supports classic mode (one script execution per request) and worker mode
//! (boot once, handle requests in a loop via bext_handle_request()).

#ifndef BEXT_PHP_SAPI_H
#define BEXT_PHP_SAPI_H

#include <stddef.h>
#include <stdint.h>

typedef struct bext_request_ctx bext_request_ctx;

// ---------------------------------------------------------------------------
// Callbacks: Rust → C (implemented in ffi.rs, called from C SAPI)
// ---------------------------------------------------------------------------

// I/O callbacks (classic + worker mode)
extern size_t bext_sapi_ub_write(bext_request_ctx *ctx, const char *str, size_t len);
extern size_t bext_sapi_read_post(bext_request_ctx *ctx, char *buf, size_t count);
extern char  *bext_sapi_read_cookies(bext_request_ctx *ctx);
extern void   bext_sapi_on_header(bext_request_ctx *ctx, const char *header, size_t header_len);
extern void   bext_sapi_register_server_variables(bext_request_ctx *ctx, void *track_vars_array);
extern void   bext_sapi_log_message(const char *message, int syslog_type);

// Worker mode callbacks
/// Block until Rust dispatches a request (or signals shutdown).
/// Sets *ctx_out to the new request context.
/// Returns 1 if a request was received, 0 if shutdown.
extern int    bext_sapi_worker_wait_request(bext_request_ctx **ctx_out);
/// Signal that the worker has finished processing a request.
extern void   bext_sapi_worker_finish_request(bext_request_ctx *ctx, int status);

// Worker mode: request info accessors (Rust provides these from RequestCtx)
extern const char *bext_sapi_get_method(bext_request_ctx *ctx);
extern const char *bext_sapi_get_uri(bext_request_ctx *ctx);
extern const char *bext_sapi_get_query_string(bext_request_ctx *ctx);
extern const char *bext_sapi_get_content_type(bext_request_ctx *ctx);
extern int64_t     bext_sapi_get_content_length(bext_request_ctx *ctx);

// ---------------------------------------------------------------------------
// C functions called from Rust
// ---------------------------------------------------------------------------

/// One-time PHP module startup. Returns 0 on success, -1 on failure.
int bext_php_module_init(const char *ini_entries);

/// Shut down the PHP module.
void bext_php_module_shutdown(void);

/// Classic mode: execute a single PHP script. Returns HTTP status code.
int bext_php_execute_script(bext_request_ctx *ctx,
                             const char *script_path,
                             const char *method,
                             const char *uri,
                             const char *query_string,
                             const char *content_type,
                             int64_t content_length);

/// Worker mode: execute a worker script that loops on bext_handle_request().
/// The script boots the framework once and handles requests until shutdown.
/// Returns the exit status (0 = clean, non-zero = error/crash).
int bext_php_execute_worker(bext_request_ctx *initial_ctx,
                             const char *worker_script_path);

/// Register a $_SERVER variable. Call from bext_sapi_register_server_variables.
void bext_php_register_variable(const char *key, const char *val, void *track_vars_array);

/// Register bext PHP functions on the current thread (call after php_request_startup in ZTS).
void bext_php_register_functions(void);

// Shared memory bridge: PHP → JSC rendering
/// Render a component via JSC. Returns a Rust-allocated string (free with bext_sapi_free_string).
extern char *bext_sapi_jsc_render(const char *component, const char *props_json);
/// Free a string returned by bext_sapi_jsc_render.
extern void bext_sapi_free_string(char *ptr);

#endif /* BEXT_PHP_SAPI_H */