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/function.rs

@@ -134,11 +134,11 @@ impl<'a> Function<'a> {
         // `handler` impl
         let required_arg_names: Vec<_> = required.iter().map(|arg| arg.name).collect();
         let not_required_arg_names: Vec<_> = not_required.iter().map(|arg| arg.name).collect();
-        let arg_declerations = self
+        let arg_declarations = self
             .args
             .typed
             .iter()
-            .map(TypedArg::arg_decleration)
+            .map(TypedArg::arg_declaration)
             .collect::<Result<Vec<_>>>()?;
         let arg_accessors = self.args.typed.iter().map(|arg| {
             arg.accessor(|e| {
@@ -248,7 +248,7 @@ impl<'a> Function<'a> {
                     ) {
                         use ::ext_php_rs::convert::IntoZval;
 
-                        #(#arg_declerations)*
+                        #(#arg_declarations)*
                         let result = {
                             #result
                         };
@@ -308,11 +308,11 @@ impl<'a> Function<'a> {
 
         let required_arg_names: Vec<_> = required.iter().map(|arg| arg.name).collect();
         let not_required_arg_names: Vec<_> = not_required.iter().map(|arg| arg.name).collect();
-        let arg_declerations = self
+        let arg_declarations = self
             .args
             .typed
             .iter()
-            .map(TypedArg::arg_decleration)
+            .map(TypedArg::arg_declaration)
             .collect::<Result<Vec<_>>>()?;
         let arg_accessors = self.args.typed.iter().map(|arg| {
             arg.accessor(
@@ -329,7 +329,7 @@ impl<'a> Function<'a> {
             ::ext_php_rs::class::ConstructorMeta {
                 constructor: {
                     fn inner(ex: &mut ::ext_php_rs::zend::ExecuteData) -> ::ext_php_rs::class::ConstructorResult<#class> {
-                        #(#arg_declerations)*
+                        #(#arg_declarations)*
                         let parse = ex.parser()
                             #(.arg(&mut #required_arg_names))*
                             .not_required()
@@ -515,9 +515,9 @@ impl TypedArg<'_> {
         ty
     }
 
-    /// Returns a token stream containing an argument decleration, where the
+    /// Returns a token stream containing an argument declaration, where the
     /// name of the variable holding the arg is the name of the argument.
-    fn arg_decleration(&self) -> Result<TokenStream> {
+    fn arg_declaration(&self) -> Result<TokenStream> {
         let name = self.name;
         let val = self.arg_builder()?;
         Ok(quote! {

crates/macros/src/impl_.rs

@@ -13,7 +13,7 @@ pub enum RenameRule {
     /// Methods won't be renamed.
     #[darling(rename = "none")]
     None,
-    /// Methods will be conveted to camelCase.
+    /// Methods will be converted to camelCase.
     #[darling(rename = "camelCase")]
     #[default]
     Camel,

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/async_impl.md

@@ -1,20 +1,20 @@
-# `#[php_async_impl]`
+# `#[php_async_impl]` Attribute
 
-Using `#[php_async_impl]` instead of `#[php_impl]` allows us to expose any async Rust library to PHP, using [PHP fibers](https://www.php.net/manual/en/language.fibers.php), [php-tokio](https://github.com/danog/php-tokio) and the [PHP Revolt event loop](https://revolt.run) under the hood to handle async interoperability.  
+Using `#[php_async_impl]` instead of `#[php_impl]` allows us to expose any async Rust library to PHP, using [PHP fibers](https://www.php.net/manual/en/language.fibers.php), [php-tokio](https://github.com/danog/php-tokio) and the [PHP Revolt event loop](https://revolt.run) under the hood to handle async interoperability.
 
 This allows full compatibility with [amphp](https://amphp.org), [PSL](https://github.com/azjezz/psl), [reactphp](https://reactphp.org) and any other async PHP library based on [Revolt](https://revolt.run).
 
-Traits annotated with `#[php_async_impl]` can freely expose any async function, using `await` and any async Rust library.  
+Traits annotated with `#[php_async_impl]` can freely expose any async function, using `await` and any async Rust library.
 
 Make sure to also expose the `php_tokio::EventLoop::init` and `php_tokio::EventLoop::wakeup` functions to PHP in order to initialize the event loop, as specified in the full example [here »](#async-example).
 
 Also, make sure to invoke `EventLoop::shutdown` in the request shutdown handler to clean up the tokio event loop before finishing the request.
 
 ## Async example
 
-In this example, we're exposing an async Rust HTTP client library called [reqwest](https://docs.rs/reqwest/latest/reqwest/) to PHP, using [PHP fibers](https://www.php.net/manual/en/language.fibers.php), [php-tokio](https://github.com/danog/php-tokio) and the [PHP Revolt event loop](https://revolt.run) under the hood to handle async interoperability.  
+In this example, we're exposing an async Rust HTTP client library called [reqwest](https://docs.rs/reqwest/latest/reqwest/) to PHP, using [PHP fibers](https://www.php.net/manual/en/language.fibers.php), [php-tokio](https://github.com/danog/php-tokio) and the [PHP Revolt event loop](https://revolt.run) under the hood to handle async interoperability.
 
-This allows full compatibility with [amphp](https://amphp.org), [PSL](https://github.com/azjezz/psl), [reactphp](https://reactphp.org) and any other async PHP library based on [Revolt](https://revolt.run).  
+This allows full compatibility with [amphp](https://amphp.org), [PSL](https://github.com/azjezz/psl), [reactphp](https://reactphp.org) and any other async PHP library based on [Revolt](https://revolt.run).
 
 Make sure to require [php-tokio](https://github.com/danog/php-tokio) as a dependency before proceeding.
 
@@ -49,11 +49,11 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 }
 ```
 
-Here's the async PHP code we use to interact with the Rust class we just exposed.  
+Here's the async PHP code we use to interact with the Rust class we just exposed.
 
 The `Client::init` method needs to be called only once in order to initialize the Revolt event loop and link it to the Tokio event loop, as shown by the following code.
 
-See [here »](https://amphp.org) for more info on async PHP using [amphp](https://amphp.org) + [revolt](https://revolt.run).  
+See [here »](https://amphp.org) for more info on async PHP using [amphp](https://amphp.org) + [revolt](https://revolt.run).
 
 ```php
 <?php declare(strict_types=1);