docs(macro): update docs to outer macro pattern

Refs: #335

Author: Xenira

README.md

@@ -19,22 +19,19 @@ Export a simple function `function hello_world(string $name): string` to PHP:
 ```rust
 #![cfg_attr(windows, feature(abi_vectorcall))]
 
-use ext_php_rs::prelude::*;
-
-/// Gives you a nice greeting!
-/// 
-/// @param string $name Your name.
-/// 
-/// @return string Nice greeting!
-#[php_function]
-pub fn hello_world(name: String) -> String {
-    format!("Hello, {}!", name)
-}
+use ext_php_rs::php_module;
 
-// Required to register the extension with PHP.
 #[php_module]
-pub fn module(module: ModuleBuilder) -> ModuleBuilder {
-    module
+mod module {
+    /// Gives you a nice greeting!
+    ///
+    /// @param string $name Your name.
+    ///
+    /// @return string Nice greeting!
+    #[php_function]
+    pub fn hello_world(name: String) -> String {
+        format!("Hello, {}!", name)
+    }
 }
 ```
 

crates/macros/src/module_builder.rs

@@ -92,6 +92,7 @@ impl ModuleBuilder {
 
         quote! {
             mod module {
+                use ::ext_php_rs::prelude::*;
                 #class_stream
                 #(#impl_stream)*
                 #(#registered_classes_impls)*

guide/src/exceptions.md

@@ -30,19 +30,18 @@ the `#[php_function]` attribute.
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 use ext_php_rs::prelude::*;
-use std::convert::TryInto;
-
-// Trivial example - PHP represents all integers as `u64` on 64-bit systems
-// so the `u32` would be converted back to `u64`, but that's okay for an example.
-#[php_function]
-pub fn something_fallible(n: u64) -> PhpResult<u32> {
-    let n: u32 = n.try_into().map_err(|_| "Could not convert into u32")?;
-    Ok(n)
-}
 
 #[php_module]
-pub fn module(module: ModuleBuilder) -> ModuleBuilder {
-    module
+mod module {
+    use std::convert::TryInto;
+
+    // Trivial example - PHP represents all integers as `u64` on 64-bit systems
+    // so the `u32` would be converted back to `u64`, but that's okay for an example.
+    #[php_function]
+    pub fn something_fallible(n: u64) -> PhpResult<u32> {
+        let n: u32 = n.try_into().map_err(|_| "Could not convert into u32")?;
+        Ok(n)
+    }
 }
 # fn main() {}
 ```

guide/src/ini-settings.md

@@ -11,19 +11,23 @@ All PHP INI definitions must be registered with PHP to get / set their values vi
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 # use ext_php_rs::prelude::*;
-# use ext_php_rs::zend::IniEntryDef;
-# use ext_php_rs::flags::IniEntryPermission;
-
-#[php_startup]
-pub fn startup_function(ty: i32, module_number: 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);
+
+#[php_module]
+mod module {
+    # use ext_php_rs::zend::IniEntryDef;
+    # use ext_php_rs::flags::IniEntryPermission;
+
+    #[php_startup]
+    pub fn startup_function(ty: i32, module_number: 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);
+    }
 }
 # fn main() {}
 ```
@@ -36,13 +40,16 @@ The INI values are stored as part of the `GlobalExecutor`, and can be accessed v
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 # use ext_php_rs::prelude::*;
-# use ext_php_rs::zend::ExecutorGlobals;
 
-#[php_startup]
-pub fn startup_function(ty: i32, module_number: 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>>
+#[php_module]
+mod module {
+    # use ext_php_rs::zend::ExecutorGlobals;
+    #[php_startup]
+    pub fn startup_function(ty: i32, module_number: 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>>
+    }
 }
 # fn main() {}
 ```

guide/src/macros/classes.md

@@ -2,7 +2,8 @@
 
 Structs can be exported to PHP as classes with the `#[php_class]` attribute
 macro. This attribute derives the `RegisteredClass` trait on your struct, as
-well as registering the class to be registered with the `#[php_module]` macro.
+well as registering the class to be registered with the `#[php_module]` containing
+the class.
 
 ## Options
 
@@ -12,8 +13,7 @@ The attribute takes some options to modify the output of the class:
   name is kept the same. If no name is given, the name of the struct is used.
   Useful for namespacing classes.
 
-There are also additional macros that modify the class. These macros **must** be
-placed underneath the `#[php_class]` attribute.
+There are also additional macros that modify the class.
 
 - `#[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
@@ -23,7 +23,7 @@ placed underneath the `#[php_class]` attribute.
   the `#[php_module]` function.
 
 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
+PHP property. By default, the field will then be accessible from PHP publicly with
 the same name as the field. Property types must implement `IntoZval` and
 `FromZval`.
 
@@ -68,17 +68,16 @@ This example creates a PHP class `Human`, adding a PHP property `address`.
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 # use ext_php_rs::prelude::*;
-#[php_class]
-pub struct Human {
-    name: String,
-    age: i32,
-    #[prop]
-    address: String,
+#[php_module]
+mod module {
+    #[php_class]
+    pub struct Human {
+        name: String,
+        age: i32,
+        #[prop]
+        address: String,
+    }
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
 # fn main() {}
 ```
 
@@ -89,22 +88,22 @@ it in the `Redis\Exception` namespace:
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 use ext_php_rs::prelude::*;
-use ext_php_rs::{exception::PhpException, zend::ce};
 
-#[php_class(name = "Redis\\Exception\\RedisException")]
-#[extends(ce::exception())]
-#[derive(Default)]
-pub struct RedisException;
+#[php_module]
+pub mod module {
+    use ext_php_rs::{exception::PhpException, zend::ce};
+
+    #[php_class(name = "Redis\\Exception\\RedisException")]
+    #[extends(ce::exception())]
+    #[derive(Default)]
+    pub struct RedisException;
 
-// Throw our newly created exception
-#[php_function]
-pub fn throw_exception() -> PhpResult<i32> {
-    Err(PhpException::from_class::<RedisException>("Not good!".into()))
+    // Throw our newly created exception
+    #[php_function]
+    pub fn throw_exception() -> PhpResult<i32> {
+        Err(PhpException::from_class::<RedisException>("Not good!".into()))
+    }
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
 # fn main() {}
 ```
 
@@ -116,47 +115,47 @@ The following example implements [`ArrayAccess`](https://www.php.net/manual/en/c
 # #![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};
-
-#[php_class]
-#[implements(ce::arrayaccess())]
-#[derive(Default)]
-pub struct EvenNumbersArray;
-
-/// Returns `true` if the array offset is an even number.
-/// Usage:
-/// ```php
-/// $arr = new EvenNumbersArray();
-/// var_dump($arr[0]); // true
-/// var_dump($arr[1]); // false
-/// var_dump($arr[2]); // true
-/// var_dump($arr[3]); // false
-/// var_dump($arr[4]); // true
-/// var_dump($arr[5] = true); // Fatal error:  Uncaught Exception: Setting values is not supported
-/// ```
-#[php_impl]
-impl EvenNumbersArray {
-    pub fn __construct() -> EvenNumbersArray {
-        EvenNumbersArray {}
-    }
-    // We need to use `Zval` because ArrayAccess needs $offset to be a `mixed`
-    pub fn offset_exists(&self, offset: &'_ Zval) -> bool {
-        offset.is_long()
-    }
-    pub fn offset_get(&self, offset: &'_ Zval) -> PhpResult<bool> {
-        let integer_offset = offset.long().ok_or("Expected integer offset")?;
-        Ok(integer_offset % 2 == 0)
-    }
-    pub fn offset_set(&mut self, _offset: &'_ Zval, _value: &'_ Zval) -> PhpResult {
-        Err("Setting values is not supported".into())
-    }
-    pub fn offset_unset(&mut self, _offset: &'_ Zval) -> PhpResult {
-        Err("Setting values is not supported".into())
+
+#[php_module]
+mod module {
+    use ext_php_rs::{exception::PhpResult, types::Zval, zend::ce};
+
+    #[php_class]
+    #[implements(ce::arrayaccess())]
+    #[derive(Default)]
+    pub struct EvenNumbersArray;
+
+    /// Returns `true` if the array offset is an even number.
+    /// Usage:
+    /// ```php
+    /// $arr = new EvenNumbersArray();
+    /// var_dump($arr[0]); // true
+    /// var_dump($arr[1]); // false
+    /// var_dump($arr[2]); // true
+    /// var_dump($arr[3]); // false
+    /// var_dump($arr[4]); // true
+    /// var_dump($arr[5] = true); // Fatal error:  Uncaught Exception: Setting values is not supported
+    /// ```
+    #[php_impl]
+    impl EvenNumbersArray {
+        pub fn __construct() -> EvenNumbersArray {
+            EvenNumbersArray {}
+        }
+        // We need to use `Zval` because ArrayAccess needs $offset to be a `mixed`
+        pub fn offset_exists(&self, offset: &'_ Zval) -> bool {
+            offset.is_long()
+        }
+        pub fn offset_get(&self, offset: &'_ Zval) -> PhpResult<bool> {
+            let integer_offset = offset.long().ok_or("Expected integer offset")?;
+            Ok(integer_offset % 2 == 0)
+        }
+        pub fn offset_set(&mut self, _offset: &'_ Zval, _value: &'_ Zval) -> PhpResult {
+            Err("Setting values is not supported".into())
+        }
+        pub fn offset_unset(&mut self, _offset: &'_ Zval) -> PhpResult {
+            Err("Setting values is not supported".into())
+        }
     }
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
 # fn main() {}
 ```

guide/src/macros/constant.md

@@ -9,13 +9,14 @@ that implements `IntoConst`.
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 # use ext_php_rs::prelude::*;
-#[php_const]
-const TEST_CONSTANT: i32 = 100;
+#[php_module]
+mod module {
+    #[php_const]
+    const TEST_CONSTANT: i32 = 100;
 
-#[php_const]
-const ANOTHER_STRING_CONST: &'static str = "Hello world!";
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder { module }
+    #[php_const]
+    const ANOTHER_STRING_CONST: &'static str = "Hello world!";
+}
 # fn main() {}
 ```
 

guide/src/macros/extern.md

@@ -0,0 +1,61 @@
+# `#[php_extern]`
+
+Attribute used to annotate `extern` blocks which are deemed as PHP
+functions.
+
+This allows you to 'import' PHP functions into Rust so that they can be
+called like regular Rust functions. Parameters can be any type that
+implements [`IntoZval`], and the return type can be anything that implements
+[`From<Zval>`] (notice how [`Zval`] is consumed rather than borrowed in this
+case).
+
+Unlike most other attributes, this does not need to be placed inside a
+`#[php_module]` block.
+
+# Panics
+
+The function can panic when called under a few circumstances:
+
+* The function could not be found or was not callable.
+* One of the parameters could not be converted into a [`Zval`].
+* The actual function call failed internally.
+* The output [`Zval`] could not be parsed into the output type.
+
+The last point can be important when interacting with functions that return
+unions, such as [`strpos`] which can return an integer or a boolean. In this
+case, a [`Zval`] should be returned as parsing a boolean to an integer is
+invalid, and vice versa.
+
+# Example
+
+This `extern` block imports the [`strpos`] function from PHP. Notice that
+the string parameters can take either [`String`] or [`&str`], the optional
+parameter `offset` is an [`Option<i64>`], and the return value is a [`Zval`]
+as the return type is an integer-boolean union.
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+# use ext_php_rs::types::Zval;
+#[php_extern]
+extern "C" {
+    fn strpos(haystack: &str, needle: &str, offset: Option<i64>) -> Zval;
+}
+
+#[php_module]
+mod module {
+    # use ext_php_rs::types::Zval;
+    use super::strpos;
+
+    #[php_function]
+    pub fn my_strpos() {
+        assert_eq!(unsafe { strpos("Hello", "e", None) }.long(), Some(1));
+    }
+}
+# fn main() {}
+```
+
+[`strpos`]: https://www.php.net/manual/en/function.strpos.php
+[`IntoZval`]: crate::convert::IntoZval
+[`Zval`]: crate::types::Zval