[POC] resolving hooks in workpress code

.phpdoc/template/file.html.twig

@@ -0,0 +1,23 @@
+{% extends 'base.html.twig' %}
+
+{% block content %}
+    {% include('components/breadcrumbs.html.twig') %}
+
+    <article class="phpdocumentor-element -file">
+        {{ include('components/file-title.html.twig') }}
+        {{ include('components/element-header.html.twig') }}
+
+        {{ include('components/constants.html.twig') }}
+        {{ include('components/functions.html.twig') }}
+
+        <h2 class="phpdocumentor-content__title">Hooks</h2>
+        <ul>
+        {% for action in node.metadata.wp_hooks.actions %}
+            <li>
+                <h3>{{ action.name }}</h3>
+                <section class="phpdocumentor-description">{{ action.docblock.description|markdown }}</section>
+            </li>
+        {% endfor %}
+        </ul>
+    </article>
+{% endblock %}

composer.json

@@ -24,7 +24,8 @@
     "repositories": [
         { "type": "path", "url": "incubator/guides" },
         { "type": "path", "url": "incubator/guides-restructured-text" },
-        { "type": "path", "url": "incubator/guides-markdown" }
+        { "type": "path", "url": "incubator/guides-markdown" },
+        { "type": "path", "url": "incubator/wordpress" }
     ],
     "require": {
         "php": ">=7.2.5||^8.0",
@@ -53,6 +54,7 @@
         "phpdocumentor/reflection-common": "^2.0",
         "phpdocumentor/reflection-docblock": "^5.0",
         "phpdocumentor/type-resolver": "^1.0",
+        "phpdocumentor/wordpress": "*@dev",
         "psr/cache": "^1.0",
         "psr/log": "^1.1",
         "symfony/cache": "^5.0",

config/services.yaml

@@ -3,6 +3,7 @@ imports:
   - { resource: 'reflection.yaml' }
   - { resource: 'stages.yaml' }
   - { resource: 'guides.yaml' }
+  - { resource: 'wordpress.yml' }
 
 parameters:
     linker.substitutions:

config/wordpress.yml

@@ -0,0 +1,15 @@
+###################################################################################
+## Wordpress - EXPERIMENTAL ##########################################################
+###################################################################################
+
+services:
+  _defaults:
+    autowire: true
+    autoconfigure: true
+    public: false
+  _instanceof:
+    phpDocumentor\Reflection\Php\ProjectFactoryStrategy:
+      tags: ['phpdoc.reflection.strategy']
+
+  phpDocumentor\Wordpress\:
+    resource: '%kernel.project_dir%/vendor/phpdocumentor/wordpress/src'

incubator/wordpress/.gitignore

@@ -0,0 +1 @@
+vendor/*

incubator/wordpress/EXPERIMENTAL.md

@@ -0,0 +1,4 @@
+**EXPERIMENTAL**: Anything regarding Guide generation, in this folder or elsewhere, is to be considered experimental and
+prone to be changed or removed without notice or consideration for BC.
+
+This is a follow-up to an earlier POC and can, at best, seen as an incubator project.

incubator/wordpress/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2010 Mike van Riel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

incubator/wordpress/composer.json

@@ -0,0 +1,22 @@
+{
+    "name": "phpdocumentor/wordpress",
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://www.phpdoc.org",
+    "autoload": {
+        "psr-4": {
+            "phpDocumentor\\Wordpress\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "phpDocumentor\\Wordpress\\": [
+                "tests/unit/"
+            ]
+        }
+    },
+    "minimum-stability": "stable",
+    "require": {
+        "php": ">=7.2.5||^8.0"
+    }
+}

incubator/wordpress/src/Reflection/Php/Action.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Wordpress\Reflection\Php;
+
+use phpDocumentor\Reflection\DocBlock;
+
+final class Action
+{
+    /**
+     * @var string
+     */
+    private $name;
+
+    /**
+     * @var DocBlock
+     */
+    private $docBlock;
+
+    public function __construct(string $name, DocBlock $docBlock)
+    {
+        $this->name = $name;
+        $this->docBlock = $docBlock;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getDocBlock(): DocBlock
+    {
+        return $this->docBlock;
+    }
+}

incubator/wordpress/src/Reflection/Php/Factory/Action.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Wordpress\Reflection\Php\Factory;
+
+use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\DocBlockFactoryInterface;
+use phpDocumentor\Reflection\Metadata\MetaDataContainer;
+use phpDocumentor\Reflection\Php\Factory\AbstractFactory;
+use phpDocumentor\Reflection\Php\Factory\ContextStack;
+use phpDocumentor\Reflection\Php\StrategyContainer;
+use phpDocumentor\Wordpress\Reflection\Php\Action as ActionElement;
+use phpDocumentor\Wordpress\Reflection\Php\Hooks;
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\PrettyPrinter\Standard as PrettyPrinter;
+
+final class Action extends AbstractFactory
+{
+    private const ACTION_NAMES = [
+        'do_action',
+        'do_action_ref_array',
+        'do_action_deprecated',
+    ];
+    /**
+     * @var PrettyPrinter
+     */
+    private $valuePrinter;
+
+    public function __construct(DocBlockFactoryInterface $docBlockFactory, PrettyPrinter $valuePrinter)
+    {
+        parent::__construct($docBlockFactory);
+        $this->valuePrinter = $valuePrinter;
+    }
+
+
+    public function matches(ContextStack $context, object $object): bool
+    {
+        return $object instanceof FuncCall && $context->peek() instanceof MetaDataContainer && in_array($object->name->toString(), self::ACTION_NAMES);
+    }
+
+    public function doCreate(ContextStack $context, object $object, StrategyContainer $strategies): void
+    {
+        /** @var MetaDataContainer $container */
+        $container = $context->peek();
+
+        $hooks = new Hooks();
+        $existing = $container->getMetadata()[$hooks->key()] ?? $hooks;
+        if ($existing === $hooks) {
+            $container->addMetadata($hooks);
+        }
+
+        $existing->addAction(
+            new ActionElement(
+                $this->valuePrinter->prettyPrintExpr($object->args[0]->value),
+                $this->createDocBlock($object->getDocComment(), $context->getTypeContext()) ?? new DocBlock()
+            )
+        );
+    }
+}

incubator/wordpress/src/Reflection/Php/Factory/Expression.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Wordpress\Reflection\Php\Factory;
+
+use phpDocumentor\Reflection\Php\Factory;
+use phpDocumentor\Reflection\Php\Factory\ContextStack;
+use phpDocumentor\Reflection\Php\ProjectFactoryStrategy;
+use phpDocumentor\Reflection\Php\StrategyContainer;
+
+final class Expression implements ProjectFactoryStrategy
+{
+    public function matches(ContextStack $context, object $object): bool
+    {
+        return $object instanceof \PhpParser\Node\Stmt\Expression;
+    }
+
+    public function create(ContextStack $context, object $object, StrategyContainer $strategies): void
+    {
+        $strategies->findMatching($context, $object->expr)->create($context, $object->expr, $strategies);
+    }
+}

incubator/wordpress/src/Reflection/Php/Hooks.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Wordpress\Reflection\Php;
+
+use phpDocumentor\Reflection\Metadata\Metadata;
+
+final class Hooks implements Metadata
+{
+    private $actions = [];
+
+    public function key(): string
+    {
+        return 'wp_hooks';
+    }
+
+    public function addAction(Action $action): void
+    {
+        $this->actions[] = $action;
+    }
+
+    /** @return Action[] */
+    public function getActions(): array
+    {
+        return $this->actions;
+    }
+}