From 407b6521adbced11ab0249f249124130dd9705b5 Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Sun, 8 Sep 2024 21:07:05 +0100
Subject: [PATCH] Add some more utility methods.

---
 src/Doc.php                 | 26 ++++++++++++++-
 src/Tags.php                | 44 ++++++++++++++++++++++---
 tests/phpunit/HooksTest.php | 65 ++++++++++++++++++++++++++++++++-----
 3 files changed, 122 insertions(+), 13 deletions(-)

diff --git a/src/Doc.php b/src/Doc.php
index 372d778..c6696af 100644
--- a/src/Doc.php
+++ b/src/Doc.php
@@ -43,12 +43,36 @@ public function getTags(): Tags {
 		return $this->tags;
 	}
 
+	/**
+	 * @return array<int, Tag>
+	 * @phpstan-return list<Tag>
+	 */
+	public function getTagsByType( string $type ): array {
+		return $this->tags->getByType( $type );
+	}
+
 	/**
 	 * @return array<int, Tag>
 	 * @phpstan-return list<Tag>
 	 */
 	public function getParams(): array {
-		return $this->getTags()->getParams();
+		return $this->tags->getParams();
+	}
+
+	public function getReturnTypeString(): ?string {
+		return $this->tags->getReturnTypeString();
+	}
+
+	/**
+	 * @return ?array<int, string>
+	 * @phpstan-return ?list<string>
+	 */
+	public function getReturnTypes(): ?array {
+		return $this->tags->getReturnTypes();
+	}
+
+	public function countParams(): int {
+		return $this->tags->countParams();
 	}
 
 	/**
diff --git a/src/Tags.php b/src/Tags.php
index 2b54dae..a55b0e4 100644
--- a/src/Tags.php
+++ b/src/Tags.php
@@ -28,6 +28,10 @@ public function count(): int {
 		return count( $this->tags );
 	}
 
+	public function countParams(): int {
+		return count( $this->getParams() );
+	}
+
 	/**
 	 * @return \Traversable<int, Tag>
 	 */
@@ -48,15 +52,47 @@ public function all(): array {
 	 * @phpstan-return list<Tag>
 	 */
 	public function getParams(): array {
-		$params = [];
+		return $this->getByType( 'param' );
+	}
+
+	/**
+	 * @return array<int, Tag>
+	 * @phpstan-return list<Tag>
+	 */
+	public function getByType( string $type ): array {
+		$tags = [];
+
+		foreach ( $this->tags as $tag ) {
+			if ( $tag->getName() === $type ) {
+				$tags[] = $tag;
+			}
+		}
+
+		return $tags;
+	}
 
-		foreach ( $this as $tag ) {
+	/**
+	 * @return ?array<int, string>
+	 * @phpstan-return ?list<string>
+	 */
+	public function getReturnTypes(): ?array {
+		foreach ( $this->tags as $tag ) {
 			if ( $tag->getName() === 'param' ) {
-				$params[] = $tag;
+				return $tag->getTypes();
 			}
 		}
 
-		return $params;
+		return null;
+	}
+
+	public function getReturnTypeString(): ?string {
+		$returnTypes = $this->getReturnTypes();
+
+		if ( $returnTypes === null ) {
+			return null;
+		}
+
+		return implode( '|', $returnTypes );
 	}
 
 	/**
diff --git a/tests/phpunit/HooksTest.php b/tests/phpunit/HooksTest.php
index dd3d31d..74e5ad6 100644
--- a/tests/phpunit/HooksTest.php
+++ b/tests/phpunit/HooksTest.php
@@ -6,6 +6,7 @@
 use PHPUnit\Framework\TestCase;
 use WPHooks\Hook;
 use WPHooks\Hooks;
+use WPHooks\Tag;
 
 final class HooksTest extends TestCase {
 	/**
@@ -30,10 +31,9 @@ public function testErrorThrownWhenFileDoesNotExist(): void {
 	}
 
 	public function testCanFindByName(): void {
-		$file = $this->dataCoreFiles()['filters'][0];
-		$filters = Hooks::fromFile( $file );
-		$hook = $filters->find( 'wp_tag_cloud' );
-		$includes = $filters->includes( 'wp_tag_cloud' );
+		$hooks = $this->getFilters();
+		$hook = $hooks->find( 'wp_tag_cloud' );
+		$includes = $hooks->includes( 'wp_tag_cloud' );
 
 		self::assertTrue( $includes );
 		self::assertInstanceOf( Hook::class, $hook );
@@ -41,15 +41,56 @@ public function testCanFindByName(): void {
 	}
 
 	public function testFindByUnknownNameReturnsNull(): void {
-		$file = $this->dataCoreFiles()['filters'][0];
-		$filters = Hooks::fromFile( $file );
-		$hook = $filters->find( 'this_does_not_exist' );
-		$includes = $filters->includes( 'this_does_not_exist' );
+		$hooks = $this->getFilters();
+		$hook = $hooks->find( 'this_does_not_exist' );
+		$includes = $hooks->includes( 'this_does_not_exist' );
 
 		self::assertFalse( $includes );
 		self::assertNull( $hook );
 	}
 
+	public function testCanGetReturnTypes(): void {
+		$hooks = $this->getFilters();
+		$hook = $hooks->find( 'wp_tag_cloud' );
+
+		$returnTypes = $hook->getDoc()->getReturnTypes();
+		$expected = [
+			'string',
+			'string[]',
+		];
+
+		self::assertSame( $expected, $returnTypes );
+	}
+
+	public function testCanGetReturnTypeString(): void {
+		$hooks = $this->getFilters();
+		$hook = $hooks->find( 'wp_tag_cloud' );
+
+		$returnType = $hook->getDoc()->getReturnTypeString();
+
+		self::assertSame( 'string|string[]', $returnType );
+	}
+
+	public function testCanGetParams(): void {
+		$hooks = $this->getFilters();
+		$hook = $hooks->find( 'wp_tag_cloud' );
+
+		$params = $hook->getDoc()->getParams();
+
+		self::assertCount( 2, $params );
+		self::assertInstanceOf( Tag::class, $params[0] );
+		self::assertInstanceOf( Tag::class, $params[1] );
+	}
+
+	public function testCanCountParams(): void {
+		$hooks = $this->getFilters();
+		$hook = $hooks->find( 'wp_tag_cloud' );
+
+		$count = $hook->getDoc()->countParams();
+
+		self::assertSame( 2, $count );
+	}
+
 	/**
 	 * @return array<string, array<int, string>>
 	 * @phpstan-return array{
@@ -93,4 +134,12 @@ public function dataCoreFiles(): array {
 			],
 		];
 	}
+
+	private function getFilters(): Hooks {
+		return Hooks::fromFile( $this->dataCoreFiles()['filters'][0] );
+	}
+
+	private function getActions(): Hooks {
+		return Hooks::fromFile( $this->dataCoreFiles()['actions'][0] );
+	}
 }