Impl ToOwned for ZObj, supplement ZObj document. (#97)

Author: jmjoy

phper-doc/doc/_04_zval/index.md

@@ -40,8 +40,6 @@ Otherwise, there are also composite types that implement `From`.
 - `From<Option<T>>`: if Some(T), T will be converted to PHP type like `From<T>`,
   or `None` wll be converted to `null`.
 
-### Example
-
 ```rust,no_run
 use phper::values::ZVal;
 
@@ -59,8 +57,6 @@ Now you can use `as_*` or `expect_*` methods to convert ZVal to Rust types.
   [phper::errors::ExpectTypeError] will be returned, with the message:
   `type error: must be of type {expect_type}, {actual_type} given")`.
 
-### Example
-
 ```rust,no_run
 use phper::echo;
 use phper::values::ZVal;

phper-doc/doc/_05_internal_types/_03_z_obj/index.md

@@ -1,3 +1,46 @@
 # Z Obj
 
-TODO
+The [`&ZObj`](phper::objects::ZObj) and [`ZObject`](phper::objects::ZObject) are
+the wrapper of [`zend_object`](phper::sys::zend_object).
+
+You can do oop operation using `ZObj` or `ZObject`, like getting and setting properties,
+calling methods, etc.
+
+```rust,no_run
+use phper::classes::ClassEntry;
+use phper::objects::ZObject;
+use phper::errors::exception_class;
+
+let mut e: ZObject = exception_class().new_object([]).unwrap();
+e.set_property("code", 403);
+e.set_property("message", "oh no");
+let _message = e.call("getMessage", []).unwrap();
+```
+
+`ZObj` implements `ToOwned` and `ToRefOwned` to upgrade to `ZObject`.
+
+- `ToOwned`: Duplicate the object via PHP keyword `clone`, like `$cloned_object = clone $some_object();`;
+- `ToRefOwned`: Duplicate the object via increment refcount.
+
+`ZObject` implements `Clone`, same as `ZObj::to_owned`.
+
+```rust,no_run
+use phper::sys;
+use phper::objects::ZObj;
+use phper::alloc::ToRefOwned;
+
+extern "C" {
+    fn something() -> *mut sys::zend_object;
+}
+
+let o = unsafe { ZObj::from_mut_ptr(something()) };
+
+// By PHP `clone`.
+let _o = o.to_owned(); 
+
+// By refcount increment.
+let _o = o.to_ref_owned();
+```
+
+Note that neither `ZObj` nor `ZObject` implement `Send` and `Sync`, because PHP
+is single-threaded.

phper/src/errors.rs

@@ -166,6 +166,7 @@ pub type Result<T> = result::Result<T, self::Error>;
 
 /// Crate level Error, which also can become an exception in php.
 #[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
 pub enum Error {
     /// The error type for I/O operations.
     #[error(transparent)]

phper/src/objects.rs

@@ -25,7 +25,7 @@ use std::{
     fmt::{self, Debug},
     intrinsics::transmute,
     marker::PhantomData,
-    mem::{forget, size_of, ManuallyDrop},
+    mem::{forget, size_of, zeroed, ManuallyDrop},
     ops::{Deref, DerefMut},
     ptr::null_mut,
 };
@@ -278,6 +278,17 @@ impl ZObj {
     }
 }
 
+impl ToOwned for ZObj {
+    type Owned = ZObject;
+
+    /// The `to_owned` will do the copy like in PHP `$cloned_object = clone
+    /// $some_object();`.
+    #[inline]
+    fn to_owned(&self) -> Self::Owned {
+        clone_obj(self.as_ptr())
+    }
+}
+
 impl ToRefOwned for ZObj {
     type Owned = ZObject;
 
@@ -351,30 +362,9 @@ impl ZObject {
 impl Clone for ZObject {
     /// The clone will do the copy like in PHP `$cloned_object = clone
     /// $some_object();`.
+    #[inline]
     fn clone(&self) -> Self {
-        unsafe {
-            Self::from_raw({
-                let mut zv = ManuallyDrop::new(ZVal::default());
-                phper_zval_obj(zv.as_mut_ptr(), self.as_ptr() as *mut _);
-                let handlers = phper_z_obj_ht_p(zv.as_ptr());
-
-                let ptr = {
-                    #[cfg(phper_major_version = "7")]
-                    {
-                        zv.as_mut_ptr()
-                    }
-                    #[cfg(phper_major_version = "8")]
-                    {
-                        self.as_ptr() as *mut _
-                    }
-                };
-
-                match (*handlers).clone_obj {
-                    Some(clone_obj) => clone_obj(ptr),
-                    None => zend_objects_clone_obj(ptr),
-                }
-            })
-        }
+        clone_obj(self.as_ptr())
     }
 }
 
@@ -415,6 +405,32 @@ impl Debug for ZObject {
     }
 }
 
+fn clone_obj(obj: *const zend_object) -> ZObject {
+    unsafe {
+        ZObject::from_raw({
+            let mut zv = zeroed::<zval>();
+            phper_zval_obj(&mut zv, obj as *mut _);
+            let handlers = phper_z_obj_ht_p(&zv);
+
+            let ptr = {
+                #[cfg(phper_major_version = "7")]
+                {
+                    &mut zv as *mut _
+                }
+                #[cfg(phper_major_version = "8")]
+                {
+                    obj as *mut _
+                }
+            };
+
+            match (*handlers).clone_obj {
+                Some(clone_obj) => clone_obj(ptr),
+                None => zend_objects_clone_obj(ptr),
+            }
+        })
+    }
+}
+
 /// The object owned state, usually as the parameter of method handler.
 #[repr(transparent)]
 pub struct StateObj<T> {

tests/integration/src/objects.rs

@@ -9,7 +9,8 @@
 // See the Mulan PSL v2 for more details.
 
 use phper::{
-    classes::ClassEntry, modules::Module, objects::ZObject, types::TypeInfo, values::ZVal,
+    alloc::ToRefOwned, classes::ClassEntry, functions::Argument, modules::Module, objects::ZObject,
+    types::TypeInfo, values::ZVal,
 };
 
 pub fn integrate(module: &mut Module) {
@@ -59,4 +60,88 @@ pub fn integrate(module: &mut Module) {
             Ok(())
         },
     );
+
+    module.add_function(
+        "integrate_objects_clone",
+        |_: &mut [ZVal]| -> phper::Result<()> {
+            let mut o1 = ZObject::new_by_std_class();
+            o1.set_property("foo", "bar");
+
+            let mut o2 = o1.clone();
+            assert_eq!(
+                o2.get_property("foo").as_z_str().unwrap().to_bytes(),
+                b"bar"
+            );
+
+            o2.set_property("foo", "baz");
+            assert_eq!(
+                o1.get_property("foo").as_z_str().unwrap().to_bytes(),
+                b"bar"
+            );
+            assert_eq!(
+                o2.get_property("foo").as_z_str().unwrap().to_bytes(),
+                b"baz"
+            );
+
+            Ok(())
+        },
+    );
+
+    module
+        .add_function(
+            "integrate_objects_to_owned",
+            |arguments: &mut [ZVal]| -> phper::Result<()> {
+                let o1 = arguments[0].expect_mut_z_obj()?;
+
+                o1.set_property("foo", "bar");
+
+                let mut o2 = o1.to_owned();
+                assert_eq!(
+                    o2.get_property("foo").as_z_str().unwrap().to_bytes(),
+                    b"bar"
+                );
+
+                o2.set_property("foo", "baz");
+                assert_eq!(
+                    o1.get_property("foo").as_z_str().unwrap().to_bytes(),
+                    b"bar"
+                );
+                assert_eq!(
+                    o2.get_property("foo").as_z_str().unwrap().to_bytes(),
+                    b"baz"
+                );
+
+                Ok(())
+            },
+        )
+        .argument(Argument::by_val("obj"));
+
+    module
+        .add_function(
+            "integrate_objects_to_ref_owned",
+            |arguments: &mut [ZVal]| -> phper::Result<()> {
+                let o1 = arguments[0].expect_mut_z_obj()?;
+
+                o1.set_property("foo", "bar");
+
+                let mut o2 = o1.to_ref_owned();
+                assert_eq!(
+                    o2.get_property("foo").as_z_str().unwrap().to_bytes(),
+                    b"bar"
+                );
+
+                o2.set_property("foo", "baz");
+                assert_eq!(
+                    o1.get_property("foo").as_z_str().unwrap().to_bytes(),
+                    b"baz"
+                );
+                assert_eq!(
+                    o2.get_property("foo").as_z_str().unwrap().to_bytes(),
+                    b"baz"
+                );
+
+                Ok(())
+            },
+        )
+        .argument(Argument::by_val("obj"));
 }

tests/integration/tests/php/objects.php

@@ -17,3 +17,6 @@
 integrate_objects_get_set();
 integrate_objects_set_val();
 integrate_objects_call();
+integrate_objects_clone();
+integrate_objects_to_owned(new stdClass());
+integrate_objects_to_ref_owned(new stdClass());