From a63985a4bbe2a8514d3a555cf110c77e9d21037e Mon Sep 17 00:00:00 2001 From: Christophe Coevoet Date: Fri, 13 Jun 2025 16:45:48 +0200 Subject: [PATCH] Restrict the API surface with internal and final tags Those methods still need to consider BC impact for now until the next major version, but this will reduce the public API surface in the future. --- src/Knp/Menu/Factory/CoreExtension.php | 3 +++ .../Integration/Symfony/RoutingExtension.php | 2 ++ .../Iterator/CurrentItemFilterIterator.php | 2 ++ .../Iterator/DisplayedItemFilterIterator.php | 2 ++ .../Menu/Iterator/RecursiveItemIterator.php | 2 ++ src/Knp/Menu/Loader/ArrayLoader.php | 2 ++ src/Knp/Menu/Loader/NodeLoader.php | 3 +++ src/Knp/Menu/Matcher/Matcher.php | 2 ++ src/Knp/Menu/Matcher/Voter/RegexVoter.php | 2 ++ src/Knp/Menu/Matcher/Voter/RouteVoter.php | 2 ++ src/Knp/Menu/Matcher/Voter/UriVoter.php | 2 ++ src/Knp/Menu/MenuFactory.php | 2 ++ src/Knp/Menu/Provider/ArrayAccessProvider.php | 2 ++ src/Knp/Menu/Provider/ChainProvider.php | 3 +++ src/Knp/Menu/Provider/LazyProvider.php | 2 ++ src/Knp/Menu/Provider/PsrProvider.php | 2 ++ src/Knp/Menu/Renderer/ArrayAccessProvider.php | 2 ++ src/Knp/Menu/Renderer/ListRenderer.php | 2 ++ src/Knp/Menu/Renderer/PsrProvider.php | 2 ++ src/Knp/Menu/Renderer/TwigRenderer.php | 3 +++ src/Knp/Menu/Twig/MenuExtension.php | 21 +++++++++++++++++++ src/Knp/Menu/Twig/MenuRuntimeExtension.php | 17 +++++++++++++++ 22 files changed, 82 insertions(+) diff --git a/src/Knp/Menu/Factory/CoreExtension.php b/src/Knp/Menu/Factory/CoreExtension.php index 8cf17351..4293228a 100644 --- a/src/Knp/Menu/Factory/CoreExtension.php +++ b/src/Knp/Menu/Factory/CoreExtension.php @@ -6,6 +6,9 @@ /** * core factory extension with the main logic + * + * @final since 3.8.0 + * @internal since 3.8.0 */ class CoreExtension implements ExtensionInterface { diff --git a/src/Knp/Menu/Integration/Symfony/RoutingExtension.php b/src/Knp/Menu/Integration/Symfony/RoutingExtension.php index dc01e277..bb6e72f6 100644 --- a/src/Knp/Menu/Integration/Symfony/RoutingExtension.php +++ b/src/Knp/Menu/Integration/Symfony/RoutingExtension.php @@ -8,6 +8,8 @@ /** * Factory able to use the Symfony Routing component to build the url + * + * @final since 3.8.0 */ class RoutingExtension implements ExtensionInterface { diff --git a/src/Knp/Menu/Iterator/CurrentItemFilterIterator.php b/src/Knp/Menu/Iterator/CurrentItemFilterIterator.php index 8008c42a..d1b1fa72 100644 --- a/src/Knp/Menu/Iterator/CurrentItemFilterIterator.php +++ b/src/Knp/Menu/Iterator/CurrentItemFilterIterator.php @@ -10,6 +10,8 @@ * * @template TKey * @template-extends \FilterIterator> + * + * @final since 3.8.0 */ class CurrentItemFilterIterator extends \FilterIterator { diff --git a/src/Knp/Menu/Iterator/DisplayedItemFilterIterator.php b/src/Knp/Menu/Iterator/DisplayedItemFilterIterator.php index 1b8a0f97..3549edb8 100644 --- a/src/Knp/Menu/Iterator/DisplayedItemFilterIterator.php +++ b/src/Knp/Menu/Iterator/DisplayedItemFilterIterator.php @@ -4,6 +4,8 @@ /** * Filter iterator keeping only current items + * + * @final since 3.8.0 */ class DisplayedItemFilterIterator extends \RecursiveFilterIterator { diff --git a/src/Knp/Menu/Iterator/RecursiveItemIterator.php b/src/Knp/Menu/Iterator/RecursiveItemIterator.php index fe4edfbd..fc54d3f9 100644 --- a/src/Knp/Menu/Iterator/RecursiveItemIterator.php +++ b/src/Knp/Menu/Iterator/RecursiveItemIterator.php @@ -12,6 +12,8 @@ * @extends \IteratorIterator> * * @implements \RecursiveIterator + * + * @final since 3.8.0 */ class RecursiveItemIterator extends \IteratorIterator implements \RecursiveIterator { diff --git a/src/Knp/Menu/Loader/ArrayLoader.php b/src/Knp/Menu/Loader/ArrayLoader.php index 2ccf2275..b694bc3e 100644 --- a/src/Knp/Menu/Loader/ArrayLoader.php +++ b/src/Knp/Menu/Loader/ArrayLoader.php @@ -9,6 +9,8 @@ * Loader importing a menu tree from an array. * * The array should match the output of MenuManipulator::toArray + * + * @final since 3.8.0 */ class ArrayLoader implements LoaderInterface { diff --git a/src/Knp/Menu/Loader/NodeLoader.php b/src/Knp/Menu/Loader/NodeLoader.php index 84c23797..fac1f37c 100644 --- a/src/Knp/Menu/Loader/NodeLoader.php +++ b/src/Knp/Menu/Loader/NodeLoader.php @@ -6,6 +6,9 @@ use Knp\Menu\ItemInterface; use Knp\Menu\NodeInterface; +/** + * @final since 3.8.0 + */ class NodeLoader implements LoaderInterface { public function __construct(private FactoryInterface $factory) diff --git a/src/Knp/Menu/Matcher/Matcher.php b/src/Knp/Menu/Matcher/Matcher.php index 9b631eb7..3335dc90 100644 --- a/src/Knp/Menu/Matcher/Matcher.php +++ b/src/Knp/Menu/Matcher/Matcher.php @@ -7,6 +7,8 @@ /** * A MatcherInterface implementation using a voter system + * + * @final since 3.8.0 */ class Matcher implements MatcherInterface { diff --git a/src/Knp/Menu/Matcher/Voter/RegexVoter.php b/src/Knp/Menu/Matcher/Voter/RegexVoter.php index 801c3758..f831ca69 100644 --- a/src/Knp/Menu/Matcher/Voter/RegexVoter.php +++ b/src/Knp/Menu/Matcher/Voter/RegexVoter.php @@ -7,6 +7,8 @@ /** * Implements the VoterInterface which can be used as voter for "current" class * `matchItem` will return true if the pattern you're searching for is found in the URI of the item + * + * @final since 3.8.0 */ class RegexVoter implements VoterInterface { diff --git a/src/Knp/Menu/Matcher/Voter/RouteVoter.php b/src/Knp/Menu/Matcher/Voter/RouteVoter.php index 4b2b43f7..674a302b 100644 --- a/src/Knp/Menu/Matcher/Voter/RouteVoter.php +++ b/src/Knp/Menu/Matcher/Voter/RouteVoter.php @@ -8,6 +8,8 @@ /** * Voter based on the route + * + * @final since 3.8.0 */ class RouteVoter implements VoterInterface { diff --git a/src/Knp/Menu/Matcher/Voter/UriVoter.php b/src/Knp/Menu/Matcher/Voter/UriVoter.php index 617f5f05..4f6a534c 100644 --- a/src/Knp/Menu/Matcher/Voter/UriVoter.php +++ b/src/Knp/Menu/Matcher/Voter/UriVoter.php @@ -6,6 +6,8 @@ /** * Voter based on the uri + * + * @final since 3.8.0 */ class UriVoter implements VoterInterface { diff --git a/src/Knp/Menu/MenuFactory.php b/src/Knp/Menu/MenuFactory.php index f7ae333f..ac8dca19 100644 --- a/src/Knp/Menu/MenuFactory.php +++ b/src/Knp/Menu/MenuFactory.php @@ -7,6 +7,8 @@ /** * Factory to create a menu from a tree + * + * @final since 3.8.0 */ class MenuFactory implements FactoryInterface { diff --git a/src/Knp/Menu/Provider/ArrayAccessProvider.php b/src/Knp/Menu/Provider/ArrayAccessProvider.php index 79b4c7d8..70bbce44 100644 --- a/src/Knp/Menu/Provider/ArrayAccessProvider.php +++ b/src/Knp/Menu/Provider/ArrayAccessProvider.php @@ -10,6 +10,8 @@ * In case the value stored in the registry is a callable rather than an ItemInterface, * it will be called with the options as first argument and the registry as second argument * and is expected to return a menu item. + * + * @final since 3.8.0 */ class ArrayAccessProvider implements MenuProviderInterface { diff --git a/src/Knp/Menu/Provider/ChainProvider.php b/src/Knp/Menu/Provider/ChainProvider.php index 11cf6975..f52fe7c9 100644 --- a/src/Knp/Menu/Provider/ChainProvider.php +++ b/src/Knp/Menu/Provider/ChainProvider.php @@ -4,6 +4,9 @@ use Knp\Menu\ItemInterface; +/** + * @final since 3.8.0 + */ class ChainProvider implements MenuProviderInterface { /** diff --git a/src/Knp/Menu/Provider/LazyProvider.php b/src/Knp/Menu/Provider/LazyProvider.php index c42e3370..1d3c092e 100644 --- a/src/Knp/Menu/Provider/LazyProvider.php +++ b/src/Knp/Menu/Provider/LazyProvider.php @@ -10,6 +10,8 @@ * Builders can either be callables or a factory for an object callable * represented as [Closure, method], where the Closure gets called * to instantiate the object. + * + * @final since 3.8.0 */ class LazyProvider implements MenuProviderInterface { diff --git a/src/Knp/Menu/Provider/PsrProvider.php b/src/Knp/Menu/Provider/PsrProvider.php index 014587d2..3a5d2901 100644 --- a/src/Knp/Menu/Provider/PsrProvider.php +++ b/src/Knp/Menu/Provider/PsrProvider.php @@ -10,6 +10,8 @@ * * This menu provider does not support using options, as it cannot pass them to the container * to alter the menu building. Use a different provider in case you need support for options. + * + * @final since 3.8.0 */ class PsrProvider implements MenuProviderInterface { diff --git a/src/Knp/Menu/Renderer/ArrayAccessProvider.php b/src/Knp/Menu/Renderer/ArrayAccessProvider.php index 47bccac0..ee666cfd 100644 --- a/src/Knp/Menu/Renderer/ArrayAccessProvider.php +++ b/src/Knp/Menu/Renderer/ArrayAccessProvider.php @@ -4,6 +4,8 @@ /** * A renderer provider getting the renderers from a class implementing ArrayAccess. + * + * @final since 3.8.0 */ class ArrayAccessProvider implements RendererProviderInterface { diff --git a/src/Knp/Menu/Renderer/ListRenderer.php b/src/Knp/Menu/Renderer/ListRenderer.php index b68345f7..fa8c63e9 100644 --- a/src/Knp/Menu/Renderer/ListRenderer.php +++ b/src/Knp/Menu/Renderer/ListRenderer.php @@ -7,6 +7,8 @@ /** * Renders MenuItem tree as unordered list + * + * @final since 3.8.0 */ class ListRenderer extends Renderer implements RendererInterface { diff --git a/src/Knp/Menu/Renderer/PsrProvider.php b/src/Knp/Menu/Renderer/PsrProvider.php index 89830ea5..ce5928fc 100644 --- a/src/Knp/Menu/Renderer/PsrProvider.php +++ b/src/Knp/Menu/Renderer/PsrProvider.php @@ -9,6 +9,8 @@ * * This menu provider does not support using options, as it cannot pass them to the container * to alter the menu building. Use a different provider in case you need support for options. + * + * @final since 3.8.0 */ class PsrProvider implements RendererProviderInterface { diff --git a/src/Knp/Menu/Renderer/TwigRenderer.php b/src/Knp/Menu/Renderer/TwigRenderer.php index 99e4e6b1..534c5aa8 100644 --- a/src/Knp/Menu/Renderer/TwigRenderer.php +++ b/src/Knp/Menu/Renderer/TwigRenderer.php @@ -6,6 +6,9 @@ use Knp\Menu\Matcher\MatcherInterface; use Twig\Environment; +/** + * @final since 3.8.0 + */ class TwigRenderer implements RendererInterface { /** diff --git a/src/Knp/Menu/Twig/MenuExtension.php b/src/Knp/Menu/Twig/MenuExtension.php index 84e57c51..8d72a4a8 100644 --- a/src/Knp/Menu/Twig/MenuExtension.php +++ b/src/Knp/Menu/Twig/MenuExtension.php @@ -10,6 +10,9 @@ use Twig\TwigFunction; use Twig\TwigTest; +/** + * @final since 3.8.0 + */ class MenuExtension extends AbstractExtension { private ?MenuRuntimeExtension $runtimeExtension = null; @@ -68,6 +71,8 @@ public function getLastModified(): int /** * @param array $path * @param array $options + * + * @internal since 3.8.0 */ public function get(ItemInterface|string $menu, array $path = [], array $options = []): ItemInterface { @@ -79,6 +84,8 @@ public function get(ItemInterface|string $menu, array $path = [], array $options /** * @param string|ItemInterface|array $menu * @param array $options + * + * @internal since 3.8.0 */ public function render(array|ItemInterface|string $menu, array $options = [], ?string $renderer = null): string { @@ -94,6 +101,8 @@ public function render(array|ItemInterface|string $menu, array $options = [], ?s * * @return array> * @phpstan-return list + * + * @internal since 3.8.0 */ public function getBreadcrumbsArray(array|ItemInterface|string $menu, array|string|null $subItem = null): array { @@ -102,6 +111,9 @@ public function getBreadcrumbsArray(array|ItemInterface|string $menu, array|stri return $this->runtimeExtension->getBreadcrumbsArray($menu, $subItem); } + /** + * @internal since 3.8.0 + */ public function getCurrentItem(ItemInterface|string $menu): ItemInterface { assert(null !== $this->runtimeExtension); @@ -109,6 +121,9 @@ public function getCurrentItem(ItemInterface|string $menu): ItemInterface return $this->runtimeExtension->getCurrentItem($menu); } + /** + * @internal since 3.8.0 + */ public function pathAsString(ItemInterface $menu, string $separator = ' > '): string { assert(null !== $this->runtimeExtension); @@ -116,6 +131,9 @@ public function pathAsString(ItemInterface $menu, string $separator = ' > '): st return $this->runtimeExtension->pathAsString($menu, $separator); } + /** + * @internal since 3.8.0 + */ public function isCurrent(ItemInterface $item): bool { assert(null !== $this->runtimeExtension); @@ -123,6 +141,9 @@ public function isCurrent(ItemInterface $item): bool return $this->runtimeExtension->isCurrent($item); } + /** + * @internal since 3.8.0 + */ public function isAncestor(ItemInterface $item, ?int $depth = null): bool { assert(null !== $this->runtimeExtension); diff --git a/src/Knp/Menu/Twig/MenuRuntimeExtension.php b/src/Knp/Menu/Twig/MenuRuntimeExtension.php index 5dc4f5fc..a7d7e131 100644 --- a/src/Knp/Menu/Twig/MenuRuntimeExtension.php +++ b/src/Knp/Menu/Twig/MenuRuntimeExtension.php @@ -7,6 +7,9 @@ use Knp\Menu\Util\MenuManipulator; use Twig\Extension\RuntimeExtensionInterface; +/** + * @final since 3.8.0 + */ class MenuRuntimeExtension implements RuntimeExtensionInterface { public function __construct( @@ -21,6 +24,8 @@ public function __construct( * * @param array $path * @param array $options + * + * @internal since 3.8.0 */ public function get(ItemInterface|string $menu, array $path = [], array $options = []): ItemInterface { @@ -32,6 +37,8 @@ public function get(ItemInterface|string $menu, array $path = [], array $options * * @param string|ItemInterface|array $menu * @param array $options + * + * @internal since 3.8.0 */ public function render(array|ItemInterface|string $menu, array $options = [], ?string $renderer = null): string { @@ -47,6 +54,8 @@ public function render(array|ItemInterface|string $menu, array $options = [], ?s * * @return array> * @phpstan-return list + * + * @internal since 3.8.0 */ public function getBreadcrumbsArray(array|ItemInterface|string $menu, array|string|null $subItem = null): array { @@ -55,6 +64,8 @@ public function getBreadcrumbsArray(array|ItemInterface|string $menu, array|stri /** * Returns the current item of a menu. + * + * @internal since 3.8.0 */ public function getCurrentItem(ItemInterface|string $menu): ItemInterface { @@ -73,6 +84,8 @@ public function getCurrentItem(ItemInterface|string $menu): ItemInterface * A string representation of this menu item * * e.g. Top Level > Second Level > This menu + * + * @internal since 3.8.0 */ public function pathAsString(ItemInterface $menu, string $separator = ' > '): string { @@ -85,6 +98,8 @@ public function pathAsString(ItemInterface $menu, string $separator = ' > '): st /** * Checks whether an item is current. + * + * @internal since 3.8.0 */ public function isCurrent(ItemInterface $item): bool { @@ -99,6 +114,8 @@ public function isCurrent(ItemInterface $item): bool * Checks whether an item is the ancestor of a current item. * * @param int|null $depth The max depth to look for the item + * + * @internal since 3.8.0 */ public function isAncestor(ItemInterface $item, ?int $depth = null): bool {