Merge branch 'main' into feature/package

Author: thekid

ChangeLog.md

@@ -3,6 +3,10 @@ XP Reflection ChangeLog
 
 ## ?.?.? / ????-??-??
 
+## 3.5.0 / ????-??-??
+
+* Merged PR #46: Add `Package::child()` to return child packages - @thekid
+
 ## 3.4.1 / 2025-08-15
 
 * Fixed PHP 8.5 compatibility, see xp-framework/test#24 - @thekid

README.md

@@ -187,6 +187,7 @@ $package->literal();       // 'org\example'
 $package->type('Fixture'); // Type instance
 $package->types();         // iterable with Type instances
 $package->parent()         // Package or NULL
+$package->child('impl')    // Child package "org.example.impl" or NULL
 $package->children();      // iterable with Package instances
 $package->classLoaders();  // iterable with lang.ClassLoader instances
 ```

src/main/php/lang/reflection/Package.class.php

@@ -54,6 +54,21 @@ public function parent() {
     return false === $p ? new Package() : new Package(substr($this->name, 0, $p));
   }
 
+  /**
+   * Returns a child package with a given name. Returns NULL if the child package
+   * does not exist.
+   *
+   * @return ?self
+   */
+  public function child(string $name) {
+    $child= ($this->name ? $this->name.'.' : '').strtr($name, '\\', '.');
+    if (ClassLoader::getDefault()->providesPackage($child)) {
+      return new self($child);
+    } else {
+      return null;
+    }
+  }
+
   /**
    * Returns this package's child packages
    *

src/test/php/lang/reflection/unittest/PackageTest.class.php

@@ -51,6 +51,27 @@ public function global_package_has_no_parent() {
     Assert::null((new Package())->parent());
   }
 
+  #[Test]
+  public function non_existant_child() {
+    Assert::null((new Package())->child('lang.non_existant_package'));
+  }
+
+  #[Test, Values(['reflection.unittest', 'reflection\\unittest'])]
+  public function resolve_child($reference) {
+    Assert::equals(
+      new Package('lang.reflection.unittest'),
+      (new Package('lang'))->child($reference)
+    );
+  }
+
+  #[Test, Values(['lang.reflection.unittest', 'lang\\reflection\\unittest'])]
+  public function toplevel_child($reference) {
+    Assert::equals(
+      new Package('lang.reflection.unittest'),
+      (new Package())->child($reference)
+    );
+  }
+
   #[Test]
   public function children() {
     Assert::equals(