/**

public const HOOK_FUNCTIONS = array(

'apply_filters',

'apply_filters_deprecated',

'apply_filters_ref_array',

'do_action',

'do_action_deprecated',

'do_action_ref_array',

);

/**

public const FILTER_FUNCTIONS = array(

'apply_filters',

'apply_filters_deprecated',

'apply_filters_ref_array',

);

/**

private const SCANNED_DIRECTORIES = array(

'wp-admin',

'wp-includes',

'wp-content/themes',

);

/**

public const PROBLEM_FILE_MISSING = 'fileMissing';

/**

public const PROBLEM_HOOK_MISSING = 'hookMissing';

/**

private const REFERENCE_PATTERN = '#This (?:filter|action) is documented in (\S+)#';

/**

protected FileTypeMapper $fileTypeMapper;

/**

private array $fileHookDocs = array();

/**

private string $wordpressRoot;

/**

private string $canonicalWordpressRoot;

/**

public function __construct( FileTypeMapper $file_type_mapper, ?string $wordpress_root = null ) {

$this->fileTypeMapper = $file_type_mapper;

$this->wordpressRoot = rtrim( $wordpress_root ?? dirname( __DIR__, 2 ) . '/src', '/' );

$canonical_root = realpath( $this->wordpressRoot );

$this->canonicalWordpressRoot = false === $canonical_root ? $this->wordpressRoot : $canonical_root;

}

/**

public function getReferencedHookDocsHash(): string {

$docs = array();

foreach ( $this->getScannedFiles() as $file ) {

$code = file_get_contents( $file );

if ( false === $code || ! str_contains( $code, 'is documented in' ) ) {

continue;

}

if ( ! preg_match_all( self::REFERENCE_PATTERN, $code, $matches ) ) {

continue;

}

foreach ( $matches[1] as $reference_path ) {

$target = $this->resolveReferencePath( $file, $reference_path );

if ( null === $target ) {

continue;

}

// Key on the path relative to the WordPress root so the hash does not

// depend on where the checkout lives.

$key = $this->getRootRelativePath( $target );

$docs[ $key ] ??= $this->getHookDocs( $target );

}

}

ksort( $docs );

return md5( (string) json_encode( $docs ) );

}

/**

private function getScannedFiles(): array {

$files = array();

foreach ( self::SCANNED_DIRECTORIES as $directory ) {

$path = $this->wordpressRoot . '/' . $directory;

if ( ! is_dir( $path ) ) {

continue;

}

$iterator = new RecursiveIteratorIterator(

new RecursiveDirectoryIterator( $path, FilesystemIterator::SKIP_DOTS )

);

foreach ( $iterator as $file ) {

if ( $file instanceof SplFileInfo && $file->isFile() && 'php' === strtolower( $file->getExtension() ) ) {

$files[] = $file->getPathname();

}

}

}

$root_files = glob( $this->wordpressRoot . '/*.php' );

if ( is_array( $root_files ) ) {

$files = array_merge( $files, $root_files );

}

return $files;

}

/**

private function getRootRelativePath( string $path ): string {

$prefix = $this->canonicalWordpressRoot . '/';

return str_starts_with( $path, $prefix ) ? substr( $path, strlen( $prefix ) ) : $path;

}

/**

public function getHookDoc( FuncCall $function_call, Scope $scope ): ?array {

$comment = self::getNullableNodeComment( $function_call );

if ( null === $comment ) {

return null;

}

$text = $comment->getText();

// A docblock written at the call site documents the hook in place.

if ( ! preg_match( self::REFERENCE_PATTERN, $text, $matches ) ) {

$resolved = $this->resolveInlineDocBlock( $text, $scope );

return array(

'kind' => 'inline',

'resolved' => $resolved,

'paramCount' => self::countParamTags( $resolved ),

'problem' => null,

);

}

$hook_doc = array(

'kind' => 'reference',

'resolved' => null,

'paramCount' => null,

'problem' => null,

);

// Without an identifiable hook name there is nothing to look up in the

// referenced file, and so nothing to report either.

$matcher = self::getHookNameMatcher( $function_call );

if ( null === $matcher ) {

return $hook_doc;

}

$reference_path = $matches[1];

$target_file = $this->resolveReferencePath( $scope->getFile(), $reference_path );

// The referenced file could not be located up the directory tree.

if ( null === $target_file ) {

$hook_doc['problem'] = array(

'path' => $reference_path,

'hook' => self::getHookNameDisplay( $function_call ),

'problem' => self::PROBLEM_FILE_MISSING,

);

return $hook_doc;

}

$doc_text = $this->findHookDoc( $target_file, $matcher );

if ( null === $doc_text ) {

$hook_doc['problem'] = array(

'path' => $reference_path,

'hook' => self::getHookNameDisplay( $function_call ),

'problem' => self::PROBLEM_HOOK_MISSING,

);

return $hook_doc;

}

// Resolve the canonical docblock in the global namespace, with no file

// context. Hook docblocks describe global/plain types (e.g. string[],

// WP_REST_Response), so the referenced file's `use` imports are not needed.

// Passing the referenced file here would also re-enter PHPStan's name-scope

// builder while that file is itself being analyzed, which makes

// getResolvedPhpDoc return an empty docblock (NameScopeAlreadyBeingCreated).

$resolved = $this->fileTypeMapper->getResolvedPhpDoc( null, null, null, null, $doc_text );

$hook_doc['resolved'] = $resolved;

$hook_doc['paramCount'] = self::countParamTags( $resolved );

return $hook_doc;

}

/**

public function getNullableHookDocBlock( FuncCall $function_call, Scope $scope ): ?ResolvedPhpDocBlock {

$hook_doc = $this->getHookDoc( $function_call, $scope );

return null === $hook_doc ? null : $hook_doc['resolved'];

}

/**

private function resolveInlineDocBlock( string $text, Scope $scope ): ResolvedPhpDocBlock {

$class_reflection = $scope->getClassReflection();

$trait_reflection = $scope->getTraitReflection();

return $this->fileTypeMapper->getResolvedPhpDoc(

$scope->getFile(),

( $scope->isInClass() && null !== $class_reflection ) ? $class_reflection->getName() : null,

( $scope->isInTrait() && null !== $trait_reflection ) ? $trait_reflection->getName() : null,

$scope->getFunctionName(),

$text

);

}

/**

private static function countParamTags( ResolvedPhpDocBlock $resolved_php_doc ): int {

$count = 0;

foreach ( $resolved_php_doc->getPhpDocNodes() as $php_doc_node ) {

$count += count( $php_doc_node->getParamTagValues() );

}

return $count;

}

/**

public static function isFilterMissingParamDocs( FuncCall $function_call, array $hook_doc ): bool {

if ( 0 !== $hook_doc['paramCount'] ) {

return false;

}

return $function_call->name instanceof Name

&& in_array( $function_call->name->toString(), self::FILTER_FUNCTIONS, true );

}

/**

public static function hasIdentifiableHookName( FuncCall $function_call ): bool {

$args = $function_call->getArgs();

if ( ! isset( $args[0] ) ) {

return false;

}

$value = $args[0]->value;

if ( $value instanceof String_ ) {

return true;

}

return null !== self::buildHookNamePattern( $value );

}

/**

private function findHookDoc( string $file, array $matcher ): ?string {

$docs = $this->getHookDocs( $file );

if ( 'literal' === $matcher['kind'] ) {

$name = $matcher['value'];

if ( isset( $docs['exact'][ $name ] ) ) {

return $docs['exact'][ $name ];

}

// A literal name may be an instance of a dynamic canonical hook

// (e.g. "index_template_hierarchy" matching "{$type}_template_hierarchy").

// The most specifically anchored match wins, so a name is not attributed

// to a loosely anchored hook that merely happens to match it as well.

$best = null;

$anchor_len = -1;

foreach ( $docs['patterns'] as $pattern ) {

$literal_len = strlen( $pattern['literal'] );

if ( $literal_len <= $anchor_len || ! self::isAnchorableLiteral( $pattern['literal'] ) ) {

continue;

}

if ( preg_match( $pattern['regex'], $name ) ) {

$best = $pattern['text'];

$anchor_len = $literal_len;

}

}

return $best;

}

// A dynamic referencing name matches the same dynamic canonical (identical

// regex), or a literal canonical the pattern covers.

$regex = $matcher['value'];

foreach ( $docs['patterns'] as $pattern ) {

if ( $pattern['regex'] === $regex ) {

return $pattern['text'];

}

}

// Covering a literal canonical is only meaningful for a pattern anchored

// specifically enough to identify a hook.

if ( ! self::isAnchorableLiteral( $matcher['literal'] ) ) {

return null;

}

foreach ( $docs['exact'] as $name => $text ) {

if ( preg_match( $regex, $name ) ) {

return $text;

}

}

return null;

}

/**

private function getHookDocs( string $file ): array {

$this->fileHookDocs[ $file ] ??= self::loadHookDocs( $file );

return $this->fileHookDocs[ $file ];

}

/**

private static function loadHookDocs( string $file ): array {

$empty = array(

'exact' => array(),

'patterns' => array(),

);

if ( ! is_file( $file ) || ! is_readable( $file ) ) {

return $empty;

}

$code = file_get_contents( $file );

if ( false === $code ) {

return $empty;

}

return self::parseHookDocs( $code );

}

/**

private static function parseHookDocs( string $code ): array {

$docs = array(

'exact' => array(),

'patterns' => array(),

);

// Source that cannot be parsed documents nothing this can read, and must not stop

// the analysis: a file is temporarily incomplete while it is being edited, and may

// use syntax the host PHP version does not know. Collecting the parse errors

// rather than throwing keeps the hooks documented ahead of the error wherever the

// parser can recover, and yields none where it cannot.

$parser = ( new ParserFactory() )->createForHostVersion();

try {

$stmts = $parser->parse( $code, new Collecting() );

} catch ( PhpParserError $parse_error ) {

return $docs;

}

if ( null === $stmts ) {

return $docs;

}

/*

$traverser = new NodeTraverser();

$traverser->addVisitor( new HashNotationVisitor() );

$traverser->addVisitor( new HookDocsVisitor() );

$stmts = $traverser->traverse( $stmts );

$seen = array();

$calls = ( new NodeFinder() )->findInstanceOf( $stmts, FuncCall::class );

foreach ( $calls as $call ) {

if ( ! $call instanceof FuncCall || ! $call->name instanceof Name ) {

continue;

}

if ( ! in_array( $call->name->toString(), self::HOOK_FUNCTIONS, true ) ) {

continue;

}

$args = $call->getArgs();

if ( ! isset( $args[0] ) ) {

continue;

}

$doc = $call->getAttribute( 'latestDocComment' );

// Skip reference comments so only the canonical documentation counts.

if ( ! $doc instanceof Doc || preg_match( self::REFERENCE_PATTERN, $doc->getText() ) ) {

continue;

}

$name_expr = $args[0]->value;

if ( $name_expr instanceof String_ ) {

$docs['exact'][ $name_expr->value ] ??= $doc->getText();

continue;

}

$pattern = self::buildHookNamePattern( $name_expr );

if ( null !== $pattern && ! isset( $seen[ $pattern['regex'] ] ) ) {

$seen[ $pattern['regex'] ] = true;

$docs['patterns'][] = array(

'regex' => $pattern['regex'],

'literal' => $pattern['literal'],

'text' => $doc->getText(),

);

}

}

return $docs;

}

/**

private static function buildHookNamePattern( Expr $expr ): ?array {

$parts = self::hookNameRegexParts( $expr );

if ( null === $parts || '' === $parts[1] ) {

return null;

}

return array(

'regex' => '#^' . $parts[0] . '$#',

'literal' => $parts[1],

);

}

/**

private static function isAnchorableLiteral( string $literal ): bool {

return '' !== trim( $literal, "-_ \t\n\r\0\x0B" );

}

/**

private static function hookNameRegexParts( Expr $expr ): ?array {

if ( $expr instanceof String_ ) {

return array( preg_quote( $expr->value, '#' ), $expr->value );

}

if ( $expr instanceof Concat ) {

$left = self::hookNameRegexParts( $expr->left );

$right = self::hookNameRegexParts( $expr->right );

if ( null === $left || null === $right ) {

return null;

}

return array( $left[0] . $right[0], $left[1] . $right[1] );

}

if ( $expr instanceof InterpolatedString ) {

$fragment = '';

$literal = '';

foreach ( $expr->parts as $part ) {

if ( $part instanceof InterpolatedStringPart ) {

$fragment .= preg_quote( $part->value, '#' );

$literal .= $part->value;

} else {

$fragment .= '.+';

}

}

return array( $fragment, $literal );

}

// Variables, property fetches, etc.: a wildcard with no literal anchor.

return array( '.+', '' );

}

/**

private function resolveReferencePath( string $current_file, string $reference_path ): ?string {

$reference_path = ltrim( $reference_path, '/' );

$dir = dirname( $current_file );

while ( $dir === $this->wordpressRoot || str_starts_with( $dir, $this->wordpressRoot . '/' ) ) {

$target = $this->resolveWithinRoot( $dir . '/' . $reference_path );

if ( null !== $target ) {

return $target;

}

// The root has just been tested, so the walk is done.

if ( $dir === $this->wordpressRoot ) {

return null;

}

$dir = dirname( $dir );

}

// The file holding the comment is not in the tree, so resolve against the root.

return $this->resolveWithinRoot( $this->wordpressRoot . '/' . $reference_path );

}

/**

private function resolveWithinRoot( string $candidate ): ?string {

if ( ! is_file( $candidate ) ) {

return null;

}

$canonical = realpath( $candidate );

if ( false === $canonical ) {

return null;

}

return str_starts_with( $canonical, $this->canonicalWordpressRoot . '/' ) ? $canonical : null;

}

/**

private static function getHookNameMatcher( FuncCall $call ): ?array {

$args = $call->getArgs();

if ( ! isset( $args[0] ) ) {

return null;

}

$expr = $args[0]->value;

if ( $expr instanceof String_ ) {

return array(

'kind' => 'literal',

'value' => $expr->value,

'literal' => $expr->value,

);

}

$pattern = self::buildHookNamePattern( $expr );

if ( null !== $pattern ) {

return array(

'kind' => 'pattern',

'value' => $pattern['regex'],

'literal' => $pattern['literal'],

);

}

return null;

}

/**

public static function getHookNameDisplay( FuncCall $call ): string {

$args = $call->getArgs();

if ( ! isset( $args[0] ) ) {

return '';

}

return self::renderHookName( $args[0]->value );

}

/**

private static function renderHookName( Expr $expr ): string {

if ( $expr instanceof String_ ) {

return $expr->value;

}

if ( $expr instanceof Concat ) {

return self::renderHookName( $expr->left ) . self::renderHookName( $expr->right );

}

if ( $expr instanceof InterpolatedString ) {

$out = '';

foreach ( $expr->parts as $part ) {

if ( $part instanceof InterpolatedStringPart ) {

$out .= $part->value;

} elseif ( $part instanceof Variable && is_string( $part->name ) ) {

$out .= '{$' . $part->name . '}';

} else {

$out .= '{...}';

}

}

return $out;

}

if ( $expr instanceof Variable && is_string( $expr->name ) ) {

return '$' . $expr->name;

}

return '...';

}

/**

private static function getNullableNodeComment( FuncCall $node ): ?Doc {

/** @var Doc|null $doc */

$doc = $node->getAttribute( 'latestDocComment' );

return $doc;

}