feat(ffi): allow definging additional bindings

Add environment variable `EXT_PHP_RS_ALLOWED_BINDINGS` to specify bindings that should be
included in addition to `allowed_bindings.rs`.

Refs: #403

Author: Xenira

build.rs

@@ -209,6 +209,16 @@ fn generate_bindings(defines: &[(&str, &str)], includes: &[PathBuf]) -> Result<S
             .allowlist_var(binding);
     }
 
+    let extension_allowed_bindings = env::var("EXT_PHP_RS_ALLOWED_BINDINGS").ok();
+    if let Some(extension_allowed_bindings) = extension_allowed_bindings {
+        for binding in extension_allowed_bindings.split(',') {
+            bindgen = bindgen
+                .allowlist_function(binding)
+                .allowlist_type(binding)
+                .allowlist_var(binding);
+        }
+    }
+
     let bindings = bindgen
         .generate()
         .map_err(|_| anyhow!("Unable to generate bindings for PHP"))?
@@ -286,7 +296,7 @@ fn main() -> Result<()> {
     ] {
         println!("cargo:rerun-if-changed={}", path.to_string_lossy());
     }
-    for env_var in ["PHP", "PHP_CONFIG", "PATH"] {
+    for env_var in ["PHP", "PHP_CONFIG", "PATH", "EXT_PHP_RS_ALLOWED_BINDINGS"] {
         println!("cargo:rerun-if-env-changed={env_var}");
     }
 

guide/src/SUMMARY.md

@@ -38,6 +38,7 @@
 # Advanced Topics
 
 - [Async](./advanced/async_impl.md)
+- [Allowed Bindings](./advanced/allowed_bindings.md)
 
 # Migration Guides
 ---

guide/src/advanced/allowed_bindings.md

@@ -0,0 +1,27 @@
+# Allowed Bindings
+
+The extension limits the bindings that are generated by `bindgen` to a subset of the original bindings.
+Those bindings are defined in the `allowed_bindings.rs` file.
+
+Should you need to add more bindings, you can do so by defining them as a comma-separated list in the `EXT_PHP_RS_ALLOWED_BINDINGS` environment variable.
+
+This can be configured in your `.cargo/config.toml` file:
+
+```toml
+[env]
+EXT_PHP_RS_ALLOWED_BINDINGS = "php_foo,php_bar"
+```
+
+Your bindings should now appear in the `ext_php_rs::ffi` module.
+
+<div class="warning">
+Pay attention to the PHP version
+
+Be aware, that bindings that do not exist in the PHP version you are targeting will not be available.
+
+Some bindings may also change between PHP versions, so make sure to test your extension with all PHP versions you are targeting.
+</div>
+
+## Contributing
+
+If you think that a binding should be added to the allowed bindings, please open an issue or a pull request on the [GitHub repository](https://github.com/davidcole1340/ext-php-rs) so that everyone can benefit from it.