docs(macro): update documentation for builder pattern

Author: Xenira

README.md

@@ -192,6 +192,8 @@ Contributions welcome include:
 When contributing, please keep in mind the following:
 - Create tests if possible.
 - Update the documentation if necessary.
+  - If your change is a [braking change](https://semver.org) a migration guide MUST be included. This
+    should be placed in the `guide/src/migration-guides` directory.
 - Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). We use these to automatically generate changelogs.
 
 Unless you explicitly state otherwise, any contribution intentionally submitted

build.rs

@@ -1,3 +1,7 @@
+//! The build script for ext-php-rs.
+//! This script is responsible for generating the bindings to the PHP Zend API.
+//! It also checks the PHP version for compatibility with ext-php-rs and sets
+//! configuration flags accordingly.
 #[cfg_attr(windows, path = "windows_build.rs")]
 #[cfg_attr(not(windows), path = "unix_build.rs")]
 mod impl_;
@@ -18,6 +22,7 @@ use impl_::Provider;
 const MIN_PHP_API_VER: u32 = 20200930;
 const MAX_PHP_API_VER: u32 = 20240924;
 
+/// Provides information about the PHP installation.
 pub trait PHPProvider<'a>: Sized {
     /// Create a new PHP provider.
     fn new(info: &'a PHPInfo) -> Result<Self>;
@@ -75,9 +80,11 @@ fn find_php() -> Result<PathBuf> {
     })
 }
 
+/// Output of `php -i`.
 pub struct PHPInfo(String);
 
 impl PHPInfo {
+    /// Get the PHP info.
     pub fn get(php: &Path) -> Result<Self> {
         let cmd = Command::new(php)
             .arg("-i")
@@ -100,25 +107,29 @@ impl PHPInfo {
             .try_into()
     }
 
+    /// Checks if thread safety is enabled.
     pub fn thread_safety(&self) -> Result<bool> {
         Ok(self
             .get_key("Thread Safety")
             .context("Could not find thread safety of PHP")?
             == "enabled")
     }
 
+    /// Checks if PHP was built with debug.
     pub fn debug(&self) -> Result<bool> {
         Ok(self
             .get_key("Debug Build")
             .context("Could not find debug build of PHP")?
             == "yes")
     }
 
+    /// Get the php version.
     pub fn version(&self) -> Result<&str> {
         self.get_key("PHP Version")
             .context("Failed to get PHP version")
     }
 
+    /// Get the zend version.
     pub fn zend_version(&self) -> Result<u32> {
         self.get_key("PHP API")
             .context("Failed to get Zend version")

crates/macros/src/lib.rs

@@ -19,6 +19,9 @@ use syn::{
 
 extern crate proc_macro;
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/classes.md")]
 #[proc_macro_attribute]
 pub fn php_class(args: TokenStream, input: TokenStream) -> TokenStream {
@@ -30,6 +33,9 @@ pub fn php_class(args: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/function.md")]
 #[proc_macro_attribute]
 pub fn php_function(args: TokenStream, input: TokenStream) -> TokenStream {
@@ -41,6 +47,9 @@ pub fn php_function(args: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/constant.md")]
 #[proc_macro_attribute]
 pub fn php_const(_args: TokenStream, input: TokenStream) -> TokenStream {
@@ -49,6 +58,9 @@ pub fn php_const(_args: TokenStream, input: TokenStream) -> TokenStream {
     constant::parser(input).into()
 }
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/module.md")]
 #[proc_macro_attribute]
 pub fn php_module(args: TokenStream, input: TokenStream) -> TokenStream {
@@ -60,6 +72,9 @@ pub fn php_module(args: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/impl.md")]
 #[proc_macro_attribute]
 pub fn php_impl(args: TokenStream, input: TokenStream) -> TokenStream {
@@ -71,6 +86,9 @@ pub fn php_impl(args: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/extern.md")]
 #[proc_macro_attribute]
 pub fn php_extern(_: TokenStream, input: TokenStream) -> TokenStream {
@@ -81,6 +99,9 @@ pub fn php_extern(_: TokenStream, input: TokenStream) -> TokenStream {
         .into()
 }
 
+// Not included in the doc tests, as they depend on `ext-php-rs` being available.
+// The guide tests will cover these macros.
+#[cfg(not(doctest))]
 #[lsp_doc("guide/src/macros/zval_convert.md")]
 #[proc_macro_derive(ZvalConvert)]
 pub fn zval_convert_derive(input: TokenStream) -> TokenStream {
@@ -91,6 +112,7 @@ pub fn zval_convert_derive(input: TokenStream) -> TokenStream {
         .into()
 }
 
+#[cfg(not(doctest))]
 /// Defines an `extern` function with the Zend fastcall convention based on
 /// operating system.
 ///

guide/src/SUMMARY.md

@@ -27,7 +27,6 @@
   - [Async futures](./macros/async_impl.md)
 - [Macros](./macros/index.md)
   - [Module](./macros/module.md)
-  - [Module Startup Function](./macros/module_startup.md)
   - [Function](./macros/function.md)
   - [Classes](./macros/classes.md)
     - [`impl`s](./macros/impl.md)
@@ -37,3 +36,7 @@
   - [`ZvalConvert`](./macros/zval_convert.md)
 - [Exceptions](./exceptions.md)
 - [INI Settings](./ini-settings.md)
+
+# Migration Guides
+---
+[v0.14](./migration-guides/v0.14.md)

guide/src/getting-started/hello_world.md

@@ -57,16 +57,16 @@ Let's actually write the extension code now. We start by importing the
 basic extension. We will then write our basic `hello_world` function, which will
 take a string argument for the callers name, and we will return another string.
 Finally, we write a `get_module` function which is used by PHP to find out about
-your module. The `#[php_module]` attribute automatically registers your new
-function so we don't need to do anything except return the `ModuleBuilder` that
-we were given.
+your module. We must provide the defined function to the given `ModuleBuilder`
+and then return the same object.
 
-We also need to enable the `abi_vectorcall` feature when compiling for Windows.
-This is a nightly-only feature so it is recommended to use the `#[cfg_attr]`
-macro to not enable the feature on other operating systems.
+We also need to enable the `abi_vectorcall` feature when compiling for Windows
+(the first line). This is a nightly-only feature so it is recommended to use
+the `#[cfg_attr]` macro to not enable the feature on other operating systems.
 
-```rust,ignore
+```rust,no_run
 #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
 use ext_php_rs::prelude::*;
 
 #[php_function]
@@ -76,8 +76,9 @@ pub fn hello_world(name: &str) -> String {
 
 #[php_module]
 pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-    module
+    module.function(wrap_function!(hello_world))
 }
+# fn main() {}
 ```
 
 ## Building the extension

guide/src/ini-settings.md

@@ -14,16 +14,22 @@ All PHP INI definitions must be registered with PHP to get / set their values vi
 # use ext_php_rs::zend::IniEntryDef;
 # use ext_php_rs::flags::IniEntryPermission;
 
-#[php_startup]
-pub fn startup_function(ty: i32, module_number: i32) {
+pub fn startup(ty: i32, mod_num: i32) -> i32 {
     let ini_entries: Vec<IniEntryDef> = vec![
         IniEntryDef::new(
             "my_extension.display_emoji".to_owned(),
             "yes".to_owned(),
             IniEntryPermission::All,
         ),
     ];
-    IniEntryDef::register(ini_entries, module_number);
+    IniEntryDef::register(ini_entries, mod_num);
+
+    0
+}
+
+#[php_module(startup = "startup")]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module
 }
 # fn main() {}
 ```
@@ -35,14 +41,22 @@ The INI values are stored as part of the `GlobalExecutor`, and can be accessed v
 ```rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
-# use ext_php_rs::prelude::*;
-# use ext_php_rs::zend::ExecutorGlobals;
+use ext_php_rs::{
+    prelude::*,
+    zend::ExecutorGlobals,
+};
 
-#[php_startup]
-pub fn startup_function(ty: i32, module_number: i32) {
+pub fn startup(ty: i32, mod_num: i32) -> i32 {
     // Get all INI values
     let ini_values = ExecutorGlobals::get().ini_values(); // HashMap<String, Option<String>>
     let my_ini_value = ini_values.get("my_extension.display_emoji"); // Option<Option<String>>
+
+    0
+}
+
+#[php_module(startup = "startup")]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module
 }
 # fn main() {}
 ```

guide/src/introduction.md

@@ -32,6 +32,9 @@ Our main goal is to **make extension development easier.**
 guaranteed while we are at major version `0`, which is for the foreseeable
 future. It's recommended to lock the version at the patch level.
 
+When introducing breaking changes a migration guide will be provided in this
+guide.
+
 ## Documentation
 
 - This guide!

guide/src/macros/classes.md

@@ -16,11 +16,10 @@ There are also additional macros that modify the class. These macros **must** be
 placed underneath the `#[php_class]` attribute.
 
 - `#[extends(ce)]` - Sets the parent class of the class. Can only be used once.
-  `ce` must be a valid Rust expression when it is called inside the
-  `#[php_module]` function.
+  `ce` must be a function with the signature `fn() -> &'static ClassEntry`.
 - `#[implements(ce)]` - Implements the given interface on the class. Can be used
-  multiple times. `ce` must be a valid Rust expression when it is called inside
-  the `#[php_module]` function.
+  multiple times. `ce` must be a valid function with the signature
+  `fn() -> &'static ClassEntry`.
 
 You may also use the `#[prop]` attribute on a struct field to use the field as a
 PHP property. By default, the field will be accessible from PHP publicly with
@@ -67,18 +66,20 @@ This example creates a PHP class `Human`, adding a PHP property `address`.
 ```rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
-# use ext_php_rs::prelude::*;
+use ext_php_rs::prelude::*;
+
 #[php_class]
 pub struct Human {
     name: String,
     age: i32,
     #[prop]
     address: String,
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
+
+#[php_module]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module.class::<Human>()
+}
 # fn main() {}
 ```
 
@@ -88,11 +89,14 @@ it in the `Redis\Exception` namespace:
 ```rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
-use ext_php_rs::prelude::*;
-use ext_php_rs::{exception::PhpException, zend::ce};
+use ext_php_rs::{
+    prelude::*,
+    exception::PhpException,
+    zend::ce
+};
 
 #[php_class(name = "Redis\\Exception\\RedisException")]
-#[extends(ce::exception())]
+#[extends(ce::exception)]
 #[derive(Default)]
 pub struct RedisException;
 
@@ -101,25 +105,33 @@ pub struct RedisException;
 pub fn throw_exception() -> PhpResult<i32> {
     Err(PhpException::from_class::<RedisException>("Not good!".into()))
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
+
+#[php_module]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module
+        .class::<RedisException>()
+        .function(wrap_function!(throw_exception))
+}
 # fn main() {}
 ```
 
 ## Implementing an Interface
 
-To implement an interface, use `#[implements(ce)]` where `ce` is an expression returning a `ClassEntry`.
+To implement an interface, use `#[implements(ce)]` where `ce` is an function returning a `ClassEntry`.
 The following example implements [`ArrayAccess`](https://www.php.net/manual/en/class.arrayaccess.php):
-```rust,no_run
+
+````rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
-use ext_php_rs::prelude::*;
-use ext_php_rs::{exception::PhpResult, types::Zval, zend::ce};
+use ext_php_rs::{
+    prelude::*,
+    exception::PhpResult,
+    types::Zval,
+    zend::ce,
+};
 
 #[php_class]
-#[implements(ce::arrayaccess())]
+#[implements(ce::arrayaccess)]
 #[derive(Default)]
 pub struct EvenNumbersArray;
 
@@ -154,9 +166,10 @@ impl EvenNumbersArray {
         Err("Setting values is not supported".into())
     }
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
+
+#[php_module]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module.class::<EvenNumbersArray>()
+}
 # fn main() {}
-```
+````