documentation

Author: davidcole1340

NEW_MACROS.md

@@ -37,6 +37,7 @@ need to register the classes with the module builder:
 use ext_php_rs::prelude::*;
 
 #[php_class]
+#[derive(Debug)]
 pub struct TestClass {
     #[prop]
     a: i32,
@@ -63,6 +64,12 @@ impl TestClass {
     fn x(&self) -> i32 {
         5
     }
+
+    pub fn builder_pattern(
+        self_: &mut ZendClassObject<TestClass>,
+    ) -> &mut ZendClassObject<TestClass> {
+        dbg!(self_)
+    }
 }
 
 #[php_module]

crates/macros/src/class.rs

@@ -181,16 +181,19 @@ fn generate_registered_class_impl(
             fn method_builders() -> ::std::vec::Vec<
                 (::ext_php_rs::builders::FunctionBuilder<'static>, ::ext_php_rs::flags::MethodFlags)
             > {
+                use ::ext_php_rs::internal::class::PhpClassImpl;
                 ::ext_php_rs::internal::class::PhpClassImplCollector::<Self>::default().get_methods()
             }
 
             #[inline]
             fn constructor() -> ::std::option::Option<::ext_php_rs::class::ConstructorMeta<Self>> {
+                use ::ext_php_rs::internal::class::PhpClassImpl;
                 ::ext_php_rs::internal::class::PhpClassImplCollector::<Self>::default().get_constructor()
             }
 
             #[inline]
             fn constants() -> &'static [(&'static str, &'static dyn ::ext_php_rs::convert::IntoZvalDyn)] {
+                use ::ext_php_rs::internal::class::PhpClassImpl;
                 ::ext_php_rs::internal::class::PhpClassImplCollector::<Self>::default().get_constants()
             }
         }

crates/macros/src/function.rs

@@ -454,7 +454,7 @@ impl<'a> TypedArg<'a> {
             }
         });
         Ok(quote! {
-            ::ext_php_rs::args::Arg::new(#name, <#ty as ::ext_php_rs::convert::FromZval>::TYPE)
+            ::ext_php_rs::args::Arg::new(#name, <#ty as ::ext_php_rs::convert::FromZvalMut>::TYPE)
                 #null
                 #default
         })
@@ -465,7 +465,7 @@ impl<'a> TypedArg<'a> {
         let name = self.name;
         if let Some(default) = &self.default {
             quote! {
-                #name.val().unwrap_or(#default)
+                #name.val().unwrap_or(#default.into())
             }
         } else if self.nullable {
             // Originally I thought we could just use the below case for `null` options, as

crates/macros/src/impl_.rs

@@ -266,21 +266,36 @@ impl<'a> ParsedImpl<'a> {
                     opts.parse(&mut method.attrs)?;
 
                     let args = Args::parse_from_fnargs(method.sig.inputs.iter(), opts.defaults)?;
-                    let func = Function::parse(&method.sig, Some(opts.name), args, opts.optional)?;
+                    let mut func =
+                        Function::parse(&method.sig, Some(opts.name), args, opts.optional)?;
 
                     if matches!(opts.ty, MethodTy::Constructor) {
                         if self.constructor.replace(func).is_some() {
                             bail!(method => "Only one constructor can be provided per class.");
                         }
                     } else {
-                        let builder = func.function_builder(CallType::Method {
+                        let call_type = CallType::Method {
                             class: self.path,
                             receiver: if func.args.receiver.is_some() {
+                                // `&self` or `&mut self`
                                 MethodReceiver::Class
+                            } else if func
+                                .args
+                                .typed
+                                .first()
+                                .map(|arg| arg.name == "self_")
+                                .unwrap_or_default()
+                            {
+                                // `self_: &[mut] ZendClassObject<Self>`
+                                // Need to remove arg from argument list
+                                func.args.typed.pop();
+                                MethodReceiver::ZendClassObject
                             } else {
+                                // Static method
                                 MethodReceiver::Static
                             },
-                        })?;
+                        };
+                        let builder = func.function_builder(call_type)?;
                         self.functions.push(FnBuilder {
                             builder,
                             vis: opts.vis,

crates/macros/src/zval.rs

@@ -235,6 +235,7 @@ fn parse_enum(
     Ok(quote! {
         impl #into_impl_generics ::ext_php_rs::convert::IntoZval for #ident #ty_generics #into_where_clause {
             const TYPE: ::ext_php_rs::flags::DataType = ::ext_php_rs::flags::DataType::Mixed;
+            const NULLABLE: bool = false;
 
             fn set_zval(
                 self,

examples/hello_world.rs

@@ -7,10 +7,11 @@ use ext_php_rs::{
     flags::DataType,
     internal::class::{PhpClassImpl, PhpClassImplCollector},
     prelude::*,
-    types::Zval,
+    types::{ZendClassObject, Zval},
     zend::ExecuteData,
 };
 
+#[derive(Debug)]
 #[php_class]
 pub struct TestClass {
     #[prop]
@@ -41,6 +42,12 @@ impl TestClass {
     fn x(&self) -> i32 {
         5
     }
+
+    pub fn builder_pattern(
+        self_: &mut ZendClassObject<TestClass>,
+    ) -> &mut ZendClassObject<TestClass> {
+        dbg!(self_)
+    }
 }
 
 #[php_function]

guide/src/SUMMARY.md

@@ -27,7 +27,6 @@
   - [Async futures](./macros/impl.md#async)
 - [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)

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 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 a function returning a `ClassEntry`.
 The following example implements [`ArrayAccess`](https://www.php.net/manual/en/class.arrayaccess.php):
+
 ```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() {}
 ```

guide/src/macros/constant.md

@@ -1,4 +1,4 @@
-# `#[php_const]`
+# `wrap_constant!()`
 
 Exports a Rust constant as a global PHP constant. The constant can be any type
 that implements `IntoConst`.
@@ -8,14 +8,17 @@ that implements `IntoConst`.
 ```rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
-# use ext_php_rs::prelude::*;
-#[php_const]
-const TEST_CONSTANT: i32 = 100;
+use ext_php_rs::prelude::*;
 
-#[php_const]
+const TEST_CONSTANT: i32 = 100;
 const ANOTHER_STRING_CONST: &'static str = "Hello world!";
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder { module }
+
+#[php_module]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module
+        .constant(wrap_constant!(TEST_CONSTANT))
+        .constant(wrap_constant!(ANOTHER_STRING_CONST))
+}
 # fn main() {}
 ```
 

guide/src/macros/impl.md

@@ -3,7 +3,8 @@
 You can export an entire `impl` block to PHP. This exports all methods as well
 as constants to PHP on the class that it is implemented on. This requires the
 `#[php_class]` macro to already be used on the underlying struct. Trait
-implementations cannot be exported to PHP.
+implementations cannot be exported to PHP. Only one `impl` block can be exported
+per class.
 
 If you do not want a function exported to PHP, you should place it in a separate
 `impl` block.
@@ -20,9 +21,8 @@ Class methods can take a `&self` or `&mut self` parameter. They cannot take a
 consuming `self` parameter. Static methods can omit this `self` parameter.
 
 To access the underlying Zend object, you can take a reference to a
-`ZendClassObject<T>` in place of the self parameter, where the parameter is
-annotated with the `#[this]` attribute. This can also be used to return a
-reference to `$this`.
+`ZendClassObject<T>` in place of the self parameter, where the parameter must
+be named `self_`. This can also be used to return a reference to `$this`.
 
 By default, all methods are renamed in PHP to the camel-case variant of the Rust
 method name. This can be changed on the `#[php_impl]` attribute, by passing one
@@ -114,22 +114,28 @@ constant for the maximum age of a `Human`.
 ```rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
-# use ext_php_rs::{prelude::*, types::ZendClassObject};
-# #[php_class]
-# #[derive(Debug, Default)]
-# pub struct Human {
-#     name: String,
-#     age: i32,
-#     #[prop]
-#     address: String,
-# }
+use ext_php_rs::{prelude::*, types::ZendClassObject};
+
+#[php_class]
+#[derive(Debug, Default)]
+pub struct Human {
+    name: String,
+    age: i32,
+    #[prop]
+    address: String,
+}
+
 #[php_impl]
 impl Human {
     const MAX_AGE: i32 = 100;
 
     // No `#[constructor]` attribute required here - the name is `__construct`.
     pub fn __construct(name: String, age: i32) -> Self {
-        Self { name, age, address: String::new() }
+        Self {
+            name,
+            age,
+            address: String::new(),
+        }
     }
 
     #[getter]
@@ -148,21 +154,25 @@ impl Human {
     }
 
     pub fn introduce(&self) {
-        println!("My name is {} and I am {} years old. I live at {}.", self.name, self.age, self.address);
+        println!(
+            "My name is {} and I am {} years old. I live at {}.",
+            self.name, self.age, self.address
+        );
     }
 
-    pub fn get_raw_obj(#[this] this: &mut ZendClassObject<Human>) {
-        dbg!(this);   
+    pub fn get_raw_obj(self_: &mut ZendClassObject<Human>) -> &mut ZendClassObject<Human> {
+        dbg!(self_)
     }
 
     pub fn get_max_age() -> i32 {
         Self::MAX_AGE
     }
 }
-# #[php_module]
-# pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
-#     module
-# }
+
+#[php_module]
+pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
+    module.class::<Human>()
+}
 # fn main() {}
 ```