feature #24160 [HttpKernel] Deprecate bundle inheritance (fabpot)

This PR was squashed before being merged into the 3.4 branch (closes #24160).

Discussion
----------

[HttpKernel] Deprecate bundle inheritance

| Q             | A
| ------------- | ---
| Branch?       | 3.4
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #24048
| License       | MIT
| Doc PR        | symfony/symfony-docs#8389

Commits
-------

89893c1 [HttpKernel] deprecated bundle inheritance
ee9f4c3 fixed CS

UPGRADE-3.4.md

@@ -173,6 +173,8 @@ FrameworkBundle
 HttpKernel
 ----------
 
+ * Bundle inheritance has been deprecated.
+
  * Relying on convention-based commands discovery has been deprecated and
    won't be supported in 4.0. Use PSR-4 based service discovery instead.
 

UPGRADE-4.0.md

@@ -493,6 +493,8 @@ HttpFoundation
 HttpKernel
 ----------
 
+ * Bundle inheritance has been removed.
+
  * Relying on convention-based commands discovery is not supported anymore.
    Use PSR-4 based service discovery instead.
 

src/Symfony/Bundle/FrameworkBundle/Controller/ControllerNameParser.php

@@ -58,7 +58,7 @@ public function parse($controller)
 
         try {
             // this throws an exception if there is no such bundle
-            $allBundles = $this->kernel->getBundle($bundle, false);
+            $allBundles = $this->kernel->getBundle($bundle, false, true);
         } catch (\InvalidArgumentException $e) {
             $message = sprintf(
                 'The "%s" (from the _controller value "%s") does not exist or is not enabled in your kernel!',
@@ -141,7 +141,7 @@ private function findAlternative($nonExistentBundleName)
             }
 
             $lev = levenshtein($nonExistentBundleName, $bundleName);
-            if ($lev <= strlen($nonExistentBundleName) / 3 && ($alternative === null || $lev < $shortest)) {
+            if ($lev <= strlen($nonExistentBundleName) / 3 && (null === $alternative || $lev < $shortest)) {
                 $alternative = $bundleName;
                 $shortest = $lev;
             }

src/Symfony/Component/HttpKernel/Bundle/BundleInterface.php

@@ -56,6 +56,8 @@ public function getContainerExtension();
      * bundle.
      *
      * @return string The Bundle name it overrides or null if no parent
+     *
+     * @deprecated This method is deprecated as of 3.4 and will be removed in 4.0.
      */
     public function getParent();
 

src/Symfony/Component/HttpKernel/CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 3.4.0
 -----
 
+ * deprecated bundle inheritance
  * added `RebootableInterface` and implemented it in `Kernel`
  * deprecated commands auto registration
  * added `AddCacheClearerPass`

src/Symfony/Component/HttpKernel/Kernel.php

@@ -204,8 +204,17 @@ public function getBundles()
     /**
      * {@inheritdoc}
      */
-    public function getBundle($name, $first = true)
+    public function getBundle($name, $first = true/*, $noDeprecation = false */)
     {
+        $noDeprecation = false;
+        if (func_num_args() >= 3) {
+            $noDeprecation = func_get_arg(2);
+        }
+
+        if (!$first && !$noDeprecation) {
+            @trigger_error(sprintf('Passing "false" as the second argument to %s() is deprecated as of 3.4 and will be removed in 4.0.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         if (!isset($this->bundleMap[$name])) {
             throw new \InvalidArgumentException(sprintf('Bundle "%s" does not exist or it is not enabled. Maybe you forgot to add it in the registerBundles() method of your %s.php file?', $name, get_class($this)));
         }
@@ -241,7 +250,7 @@ public function locateResource($name, $dir = null, $first = true)
         $isResource = 0 === strpos($path, 'Resources') && null !== $dir;
         $overridePath = substr($path, 9);
         $resourceBundle = null;
-        $bundles = $this->getBundle($bundleName, false);
+        $bundles = $this->getBundle($bundleName, false, true);
         $files = array();
 
         foreach ($bundles as $bundle) {
@@ -468,6 +477,8 @@ protected function initializeBundles()
             $this->bundles[$name] = $bundle;
 
             if ($parentName = $bundle->getParent()) {
+                @trigger_error('Bundle inheritance is deprecated as of 3.4 and will be removed in 4.0.', E_USER_DEPRECATED);
+
                 if (isset($directChildren[$parentName])) {
                     throw new \LogicException(sprintf('Bundle "%s" is directly extended by two bundles "%s" and "%s".', $parentName, $name, $directChildren[$parentName]));
                 }
@@ -852,7 +863,7 @@ public static function stripComments($source)
                 do {
                     $token = $tokens[++$i];
                     $output .= isset($token[1]) && 'b"' !== $token ? $token[1] : $token;
-                } while ($token[0] !== T_END_HEREDOC);
+                } while (T_END_HEREDOC !== $token[0]);
                 $rawChunk = '';
             } elseif (T_WHITESPACE === $token[0]) {
                 if ($ignoreSpace) {

src/Symfony/Component/HttpKernel/KernelInterface.php

@@ -60,6 +60,9 @@ public function getBundles();
     /**
      * Returns a bundle and optionally its descendants by its name.
      *
+     * The second argument is deprecated as of 3.4 and will be removed in 4.0. This method
+     * will always return an instance of BundleInterface in 4.0.
+     *
      * @param string $name  Bundle name
      * @param bool   $first Whether to return the first bundle only or together with its descendants
      *

src/Symfony/Component/HttpKernel/Tests/KernelTest.php

@@ -410,6 +410,9 @@ public function testLocateResourceReturnsTheFirstThatMatches()
         $this->assertEquals(__DIR__.'/Fixtures/Bundle1Bundle/foo.txt', $kernel->locateResource('@Bundle1Bundle/foo.txt'));
     }
 
+    /**
+     * @group legacy
+     */
     public function testLocateResourceReturnsTheFirstThatMatchesWithParent()
     {
         $parent = $this->getBundle(__DIR__.'/Fixtures/Bundle1Bundle');
@@ -426,6 +429,9 @@ public function testLocateResourceReturnsTheFirstThatMatchesWithParent()
         $this->assertEquals(__DIR__.'/Fixtures/Bundle1Bundle/bar.txt', $kernel->locateResource('@ParentAABundle/bar.txt'));
     }
 
+    /**
+     * @group legacy
+     */
     public function testLocateResourceReturnsAllMatches()
     {
         $parent = $this->getBundle(__DIR__.'/Fixtures/Bundle1Bundle');
@@ -444,6 +450,9 @@ public function testLocateResourceReturnsAllMatches()
             $kernel->locateResource('@Bundle1Bundle/foo.txt', null, false));
     }
 
+    /**
+     * @group legacy
+     */
     public function testLocateResourceReturnsAllMatchesBis()
     {
         $kernel = $this->getKernel(array('getBundle'));
@@ -492,6 +501,9 @@ public function testLocateResourceReturnsTheDirOneForResources()
         );
     }
 
+    /**
+     * @group legacy
+     */
     public function testLocateResourceReturnsTheDirOneForResourcesAndBundleOnes()
     {
         $kernel = $this->getKernel(array('getBundle'));
@@ -508,6 +520,9 @@ public function testLocateResourceReturnsTheDirOneForResourcesAndBundleOnes()
         );
     }
 
+    /**
+     * @group legacy
+     */
     public function testLocateResourceOverrideBundleAndResourcesFolders()
     {
         $parent = $this->getBundle(__DIR__.'/Fixtures/BaseBundle', null, 'BaseBundle', 'BaseBundle');
@@ -581,6 +596,9 @@ public function testLocateResourceOnDirectories()
         );
     }
 
+    /**
+     * @group legacy
+     */
     public function testInitializeBundles()
     {
         $parent = $this->getBundle(null, null, 'ParentABundle');
@@ -599,6 +617,9 @@ public function testInitializeBundles()
         $this->assertEquals(array($child, $parent), $map['ParentABundle']);
     }
 
+    /**
+     * @group legacy
+     */
     public function testInitializeBundlesSupportInheritanceCascade()
     {
         $grandparent = $this->getBundle(null, null, 'GrandParentBBundle');
@@ -621,6 +642,7 @@ public function testInitializeBundlesSupportInheritanceCascade()
     }
 
     /**
+     * @group legacy
      * @expectedException \LogicException
      * @expectedExceptionMessage Bundle "ChildCBundle" extends bundle "FooBar", which is not registered.
      */
@@ -631,6 +653,9 @@ public function testInitializeBundlesThrowsExceptionWhenAParentDoesNotExists()
         $kernel->boot();
     }
 
+    /**
+     * @group legacy
+     */
     public function testInitializeBundlesSupportsArbitraryBundleRegistrationOrder()
     {
         $grandparent = $this->getBundle(null, null, 'GrandParentCBundle');
@@ -653,6 +678,7 @@ public function testInitializeBundlesSupportsArbitraryBundleRegistrationOrder()
     }
 
     /**
+     * @group legacy
      * @expectedException \LogicException
      * @expectedExceptionMessage Bundle "ParentCBundle" is directly extended by two bundles "ChildC2Bundle" and "ChildC1Bundle".
      */
@@ -667,6 +693,7 @@ public function testInitializeBundlesThrowsExceptionWhenABundleIsDirectlyExtende
     }
 
     /**
+     * @group legacy
      * @expectedException \LogicException
      * @expectedExceptionMessage Trying to register two bundles with the same name "DuplicateName"
      */
@@ -680,6 +707,7 @@ public function testInitializeBundleThrowsExceptionWhenRegisteringTwoBundlesWith
     }
 
     /**
+     * @group legacy
      * @expectedException \LogicException
      * @expectedExceptionMessage Bundle "CircularRefBundle" can not extend itself.
      */