Struct ModuleBuilder 

pub struct ModuleBuilder<'a> { /* private fields */ }

Builds a Zend module extension to be registered with PHP. Must be called from within an external function called get_module, returning a mutable pointer to a ModuleEntry.

use ext_php_rs::{
    builders::ModuleBuilder,
    zend::{ModuleEntry, StaticModuleEntry},
    info_table_start, info_table_end, info_table_row
};

#[unsafe(no_mangle)]
pub extern "C" fn php_module_info(_module: *mut ModuleEntry) {
    info_table_start!();
    info_table_row!("column 1", "column 2");
    info_table_end!();
}

#[unsafe(no_mangle)]
pub extern "C" fn get_module() -> *mut ModuleEntry {
    static MODULE: StaticModuleEntry = StaticModuleEntry::new();
    MODULE.get_or_init(|| {
        let (entry, _startup, owned) = ModuleBuilder::new("ext-name", "ext-version")
            .info_function(php_module_info)
            .try_into()
            .unwrap();
        (entry, owned)
    })
}

Implementations

impl ModuleBuilder<'_>

pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self

Creates a new module builder with a given name and version.

Arguments

• name - The name of the extension.
• version - The current version of the extension.

pub fn name(self, name: impl Into<String>) -> Self

Overrides module name.

Arguments

• name - The name of the extension.

pub fn version(self, version: impl Into<String>) -> Self

Overrides module version.

Arguments

• version - The current version of the extension.

pub fn startup_function( self, func: unsafe extern "C" fn(_type: i32, _module_number: i32) -> i32, ) -> Self

Sets the startup function for the extension.

Arguments

• func - The function to be called on startup.

pub fn shutdown_function( self, func: unsafe extern "C" fn(_type: i32, _module_number: i32) -> i32, ) -> Self

Sets the shutdown function for the extension.

Arguments

• func - The function to be called on shutdown.

pub fn request_startup_function( self, func: unsafe extern "C" fn(_type: i32, _module_number: i32) -> i32, ) -> Self

Sets the request startup function for the extension.

Arguments

• func - The function to be called when startup is requested.

pub fn request_shutdown_function( self, func: unsafe extern "C" fn(_type: i32, _module_number: i32) -> i32, ) -> Self

Sets the request shutdown function for the extension.

Arguments

• func - The function to be called when shutdown is requested.

pub fn post_deactivate_function( self, func: unsafe extern "C" fn() -> i32, ) -> Self

Sets the post request shutdown function for the extension.

This function can be useful if you need to do any final cleanup at the very end of a request, after all other resources have been released. For example, if your extension creates any persistent resources that last beyond a single request, you could use this function to clean those up.

Arguments

• func - The function to be called when shutdown is requested.

pub fn info_function( self, func: unsafe extern "C" fn(zend_module: *mut ModuleEntry), ) -> Self

Sets the extension information function for the extension.

Arguments

• func - The function to be called to retrieve the information about the extension.

pub fn globals<T: ModuleGlobal>(self, handle: &'static ModuleGlobals<T>) -> Self

Registers a module globals struct with this extension.

PHP will allocate per-thread storage (ZTS) or use the static’s inline storage (non-ZTS), calling GINIT/GSHUTDOWN callbacks automatically.

Only one globals struct per module is supported (PHP limitation). Calling this a second time will overwrite the previous registration.

Arguments

• handle - A static ModuleGlobals that will hold the globals.

Examples

use ext_php_rs::prelude::*;
use ext_php_rs::zend::{ModuleGlobal, ModuleGlobals};

#[derive(Default)]
struct MyGlobals { counter: i64 }
impl ModuleGlobal for MyGlobals {}

static MY_GLOBALS: ModuleGlobals<MyGlobals> = ModuleGlobals::new();

#[php_module]
pub fn module(module: ModuleBuilder) -> ModuleBuilder {
    module.globals(&MY_GLOBALS)
}

pub fn fcall_observer<F, O>(self, factory: F) -> Self

where F: Fn() -> O + Send + Sync + 'static, O: FcallObserver + Send + Sync,

Available on crate feature observer only.

Registers a function call observer for profiling or tracing.

The factory function is called once globally during MINIT to create a singleton observer instance shared across all requests and threads. The observer must be Send + Sync as it may be accessed concurrently in ZTS builds.

Arguments

• factory - A function that creates an observer instance

Example

use ext_php_rs::prelude::*;
use ext_php_rs::zend::{FcallObserver, FcallInfo, ExecuteData};
use ext_php_rs::types::Zval;

struct MyProfiler;

impl FcallObserver for MyProfiler {
    fn should_observe(&self, info: &FcallInfo) -> bool {
        !info.is_internal
    }
    fn begin(&self, _: &ExecuteData) {}
    fn end(&self, _: &ExecuteData, _: Option<&Zval>) {}
}

#[php_module]
pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
    module.fcall_observer(|| MyProfiler)
}

Panics

Panics if called more than once on the same module.

pub fn error_observer<F, O>(self, factory: F) -> Self

where F: Fn() -> O + Send + Sync + 'static, O: ErrorObserver + Send + Sync,

Available on crate feature observer only.

Registers an error observer for monitoring PHP errors.

The factory function is called once during MINIT to create a singleton observer instance shared across all requests. The observer must be Send + Sync for ZTS builds.

Arguments

• factory - A function that creates an observer instance

Example

use ext_php_rs::prelude::*;

struct MyErrorLogger;

impl ErrorObserver for MyErrorLogger {
    fn should_observe(&self, error_type: ErrorType) -> bool {
        ErrorType::Fatal.contains(error_type)
    }

    fn on_error(&self, error: &ErrorInfo) {
        eprintln!("[{}:{}] {}",
            error.filename.unwrap_or("<unknown>"),
            error.lineno,
            error.message
        );
    }
}

#[php_module]
pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
    module.error_observer(MyErrorLogger)
}

Panics

Panics if called more than once on the same module.

pub fn exception_observer<F, O>(self, factory: F) -> Self

where F: Fn() -> O + Send + Sync + 'static, O: ExceptionObserver + Send + Sync,

Available on crate feature observer only.

Registers an exception observer for monitoring thrown PHP exceptions.

The factory function is called once during MINIT to create a singleton observer instance shared across all requests. The observer must be Send + Sync for ZTS builds.

The observer is called at throw time, before any catch blocks are evaluated.

Arguments

• factory - A function that creates an observer instance

Example

use ext_php_rs::prelude::*;

struct MyExceptionLogger;

impl ExceptionObserver for MyExceptionLogger {
    fn on_exception(&self, exception: &ExceptionInfo) {
        eprintln!("[EXCEPTION] {}: {} at {}:{}",
            exception.class_name,
            exception.message.as_deref().unwrap_or("<no message>"),
            exception.file.as_deref().unwrap_or("<unknown>"),
            exception.line
        );
    }
}

#[php_module]
pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
    module.exception_observer(|| MyExceptionLogger)
}

Panics

Panics if called more than once on the same module.

pub fn function(self, func: FunctionBuilder<'static>) -> Self

Adds a function to the extension.

Arguments

• func - The function to be added to the extension.

pub fn constant( self, const: (&str, impl IntoConst + Send + 'static, DocComments), ) -> Self

Adds a constant to the extension.

Arguments

• const - Tuple containing the name, value and doc comments for the constant. This is a tuple to support the wrap_constant macro.

pub fn interface<T: RegisteredClass>(self) -> Self

Adds a interface to the extension.

Panics

• Panics if a constant could not be registered.

pub fn class<T: RegisteredClass>(self) -> Self

Adds a class to the extension.

Panics

• Panics if a constant could not be registered.

pub fn enumeration<T>(self) -> Self

where T: RegisteredClass + RegisteredEnum,

Available on crate feature enum only.

Adds an enum to the extension.

impl<'a> ModuleBuilder<'a>

pub fn zend_extension<F, H>(self, factory: F) -> ZendExtensionBuilder<'a>

where F: Fn() -> H + Send + Sync + 'static, H: ZendExtensionHandler,

Available on crate feature observer only.

Register a ZendExtensionHandler and configure which hooks PHP should call.

Returns a ZendExtensionBuilder that exposes three opt-in methods (hook_statements, hook_fcalls, hook_op_array_compile). Call ZendExtensionBuilder::finish to return to ModuleBuilder.

Example

module
    .zend_extension(|| MyProfiler::new())
    .hook_statements()
    .finish()

Panics

Panics if called more than once on the same module.

Trait Implementations

impl<'a> Debug for ModuleBuilder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ModuleBuilder<'_>

fn default() -> Self

Returns the “default value” for a type.

impl From<ModuleBuilder<'_>> for Module

Builds a Module from a ModuleBuilder. This is used to generate the PHP stubs for the module.

fn from(builder: ModuleBuilder<'_>) -> Self

Converts to this type from the input type.

impl TryFrom<ModuleBuilder<'_>> for (ModuleEntry, ModuleStartup, ModuleAllocations)

Builds a ModuleEntry and ModuleStartup from a ModuleBuilder. This is the entry point for the module to be registered with PHP.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(builder: ModuleBuilder<'_>) -> Result<Self, Self::Error>

Performs the conversion.