diff --git a/CHANGELOG.md b/CHANGELOG.md index 21a283a..36b6ab6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# v1.8 + +- introduce ResetBreadcrumbtrail attribute for resetting trail, prefer over empty annotation + # v1.7 - support breadcrumbs via PHP Attributes diff --git a/src/Annotation/Breadcrumb.php b/src/Annotation/Breadcrumb.php index c68710c..a6334f3 100644 --- a/src/Annotation/Breadcrumb.php +++ b/src/Annotation/Breadcrumb.php @@ -53,7 +53,7 @@ class Breadcrumb private $attributes = []; /** - * @param array|string $title title, or the legacy array that contains all annotation data + * @param array|string|null $title title, or the legacy array that contains all annotation data. Passing `null` to reset the breadcrumb trail is deprecated and will throw an exception in `2.0`. * @param ?string $routeName * @param ?array $routeParameters * @param bool $routeAbsolute @@ -62,7 +62,7 @@ class Breadcrumb * @param array $attributes */ public function __construct( - $title, + $title = null, $routeName = null, $routeParameters = null, $routeAbsolute = null, diff --git a/src/Annotation/ResetBreadcrumbTrail.php b/src/Annotation/ResetBreadcrumbTrail.php new file mode 100644 index 0000000..9ba97ff --- /dev/null +++ b/src/Annotation/ResetBreadcrumbTrail.php @@ -0,0 +1,11 @@ +breadcrumbTrail->reset(); + + continue; + } + if ($annotation instanceof Breadcrumb) { $template = $annotation->getTemplate(); $title = $annotation->getTitle(); + if (null === $title) { + trigger_deprecation('apy/breadcrumb-bundle', '1.8', 'Resetting the breadcrumb trail by passing a Breadcrumb without parameters, and will throw an exception in v2.0. Use #[ResetBreadcrumbTrail] attribute instead.'); + } + if (null != $template) { $this->breadcrumbTrail->setTemplate($template); if (null === $title) { @@ -158,7 +174,11 @@ private function getAttributes($reflected): array } $attributes = []; - foreach ($reflected->getAttributes(Breadcrumb::class) as $reflectionAttribute) { + foreach ($reflected->getAttributes() as $reflectionAttribute) { + if (false === \in_array($reflectionAttribute->getName(), $this->supportedAttributes)) { + continue; + } + $attributes[] = $reflectionAttribute->newInstance(); } diff --git a/src/Resources/doc/annotation_configuration.md b/src/Resources/doc/annotation_configuration.md index e1c0578..a0b403b 100644 --- a/src/Resources/doc/annotation_configuration.md +++ b/src/Resources/doc/annotation_configuration.md @@ -284,7 +284,7 @@ Will render the following breadcrumb trail : ### Reset the trail -Passing an breadcrumb without any parameter values will remove all existing +Adding a ResetBreadcrumbTrail attribute will remove all existing breadcrumbs from the trail. Resetting might come in handy in case the controller class unwantedly defines @@ -292,9 +292,10 @@ breadcrumbs already. ```php use APY\BreadcrumbTrailBundle\Annotation\Breadcrumb; +use APY\BreadcrumbTrailBundle\Annotation\ResetBreadcrumbTrail; #[Breadcrumb("Level 1")] -#[Breadcrumb()] +#[ResetBreadcrumbTrail()] #[Breadcrumb("Level 2")] #[Breadcrumb("Level 3")] ``` diff --git a/tests/Annotation/BreadcrumbTest.php b/tests/Annotation/BreadcrumbTest.php index 9c09141..7ba7ea8 100644 --- a/tests/Annotation/BreadcrumbTest.php +++ b/tests/Annotation/BreadcrumbTest.php @@ -50,4 +50,15 @@ public function testUnnamedWillGetInterpretedAsValueForTitle() self::assertEquals($expected, $breadcrumb->getTitle()); } + + /** + * @deprecated passing empty constructor is deprecated since 1.8. ResetBreadcrumbTrail attribute should be used instead. Will throw exception in 2.0. + */ + public function testConstructorWithoutArgumentsIsAllowedForResettingTrail() + { + $expected = null; + $breadcrumb = new Breadcrumb(); + + self::assertEquals($expected, $breadcrumb->getTitle()); + } } diff --git a/tests/EventListener/BreadcrumbListenerTest.php b/tests/EventListener/BreadcrumbListenerTest.php index 53d7ae1..b761483 100644 --- a/tests/EventListener/BreadcrumbListenerTest.php +++ b/tests/EventListener/BreadcrumbListenerTest.php @@ -8,6 +8,7 @@ use APY\BreadcrumbTrailBundle\Fixtures\ControllerWithAttributes; use APY\BreadcrumbTrailBundle\Fixtures\ControllerWithAttributesAndAnnotations; use APY\BreadcrumbTrailBundle\Fixtures\InvokableControllerWithAnnotations; +use APY\BreadcrumbTrailBundle\Fixtures\ResetTrailAttribute; use APY\BreadcrumbTrailBundle\MixedAnnotationWithAttributeBreadcrumbsException; use Nyholm\BundleTest\AppKernel; use Nyholm\BundleTest\BaseBundleTestCase; @@ -86,6 +87,20 @@ public function testInvokableController() self::assertCount(3, $this->breadcrumbTrail); } + /** + * @requires PHP >= 8.0 + */ + public function testResetTrailAttribute() + { + $this->setUpTest(); + + $controller = new ResetTrailAttribute(); + $kernelEvent = $this->createControllerEvent($controller); + $this->listener->onKernelController($kernelEvent); + + self::assertCount(1, $this->breadcrumbTrail); + } + protected function getBundleClass() { return APYBreadcrumbTrailBundle::class; diff --git a/tests/Fixtures/ResetTrailAttribute.php b/tests/Fixtures/ResetTrailAttribute.php new file mode 100644 index 0000000..f4cabeb --- /dev/null +++ b/tests/Fixtures/ResetTrailAttribute.php @@ -0,0 +1,18 @@ +