class-file-reflector.php

<?php

namespace WP_Parser;

use phpDocumentor\Reflection;
use phpDocumentor\Reflection\FileReflector;

/**
 * Reflection class for a full file.
 *
 * Extends the FileReflector from phpDocumentor to parse out WordPress
 * hooks and note function relationships.
 */
class File_Reflector extends FileReflector {
	/**
	 * Attribute key used to store queued uses on PHP-Parser nodes.
	 */
	const USES_ATTRIBUTE = 'wp_parser_uses';

	/**
	 * List of elements used in global scope in this file, indexed by element type.
	 *
	 * @var array {
	 *      @type Hook_Reflector[] $hooks     The action and filters.
	 *      @type Function_Call_Reflector[] $functions The functions called.
	 * }
	 */
	public $uses = array();

	/**
	 * List of elements used in the current class scope, indexed by method.
	 *
	 * @var array[][] {@see \WP_Parser\File_Reflector::$uses}
	 */
	protected $method_uses_queue = array();

	/**
	 * Stack of classes/methods/functions currently being parsed.
	 *
	 * @see \WP_Parser\FileReflector::getLocation()
	 * @var \phpDocumentor\Reflection\BaseReflector[]
	 */
	protected $location = array();

	/**
	 * Last DocBlock associated with a non-documentable element.
	 *
	 * @var \PhpParser\Comment\Doc
	 */
	protected $last_doc = null;

	/**
	 * Whether complete fence bodies were blanked before parsing the file DocBlock.
	 *
	 * @var bool
	 */
	protected $docblock_was_sanitized = false;

	/**
	 * Indicates whether complete file-DocBlock fence bodies were blanked.
	 *
	 * @return bool Whether phpDocumentor parsed a sanitized comment.
	 */
	public function wasDocBlockSanitized() {
		return $this->docblock_was_sanitized;
	}

	/**
	 * Lets phpDocumentor identify a file DocBlock without parsing fenced PHP as tags.
	 *
	 * `FileReflector` consumes the file comment before visiting its nodes, so
	 * `export_docblock()` cannot sanitize it later. Complete fence bodies are
	 * temporarily blanked for the parent traversal and restored afterward; the
	 * untouched file contents remain available for snippet extraction.
	 *
	 * @param PHPParser_Node[] $nodes
	 *
	 * @return PHPParser_Node[]
	 */
	public function beforeTraverse( array $nodes ) {
		$source_docblock = null;
		$docblock        = null;
		$docblock_node   = null;
		$docblock_key    = null;
		$comments        = array();

		foreach ( $nodes as $node ) {
			if ( $node instanceof \PhpParser\Node\Stmt\InlineHTML ) {
				continue;
			}

			$comments = (array) $node->getAttribute( 'comments' );
			foreach ( $comments as $key => $comment ) {
				if ( $comment instanceof \PhpParser\Comment\Doc ) {
					$docblock        = $comment;
					$docblock_node   = $node;
					$docblock_key    = $key;
					$source_docblock = (string) $comment;
					break;
				}
			}
			break;
		}

		if ( null !== $source_docblock && false !== strpos( $source_docblock, '```' ) ) {
			$sanitized_docblock = sanitize_docblock_fenced_contents( $source_docblock );
			if ( $sanitized_docblock !== $source_docblock ) {
				$comments[ $docblock_key ] = new \PhpParser\Comment\Doc(
					$sanitized_docblock,
					$docblock->getStartLine(),
					$docblock->getStartFilePos(),
					$docblock->getStartTokenPos(),
					$docblock->getEndLine(),
					$docblock->getEndFilePos(),
					$docblock->getEndTokenPos()
				);
				$docblock_node->setAttribute( 'comments', $comments );
				$this->docblock_was_sanitized = true;
			}
		}

		try {
			$nodes = parent::beforeTraverse( $nodes );
		} finally {
			if ( $this->docblock_was_sanitized ) {
				$comments[ $docblock_key ] = $docblock;
				$docblock_node->setAttribute( 'comments', $comments );
			}
		}

		return $nodes;
	}

	/**
	 * Add hooks to the queue and update the node stack when we enter a node.
	 *
	 * If we are entering a class, function or method, we push it to the location
	 * stack. This is just so that we know whether we are in the file scope or not,
	 * so that hooks in the main file scope can be added to the file.
	 *
	 * We also check function calls to see if there are any actions or hooks. If
	 * there are, they are added to the file's hooks if in the global scope, or if
	 * we are in a function/method, they are added to the queue. They will be
	 * assigned to the function by leaveNode(). We also check for any other function
	 * calls and treat them similarly, so that we can export a list of functions
	 * used by each element.
	 *
	 * Finally, we pick up any docblocks for nodes that usually aren't documentable,
	 * so they can be assigned to the hooks to which they may belong.
	 *
	 * @param \PhpParser\Node $node
	 */
	public function enterNode( \PhpParser\Node $node ) {
		parent::enterNode( $node );

		switch ( $node->getType() ) {
			// Add classes, functions, and methods to the current location stack
			case 'Stmt_Class':
			case 'Stmt_Function':
			case 'Stmt_ClassMethod':
				array_push( $this->location, $node );
				break;

			// Parse out hook definitions and function calls and add them to the queue.
			case 'Expr_FuncCall':
				$function = new Function_Call_Reflector( $node, $this->context );

				// Add the call to the list of functions used in this scope.
				$this->add_use( 'functions', $function );

				if ( $this->isFilter( $node ) ) {
					if ( $this->last_doc && ! $node->getDocComment() ) {
						$node->setAttribute( 'comments', array( $this->last_doc ) );
						$this->last_doc = null;
					}

					$hook = new Hook_Reflector( $node, $this->context );

					// Add it to the list of hooks used in this scope.
					$this->add_use( 'hooks', $hook );
				}
				break;

			// Parse out method calls, so we can export where methods are used.
			case 'Expr_MethodCall':
				$method = new Method_Call_Reflector( $node, $this->context );

				// Add it to the list of methods used in this scope.
				$this->add_use( 'methods', $method );
				break;

			// Parse out method calls, so we can export where methods are used.
			case 'Expr_StaticCall':
				$method = new Static_Method_Call_Reflector( $node, $this->context );

				// Add it to the list of methods used in this scope.
				$this->add_use( 'methods', $method );
				break;

			// Parse out `new Class()` calls as uses of Class::__construct().
			case 'Expr_New':
				$method = new \WP_Parser\Method_Call_Reflector( $node, $this->context );

				// Add it to the list of methods used in this scope.
				$this->add_use( 'methods', $method );
				break;
		}

		// Pick up DocBlock from non-documentable elements so that it can be assigned
		// to the next hook if necessary. We don't do this for name nodes, since even
		// though they aren't documentable, they still carry the docblock from their
		// corresponding class/constant/function/etc. that they are the name of. If
		// we don't ignore them, we'll end up picking up docblocks that are already
		// associated with a named element, and so aren't really from a non-
		// documentable element after all.
		if (
			! $this->isNodeDocumentable( $node )
			&& 'Name' !== $node->getType()
			&& 'Name_FullyQualified' !== $node->getType()
			&& ( $docblock = $node->getDocComment() ) ) {
			$this->last_doc = $docblock;
		}
	}

	/**
	 * Assign queued hooks to functions and update the node stack on leaving a node.
	 *
	 * We can now access the function/method reflectors, so we can assign any queued
	 * hooks to them. The reflector for a node isn't created until the node is left.
	 *
	 * @param \PhpParser\Node $node
	 */
	public function leaveNode( \PhpParser\Node $node ) {

		parent::leaveNode( $node );

		switch ( $node->getType() ) {
			case 'Stmt_Property':
				/*
				 * PropertyReflector::getDocBlock() reads the declaration node, while
				 * getNode() returns one PropertyProperty child. Copy the declaration's
				 * comment to each child after it has been visited so export_docblock() can
				 * recover the raw fenced text through getNode(). Copying it earlier would
				 * make enterNode() queue the non-documentable child's comment for the next
				 * hook.
				 */
				$docblock = $node->getDocComment();
				if ( $docblock ) {
					foreach ( $node->props as $property ) {
						$comments   = (array) $property->getAttribute( 'comments' );
						$comments[] = $docblock;
						$property->setAttribute( 'comments', $comments );
					}
				}
				break;

			case 'Stmt_Class':
				$class = end( $this->classes );
				if ( ! empty( $this->method_uses_queue ) ) {
					/** @var Reflection\ClassReflector\MethodReflector $method */
					foreach ( $class->getMethods() as $method ) {
						$method_name = $method->getName();
						if ( isset( $this->method_uses_queue[ $method_name ] ) ) {
							if ( isset( $this->method_uses_queue[ $method_name ]['methods'] ) ) {
								/*
								 * For methods used in a class, set the class on the method call.
								 * That allows us to later get the correct class name for $this, self, parent.
								 */
								foreach ( $this->method_uses_queue[ $method_name ]['methods'] as $method_call ) {
									/** @var Method_Call_Reflector $method_call */
									$method_call->set_class( $class );
								}
							}

							$method->uses = $this->method_uses_queue[ $method_name ];
						}
					}
				}

				$this->method_uses_queue = array();
				array_pop( $this->location );
				break;

			case 'Stmt_Function':
				$function = array_pop( $this->location );
				$uses     = $this->get_node_uses( $function );
				if ( ! empty( $uses ) ) {
					end( $this->functions )->uses = $uses;
				}
				break;

			case 'Stmt_ClassMethod':
				$method = array_pop( $this->location );

				/*
				 * Store the list of elements used by this method in the queue. We'll
				 * assign them to the method upon leaving the class (see above).
				 */
				$uses = $this->get_node_uses( $method );
				if ( ! empty( $uses ) ) {
					$this->method_uses_queue[ (string) $method->name ] = $uses;
				}
				break;
		}
	}

	/**
	 * @param \PhpParser\Node $node
	 *
	 * @return bool
	 */
	protected function isFilter( \PhpParser\Node $node ) {
		if (
			'Name' !== $node->name->getType() &&
			'Name_FullyQualified' !== $node->name->getType()
		) {
			return false;
		}

		$calling = (string) $node->name;

		$functions = array(
			'apply_filters',
			'apply_filters_ref_array',
			'apply_filters_deprecated',
			'do_action',
			'do_action_ref_array',
			'do_action_deprecated',
		);

		return in_array( $calling, $functions );
	}

	/**
	 * @return File_Reflector
	 */
	protected function getLocation() {
		return empty( $this->location ) ? $this : end( $this->location );
	}

	/**
	 * Add a used element to the current parser scope.
	 *
	 * File-scope uses are stored on this reflector, while function and method
	 * scope uses are stored as PHP-Parser node attributes until matching
	 * reflectors are available.
	 *
	 * @param string $type
	 * @param object $reflector
	 */
	protected function add_use( $type, $reflector ) {
		$location = $this->getLocation();

		if ( $location instanceof self ) {
			$this->uses[ $type ][] = $reflector;
			return;
		}

		$uses            = $this->get_node_uses( $location );
		$uses[ $type ][] = $reflector;
		$location->setAttribute( self::USES_ATTRIBUTE, $uses );
	}

	/**
	 * Get queued uses from a PHP-Parser node.
	 *
	 * @param \PhpParser\Node $node
	 *
	 * @return array
	 */
	protected function get_node_uses( \PhpParser\Node $node ) {
		$uses = $node->getAttribute( self::USES_ATTRIBUTE, array() );

		return is_array( $uses ) ? $uses : array();
	}

	/**
	 * @param \PhpParser\Node $node
	 *
	 * @return bool
	 */
	protected function isNodeDocumentable( \PhpParser\Node $node ) {
		if ( $node instanceof \PhpParser\Node\Stmt\Expression ) {
			$node = $node->expr;
		}

		return parent::isNodeDocumentable( $node )
		|| ( $node instanceof \PhpParser\Node\Expr\FuncCall
			&& $this->isFilter( $node ) );
	}
}