Add some more utility methods.

Author: johnbillion

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();
 	}
 
 	/**

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 );
 	}
 
 	/**

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,26 +31,66 @@ 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 );
 		self::assertSame( 'wp_tag_cloud', $hook->getName() );
 	}
 
 	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] );
+	}
 }