$this->redirect(['prefix' => 'Admin', 'controller' => 'Users', 'action' => 'profile']);

use App\Controller\Admin\UsersController;

$this->redirect([
    'plugin' => null,
    'prefix' => 'Admin',
    'controller' => ControllerNameExtractor::extract(UsersController::class),
    /** @see UsersController::index() */
    'action' => 'index',
]);

$destination = [
    'plugin' => null,
    'prefix' => 'Participant',
    'controller' => ControllerNameExtractor::extract(self::class),
    /** @see ProfileController::index() */
    'action' => 'index',
];

$this->Html->link(__d('our-project-domain', 'Categories'), [
    'plugin' => null,
    'prefix' => 'Admin',
    'controller' => ControllerNameExtractor::extract(CategoriesController::class),
    /** @see CategoriesController::index() */
    'action' => 'index',
    '?' => ['type' => 'news'],
], ['class' => 'btn btn-light', 'escape' => false]);

echo $this->Html->link('<i class="ti ti-pencil"></i>' . __d('our-project-domain', 'Edit'), ['plugin' => null, 'prefix' => 'Admin', 'controller' => ControllerNameExtractor::extract(NewsController::class), /** @see NewsController::edit() */ 'action' => 'edit', $newsEntity->id], ['class' => 'dropdown-item']);

<?php

declare(strict_types=1);

namespace App\Utility;

/**
 * Controller Name Extractor
 *
 * Utility class for extracting controller base names from FQDN class strings.
 */
final readonly class ControllerNameExtractor
{
    /**
     * Extracts the base name of a controller class by removing the "Controller" suffix.
     *
     * @param class-string $controllerClass The FQDN of the controller (e.g., `"App\Controller\UsersController"`)
     *
     * @return string The base name of the controller without the `"Controller"` suffix (e.g., `"Users"`)
     */
    public static function extract(string $controllerClass): string
    {
        // Get short class name from FQDN via string manipulation (no autoloading)
        $pos = strrpos($controllerClass, '\\');
        $shortName = $pos !== false ? substr($controllerClass, $pos + 1) : $controllerClass;

        // Remove "Controller" suffix if present
        if (str_ends_with($shortName, 'Controller')) {
            return substr($shortName, 0, -10);
        }

        return $shortName;
    }
}

<?php

declare(strict_types=1);

namespace App\PHPStan;

use App\Utility\ControllerNameExtractor;
use PhpParser\Node;
use PhpParser\Node\ArrayItem;
use PhpParser\Node\Expr\Array_;
use PhpParser\Node\Expr\StaticCall;
use PhpParser\Node\Identifier;
use PhpParser\Node\Name;
use PhpParser\Node\Scalar\String_;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;
use PHPStan\Rules\RuleError;
use PHPStan\Rules\RuleErrorBuilder;
use PHPStan\ShouldNotHappenException;

use function in_array;
use function sprintf;
use function str_contains;
use function ucfirst;

/**
 * @implements Rule<Array_>
 */
class RouteArrayConventionRule implements Rule
{
    private const array REQUIRED_KEYS = ['plugin', 'prefix', 'action'];

    public function getNodeType(): string
    {
        return Array_::class;
    }

    /** @return list<\PHPStan\Rules\IdentifierRuleError> */
    public function processNode(Node $node, Scope $scope): array
    {
        if (!$node instanceof Array_) {
            return [];
        }

        $itemsByKey = $this->indexByStringKey($node->items);
        if (!isset($itemsByKey['controller'])) {
            return [];
        }

        $errors = [];

        foreach (self::REQUIRED_KEYS as $required) {
            if (!isset($itemsByKey[$required])) {
                $errors[] = $this->error(
                    sprintf(
                        'CakePHP route array is missing the explicit "%s" key. '
                        . 'Set plugin / prefix / controller / action all explicitly so '
                        . 'CakePHP does not inherit a slot from the current request context.',
                        $required,
                    ),
                    'missing' . ucfirst($required),
                );
            }
        }

        $controllerValue = $itemsByKey['controller']->value;
        if (!$this->isControllerNameExtractorCall($controllerValue)) {
            $errors[] = $this->error(
                'CakePHP route array "controller" must use '
                . 'ControllerNameExtractor::extract(SomeController::class). '
                . 'String literals break IDE rename / find-usages and let '
                . 'typos hide until runtime.',
                'controllerNotExtractor',
            );
        }

        if (isset($itemsByKey['action']) && !$this->hasSeeAnnotation($itemsByKey['action'])) {
            $errors[] = $this->error(
                'CakePHP route array "action" key must be preceded by a '
                . '/** @see ControllerClass::method() */ docblock so the IDE '
                . 'can navigate from the action string back to the source. '
                . 'Place the docblock on the line directly above the '
                . '`\'action\' => \'…\',` entry.',
                'actionMissingSeeDoc',
            );
        }

        return $errors;
    }

    /**
     * @param array<int, ArrayItem|null> $items
     *
     * @return array<string, ArrayItem>
     */
    private function indexByStringKey(array $items): array
    {
        $result = [];
        foreach ($items as $item) {
            if ($item === null) {
                continue;
            }
            if (!$item->key instanceof String_) {
                continue;
            }
            $result[$item->key->value] = $item;
        }

        return $result;
    }

    private function isControllerNameExtractorCall(Node $value): bool
    {
        if (!$value instanceof StaticCall) {
            return false;
        }
        if (!$value->class instanceof Name) {
            return false;
        }
        if (!$value->name instanceof Identifier) {
            return false;
        }

        $className = $value->class->toString();
        $allowed = [
            'ControllerNameExtractor',
            'App\Utility\ControllerNameExtractor',
            ControllerNameExtractor::class,
        ];

        return in_array($className, $allowed, true) && $value->name->name === 'extract';
    }

    private function hasSeeAnnotation(ArrayItem $item): bool
    {
        foreach ($item->getComments() as $comment) {
            if (str_contains($comment->getText(), '@see')) {
                return true;
            }
        }

        return false;
    }

    /**
     * Native return stays the broader `RuleError` so PHPStorm — which can't
     * follow `RuleErrorBuilder`'s fluent state to see that `build()` narrows
     * once `identifier()` is set — doesn't warn. The `return` narrows to
     * `IdentifierRuleError` for PHPStan, as `Rule::processNode()`'s
     * `list<IdentifierRuleError>` contract demands at level 8.
     *
     * @return \PHPStan\Rules\IdentifierRuleError
     *
     * @noinspection PhpUnhandledExceptionInspection (build() declares ShouldNotHappenException; safe here)
     *
     * @throws ShouldNotHappenException
     */
    private function error(string $message, string $identifierSuffix): RuleError
    {
        return RuleErrorBuilder::message($message)
            ->identifier('ourProjectName.routeArray.' . $identifierSuffix)
            ->build();
    }
}

$this->Html->link('Profile', ['controller' => 'Users', 'action' => 'view', $id]);