fix(class)!: generate correct stubs for extends and implements

BREAKING CHANGE: `extends` and `implements` attributes now require the `stub` property containing the class/interface name to be used in stubs.

Refs: #326

Author: Xenira

crates/macros/src/class.rs

@@ -20,12 +20,18 @@ pub struct StructAttributes {
     modifier: Option<syn::Ident>,
     /// An expression of `ClassFlags` to be applied to the class.
     flags: Option<syn::Expr>,
-    extends: Option<syn::Expr>,
+    extends: Option<ClassEntryAttribute>,
     #[darling(multiple)]
-    implements: Vec<syn::Expr>,
+    implements: Vec<ClassEntryAttribute>,
     attrs: Vec<Attribute>,
 }
 
+#[derive(FromMeta, Debug)]
+pub struct ClassEntryAttribute {
+    ce: syn::Expr,
+    stub: String,
+}
+
 pub fn parser(mut input: ItemStruct) -> Result<TokenStream> {
     let attr = StructAttributes::from_attributes(&input.attrs)?;
     let ident = &input.ident;
@@ -111,14 +117,13 @@ fn generate_registered_class_impl(
     ident: &syn::Ident,
     class_name: &str,
     modifier: Option<&syn::Ident>,
-    extends: Option<&syn::Expr>,
-    implements: &[syn::Expr],
+    extends: Option<&ClassEntryAttribute>,
+    implements: &[ClassEntryAttribute],
     fields: &[Property],
     flags: Option<&syn::Expr>,
     docs: &[String],
 ) -> TokenStream {
     let modifier = modifier.option_tokens();
-    let extends = extends.option_tokens();
 
     let fields = fields.iter().map(|prop| {
         let name = prop.name();
@@ -149,16 +154,34 @@ fn generate_registered_class_impl(
         #(#docs)*
     };
 
+    let extends = if let Some(extends) = extends {
+        let ce = &extends.ce;
+        let stub = &extends.stub;
+        quote! {
+            Some((#ce, #stub))
+        }
+    } else {
+        quote! { None }
+    };
+
+    let implements = implements.iter().map(|imp| {
+        let ce = &imp.ce;
+        let stub = &imp.stub;
+        quote! {
+            (#ce, #stub)
+        }
+    });
+
     quote! {
         impl ::ext_php_rs::class::RegisteredClass for #ident {
             const CLASS_NAME: &'static str = #class_name;
             const BUILDER_MODIFIER: ::std::option::Option<
                 fn(::ext_php_rs::builders::ClassBuilder) -> ::ext_php_rs::builders::ClassBuilder
             > = #modifier;
             const EXTENDS: ::std::option::Option<
-                fn() -> &'static ::ext_php_rs::zend::ClassEntry
+                ::ext_php_rs::class::ClassEntryInfo
             > = #extends;
-            const IMPLEMENTS: &'static [fn() -> &'static ::ext_php_rs::zend::ClassEntry] = &[
+            const IMPLEMENTS: &'static [::ext_php_rs::class::ClassEntryInfo] = &[
                 #(#implements,)*
             ];
             const FLAGS: ::ext_php_rs::flags::ClassFlags = #flags;

crates/macros/src/lib.rs

@@ -27,21 +27,19 @@ extern crate proc_macro;
 ///
 /// ## Options
 ///
-/// The attribute takes some options to modify the output of the class:
+/// There are additional macros that modify the class. These macros **must** be
+/// placed underneath the `#[php_class]` attribute.
 ///
 /// - `name` - Changes the name of the class when exported to PHP. The Rust
 ///   struct 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.
-///
-/// - `#[php(extends = ce)]` - Sets the parent class of the class. Can only be
-///   used once. `ce` must be a function with the signature `fn() -> &'static
-///   ClassEntry`.
-/// - `#[php(implements = ce)]` - Implements the given interface on the class.
-///   Can be used multiple times. `ce` must be a valid function with the
-///   signature `fn() -> &'static ClassEntry`.
+/// - `rename` - Changes the case of the class name when exported to PHP.
+/// - `#[php(extends(ce = ce_fn, stub = "ParentClass"))]` - Sets the parent
+///   class of the class. Can only be used once. `ce_fn` must be a function with
+///   the signature `fn() -> &'static ClassEntry`.
+/// - `#[php(implements(ce = ce_fn, stub = "InterfaceName"))]` - Implements the
+///   given interface on the class. Can be used multiple times. `ce_fn` must be
+///   a valid function with the signature `fn() -> &'static ClassEntry`.
 ///
 /// You may also use the `#[php(prop)]` attribute on a struct field to use the
 /// field as a PHP property. By default, the field will be accessible from PHP
@@ -122,8 +120,9 @@ extern crate proc_macro;
 ///     zend::ce
 /// };
 ///
-/// #[php_class(name = "Redis\\Exception\\RedisException")]
-/// #[php(extends = ce::exception)]
+/// #[php_class]
+/// #[php(name = "Redis\\Exception\\RedisException")]
+/// #[php(extends(ce = ce::exception, stub = "\\Exception"))]
 /// #[derive(Default)]
 /// pub struct RedisException;
 ///
@@ -144,8 +143,8 @@ extern crate proc_macro;
 ///
 /// ## Implementing an Interface
 ///
-/// To implement an interface, use `#[php(implements = ce)]` where `ce` is an
-/// function returning a `ClassEntry`. The following example implements [`ArrayAccess`](https://www.php.net/manual/en/class.arrayaccess.php):
+/// To implement an interface, use `#[php(implements(ce = ce_fn, stub =
+/// "InterfaceName")]` where `ce_fn` is an function returning a `ClassEntry`. The following example implements [`ArrayAccess`](https://www.php.net/manual/en/class.arrayaccess.php):
 ///
 /// ````rust,no_run,ignore
 /// # #![cfg_attr(windows, feature(abi_vectorcall))]
@@ -158,7 +157,7 @@ extern crate proc_macro;
 /// };
 ///
 /// #[php_class]
-/// #[php(implements = ce::arrayaccess)]
+/// #[php(implements(ce = ce::arrayaccess, stub = "\\ArrayAccess"))]
 /// #[derive(Default)]
 /// pub struct EvenNumbersArray;
 ///

guide/src/macros/classes.md

@@ -13,10 +13,10 @@ placed underneath the `#[php_class]` attribute.
   name is kept the same. If no name is given, the name of the struct is used.
   Useful for namespacing classes.
 - `rename` - Changes the case of the class name when exported to PHP.
-- `#[php(extends = ce)]` - Sets the parent class of the class. Can only be used once.
-  `ce` must be a function with the signature `fn() -> &'static ClassEntry`.
-- `#[php(implements = ce)]` - Implements the given interface on the class. Can be used
-  multiple times. `ce` must be a valid function with the signature
+- `#[php(extends(ce = ce_fn, stub = "ParentClass"))]` - Sets the parent class of the class. Can only be used once.
+  `ce_fn` must be a function with the signature `fn() -> &'static ClassEntry`.
+- `#[php(implements(ce = ce_fn, stub = "InterfaceName"))]` - Implements the given interface on the class. Can be used
+  multiple times. `ce_fn` must be a valid function with the signature
   `fn() -> &'static ClassEntry`.
 
 You may also use the `#[php(prop)]` attribute on a struct field to use the field as a
@@ -97,7 +97,7 @@ use ext_php_rs::{
 
 #[php_class]
 #[php(name = "Redis\\Exception\\RedisException")]
-#[php(extends = ce::exception)]
+#[php(extends(ce = ce::exception, stub = "\\Exception"))]
 #[derive(Default)]
 pub struct RedisException;
 
@@ -118,7 +118,7 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 
 ## Implementing an Interface
 
-To implement an interface, use `#[php(implements = ce)]` where `ce` is an function returning a `ClassEntry`.
+To implement an interface, use `#[php(implements(ce = ce_fn, stub = "InterfaceName")]` where `ce_fn` is an function returning a `ClassEntry`.
 The following example implements [`ArrayAccess`](https://www.php.net/manual/en/class.arrayaccess.php):
 
 ````rust,no_run
@@ -132,7 +132,7 @@ use ext_php_rs::{
 };
 
 #[php_class]
-#[php(implements = ce::arrayaccess)]
+#[php(implements(ce = ce::arrayaccess, stub = "\\ArrayAccess"))]
 #[derive(Default)]
 pub struct EvenNumbersArray;
 

guide/src/migration-guides/v0.14.md

@@ -106,8 +106,8 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 - `#[php(name = "NEW_NAME")]` - Renames the class
 - `#[php(rename = case)]` - Changes the case of the class name
 - `#[php(vis = "public")]` - Changes the visibility of the class
-- `#[php(extends = "ParentClass")]` - Extends a parent class
-- `#[php(implements = "Interface")]` - Implements an interface
+- `#[php(extends(ce = ce_fn, stub = "ParentClass")]` - Extends a parent class
+- `#[php(implements(ce = ce_fn, stub = "Interface"))]` - Implements an interface
 - `#[php(prop)]` - Marks a field as a property
 
 **Supported `#[php]` attributes (`impl`):**
@@ -116,6 +116,13 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 
 For elements in the `#[php_impl]` block see the respective function and constant attributes.
 
+#### Extends and Implements
+
+Extends and implements are now taking a second parameter which is the
+`stub` name. This is the name of the class or interface in PHP.
+
+This value is only used for stub generation and is not used for the class name in Rust.
+
 ### Constants
 
 Mostly unchanged in terms of constant definition, however you now need to

src/builders/class.rs

@@ -2,7 +2,7 @@ use std::{ffi::CString, mem::MaybeUninit, ptr, rc::Rc};
 
 use crate::{
     builders::FunctionBuilder,
-    class::{ConstructorMeta, ConstructorResult, RegisteredClass},
+    class::{ClassEntryInfo, ConstructorMeta, ConstructorResult, RegisteredClass},
     convert::{IntoZval, IntoZvalDyn},
     describe::DocComments,
     error::{Error, Result},
@@ -24,8 +24,8 @@ type ConstantEntry = (String, Box<dyn FnOnce() -> Result<Zval>>, DocComments);
 pub struct ClassBuilder {
     pub(crate) name: String,
     ce: ClassEntry,
-    extends: Option<&'static ClassEntry>,
-    interfaces: Vec<&'static ClassEntry>,
+    pub(crate) extends: Option<ClassEntryInfo>,
+    pub(crate) interfaces: Vec<ClassEntryInfo>,
     pub(crate) methods: Vec<(FunctionBuilder<'static>, MethodFlags)>,
     object_override: Option<unsafe extern "C" fn(class_type: *mut ClassEntry) -> *mut ZendObject>,
     pub(crate) properties: Vec<(String, PropertyFlags, DocComments)>,
@@ -63,7 +63,7 @@ impl ClassBuilder {
     /// # Parameters
     ///
     /// * `parent` - The parent class to extend.
-    pub fn extends(mut self, parent: &'static ClassEntry) -> Self {
+    pub fn extends(mut self, parent: ClassEntryInfo) -> Self {
         self.extends = Some(parent);
         self
     }
@@ -77,11 +77,7 @@ impl ClassBuilder {
     /// # Panics
     ///
     /// Panics when the given class entry `interface` is not an interface.
-    pub fn implements(mut self, interface: &'static ClassEntry) -> Self {
-        assert!(
-            interface.is_interface(),
-            "Given class entry was not an interface."
-        );
+    pub fn implements(mut self, interface: ClassEntryInfo) -> Self {
         self.interfaces.push(interface);
         self
     }
@@ -309,7 +305,7 @@ impl ClassBuilder {
             zend_register_internal_class_ex(
                 &mut self.ce,
                 match self.extends {
-                    Some(ptr) => ptr::from_ref(ptr).cast_mut(),
+                    Some((ptr, _)) => ptr::from_ref(ptr()).cast_mut(),
                     None => std::ptr::null_mut(),
                 },
             )
@@ -329,8 +325,14 @@ impl ClassBuilder {
             }
         }
 
-        for iface in self.interfaces {
-            unsafe { zend_do_implement_interface(class, ptr::from_ref(iface).cast_mut()) };
+        for (iface, _) in self.interfaces {
+            let interface = iface();
+            assert!(
+                interface.is_interface(),
+                "Given class entry was not an interface."
+            );
+
+            unsafe { zend_do_implement_interface(class, ptr::from_ref(interface).cast_mut()) };
         }
 
         for (name, flags, _) in self.properties {

src/builders/module.rs

@@ -179,11 +179,11 @@ impl ModuleBuilder<'_> {
             for (method, flags) in T::method_builders() {
                 builder = builder.method(method, flags);
             }
-            if let Some(extends) = T::EXTENDS {
-                builder = builder.extends(extends());
+            if let Some(parent) = T::EXTENDS {
+                builder = builder.extends(parent);
             }
-            for iface in T::IMPLEMENTS {
-                builder = builder.implements(iface());
+            for interface in T::IMPLEMENTS {
+                builder = builder.implements(*interface);
             }
             for (name, value, docs) in T::constants() {
                 builder = builder

src/class.rs

@@ -18,6 +18,10 @@ use crate::{
     zend::{ClassEntry, ExecuteData, ZendObjectHandlers},
 };
 
+/// A type alias for a tuple containing a function pointer to a class entry
+/// and a string representing the class name used in stubs.
+pub type ClassEntryInfo = (fn() -> &'static ClassEntry, &'static str);
+
 /// Implemented on Rust types which are exported to PHP. Allows users to get and
 /// set PHP properties on the object.
 pub trait RegisteredClass: Sized + 'static {
@@ -29,10 +33,10 @@ pub trait RegisteredClass: Sized + 'static {
     const BUILDER_MODIFIER: Option<fn(ClassBuilder) -> ClassBuilder>;
 
     /// Parent class entry. Optional.
-    const EXTENDS: Option<fn() -> &'static ClassEntry>;
+    const EXTENDS: Option<ClassEntryInfo>;
 
     /// Interfaces implemented by the class.
-    const IMPLEMENTS: &'static [fn() -> &'static ClassEntry];
+    const IMPLEMENTS: &'static [ClassEntryInfo];
 
     /// PHP flags applied to the class.
     const FLAGS: ClassFlags = ClassFlags::empty();

src/closure.rs

@@ -5,14 +5,14 @@ use std::collections::HashMap;
 use crate::{
     args::{Arg, ArgParser},
     builders::{ClassBuilder, FunctionBuilder},
-    class::{ClassMetadata, RegisteredClass},
+    class::{ClassEntryInfo, ClassMetadata, RegisteredClass},
     convert::{FromZval, IntoZval},
     describe::DocComments,
     exception::PhpException,
     flags::{DataType, MethodFlags},
     internal::property::PropertyInfo,
     types::Zval,
-    zend::{ClassEntry, ExecuteData},
+    zend::ExecuteData,
     zend_fastcall,
 };
 
@@ -150,8 +150,8 @@ impl RegisteredClass for Closure {
     const CLASS_NAME: &'static str = "RustClosure";
 
     const BUILDER_MODIFIER: Option<fn(ClassBuilder) -> ClassBuilder> = None;
-    const EXTENDS: Option<fn() -> &'static ClassEntry> = None;
-    const IMPLEMENTS: &'static [fn() -> &'static ClassEntry] = &[];
+    const EXTENDS: Option<ClassEntryInfo> = None;
+    const IMPLEMENTS: &'static [ClassEntryInfo] = &[];
 
     fn get_metadata() -> &'static ClassMetadata<Self> {
         &CLOSURE_META

src/describe/mod.rs

@@ -185,8 +185,13 @@ impl From<ClassBuilder> for Class {
                     .collect::<StdVec<_>>()
                     .into(),
             ),
-            extends: abi::Option::None, // TODO: Implement extends #326
-            implements: vec![].into(),  // TODO: Implement implements #326
+            extends: val.extends.map(|(_, stub)| stub.into()).into(),
+            implements: val
+                .interfaces
+                .into_iter()
+                .map(|(_, stub)| stub.into())
+                .collect::<StdVec<_>>()
+                .into(),
             properties: val
                 .properties
                 .into_iter()
@@ -241,7 +246,7 @@ impl From<(String, PropertyFlags, DocComments)> for Property {
         // TODO: Implement nullable #376
         let nullable = false;
         let docs = docs.into();
-        println!("Property: {name:?}");
+
         Self {
             name: name.into(),
             docs,

src/exception.rs

@@ -82,6 +82,20 @@ impl PhpException {
         self.object = object;
     }
 
+    /// Builder functin that sets the Zval object for the exception.
+    ///
+    /// Exceptions can be based of instantiated Zval objects when you are
+    /// throwing a custom exception with stateful properties.
+    ///
+    /// # Parameters
+    ///
+    /// * `object` - The Zval object.
+    #[must_use]
+    pub fn with_object(mut self, object: Zval) -> Self {
+        self.object = Some(object);
+        self
+    }
+
     /// Throws the exception, returning nothing inside a result if successful
     /// and an error otherwise.
     ///
@@ -213,7 +227,7 @@ pub fn throw_with_code(ex: &ClassEntry, code: i32, message: &str) -> Result<()>
 /// use crate::ext_php_rs::convert::IntoZval;
 ///
 /// #[php_class]
-/// #[php(extends = ext_php_rs::zend::ce::exception)]
+/// #[php(extends(ce = ext_php_rs::zend::ce::exception, stub = "\\Exception"))]
 /// pub struct JsException {
 ///     #[php(prop, flags = ext_php_rs::flags::PropertyFlags::Public)]
 ///     message: String,