test and document co-dependent classes

phper-doc/doc/_06_module/_06_register_class/index.md

@@ -38,8 +38,8 @@ class Foo {}
 
 ## Extends & implements
 
-To allow a class to extend another, you can use `ClassEntity.extends(StateClass<T>)` for classes implemented
-in your module. A StateClass can either be obtained by registering your own class against the module, or
+To allow a class to extend another, you can use `ClassEntity.extends(StateClass<T>)`.
+A StateClass can either be obtained by registering your own class against the module, or
 by  looking up the class by name (for example, for PHP built-in classes like `Exception`).
 
 If you want class `Foo` extends `Bar`, and implements interface `Stringable`:
@@ -195,3 +195,51 @@ class MyHashMap {
 
 }
 ```
+
+## Circular class dependencies
+If you wish to register classes which depend on each other, you can retrieve the bound class (`StateClass<T>`)
+from a `ClassEntity`, and use it in functions and methods:
+
+```rust,no_run
+use phper::{
+    classes::{ClassEntity, StateClass, Visibility},
+    modules::Module,
+};
+
+let mut module = Module::new(
+    env!("CARGO_CRATE_NAME"),
+    env!("CARGO_PKG_VERSION"),
+    env!("CARGO_PKG_AUTHORS"),
+);
+
+let mut a_cls = ClassEntity::new("A");
+let mut b_cls = ClassEntity::new("B");
+let a_bound_class = a_cls.bound_class();
+let b_bound_class = b_cls.bound_class();
+
+a_cls.add_static_method("createB", Visibility::Public, move |_| {
+    let object = b_bound_class.init_object()?;
+    Ok::<_, phper::Error>(object)
+});
+b_cls.add_static_method("createA", Visibility::Public, move |_| {
+    let object = a_bound_class.init_object()?;
+    Ok::<_, phper::Error>(object)
+});
+
+module.add_class(a_cls);
+module.add_class(b_cls);
+```
+
+This is equivalent to the following PHP code:
+```php
+class A {
+  public static function createB(): B {
+    return new B();
+  }
+}
+class B {
+  public static function createA(): A {
+    return new A();
+  }
+}
+```

tests/integration/src/classes.rs

@@ -25,6 +25,7 @@ pub fn integrate(module: &mut Module) {
     integrate_static_props(module);
     integrate_i_constants(module);
     integrate_bar_extends_foo(module, foo_class);
+    integrate_dependent_classes(module);
     #[cfg(phper_major_version = "8")]
     integrate_stringable(module);
 }
@@ -229,6 +230,35 @@ fn integrate_bar_extends_foo(module: &mut Module, foo_class: StateClass<Foo>) {
     module.add_class(cls);
 }
 
+fn integrate_dependent_classes(module: &mut Module) {
+    const A_CLS: &str = r"IntegrationTest\Dependency\A";
+    const B_CLS: &str = r"IntegrationTest\Dependency\B";
+    // Build both class entities
+    let mut a_cls = ClassEntity::new(A_CLS);
+    let mut b_cls = ClassEntity::new(B_CLS);
+
+    let a_bound_class = a_cls.bound_class();
+    let b_bound_class = b_cls.bound_class();
+
+    a_cls
+        .add_static_method("createB", Visibility::Public, move |_| {
+            let object = b_bound_class.init_object()?;
+            Ok::<_, phper::Error>(object)
+        })
+        .return_type(ReturnType::new(ReturnTypeHint::ClassEntry(B_CLS.into())));
+
+    b_cls
+        .add_static_method("createA", Visibility::Public, move |_| {
+            let object = a_bound_class.init_object()?;
+            Ok::<_, phper::Error>(object)
+        })
+        .return_type(ReturnType::new(ReturnTypeHint::ClassEntry(A_CLS.into())));
+
+    // Register both classes
+    module.add_class(a_cls);
+    module.add_class(b_cls);
+}
+
 #[cfg(phper_major_version = "8")]
 fn integrate_stringable(module: &mut Module) {
     use phper::{functions::ReturnType, types::ReturnTypeHint};

tests/integration/tests/php/classes.php

@@ -105,3 +105,9 @@ class Foo2 extends IntegrationTest\Foo {}
 $bar = new \IntegrationTest\BarExtendsFoo; //Bar should extend Foo
 $reflection = new ReflectionClass($bar);
 assert_true($reflection->isSubclassOf(IntegrationTest\Foo::class));
+
+// Test co-dependent classes
+$b = IntegrationTest\Dependency\A::createB();
+assert_true($b instanceof IntegrationTest\Dependency\B);
+$a = IntegrationTest\Dependency\B::createA();
+assert_true($a instanceof IntegrationTest\Dependency\A);