feature symfony#61860 [Config][DependencyInjection][Routing] Deprecate using $this or the internal scope of the loader from PHP config files (nicolas-grekas)

This PR was merged into the 7.4 branch.

Discussion
----------

[Config][DependencyInjection][Routing] Deprecate using `$this` or the internal scope of the loader from PHP config files

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | no
| Deprecations? | yes
| Issues        | -
| License       | MIT

The target of this change is being able to patch the PHP-DSL examples in the documentation without any downsides:
```diff
-return static function (FrameworkConfig $framework) {
+return function (FrameworkConfig $framework) {
```

Commits
-------

9afb4f4 [DependencyInjection][Config][Routing] Deprecate using `$this` or the internal scope of the loader from PHP config files

Author: nicolas-grekas

UPGRADE-7.4.md

@@ -18,6 +18,11 @@ Cache
 
  * Bump ext-redis to 6.2 and ext-relay to 0.11 minimum
 
+Config
+------
+
+ * Deprecate accessing the internal scope of the loader in PHP config files, use only its public API instead
+
 Console
 -------
 
@@ -29,6 +34,7 @@ DependencyInjection
  * Add argument `$target` to `ContainerBuilder::registerAliasForArgument()`
  * Add argument `$throwOnAbstract` to `ContainerBuilder::findTaggedResourceIds()`
  * Deprecate registering a service without a class when its id is a non-existing FQCN
+ * Deprecate using `$this` or its internal scope from PHP config files; use the `$loader` variable instead
 
 DoctrineBridge
 --------------
@@ -87,6 +93,7 @@ Routing
 
  * Deprecate class aliases in the `Annotation` namespace, use attributes instead
  * Deprecate getters and setters in attribute classes in favor of public properties
+ * Deprecate accessing the internal scope of the loader in PHP config files, use only its public API instead
 
 Security
 --------

src/Symfony/Bundle/SecurityBundle/Tests/DependencyInjection/Fixtures/php/argon2i_hasher.php

@@ -1,6 +1,6 @@
 <?php
 
-$this->load('container1.php');
+$loader->load('container1.php');
 
 $container->loadFromExtension('security', [
     'password_hashers' => [

src/Symfony/Bundle/SecurityBundle/Tests/DependencyInjection/Fixtures/php/bcrypt_hasher.php

@@ -1,6 +1,6 @@
 <?php
 
-$this->load('container1.php');
+$loader->load('container1.php');
 
 $container->loadFromExtension('security', [
     'password_hashers' => [

src/Symfony/Bundle/SecurityBundle/Tests/DependencyInjection/Fixtures/php/merge.php

@@ -1,6 +1,6 @@
 <?php
 
-$this->load('merge_import.php');
+$loader->load('merge_import.php');
 
 $container->loadFromExtension('security', [
     'providers' => [

src/Symfony/Bundle/SecurityBundle/Tests/DependencyInjection/Fixtures/php/migrating_hasher.php

@@ -1,6 +1,6 @@
 <?php
 
-$this->load('container1.php');
+$loader->load('container1.php');
 
 $container->loadFromExtension('security', [
     'password_hashers' => [

src/Symfony/Bundle/SecurityBundle/Tests/DependencyInjection/Fixtures/php/sodium_hasher.php

@@ -1,6 +1,6 @@
 <?php
 
-$this->load('container1.php');
+$loader->load('container1.php');
 
 $container->loadFromExtension('security', [
     'password_hashers' => [

src/Symfony/Component/Config/CHANGELOG.md

@@ -9,6 +9,7 @@ CHANGELOG
  * Add support for `defaultNull()` on `ArrayNodeDefinition`
  * Add `ArrayNodeDefinition::acceptAndWrap()` to list alternative types that should be accepted and wrapped in an array
  * Add array-shapes to generated config builders
+ * Deprecate accessing the internal scope of the loader in PHP config files, use only its public API instead
 
 7.3
 ---

src/Symfony/Component/Config/Definition/Loader/DefinitionFileLoader.php

@@ -46,9 +46,19 @@ public function load(mixed $resource, ?string $type = null): mixed
         // the closure forbids access to the private scope in the included file
         $load = \Closure::bind(static function ($file) use ($loader) {
             return include $file;
-        }, null, ProtectedDefinitionFileLoader::class);
+        }, null, null);
 
-        $callback = $load($path);
+        try {
+            $callback = $load($path);
+        } catch (\Error $e) {
+            $load = \Closure::bind(static function ($file) use ($loader) {
+                return include $file;
+            }, null, ProtectedDefinitionFileLoader::class);
+
+            $callback = $load($path);
+
+            trigger_deprecation('symfony/config', '7.4', 'Accessing the internal scope of the loader in config files is deprecated, use only its public API instead in "%s" on line %d.', $e->getFile(), $e->getLine());
+        }
 
         if (\is_object($callback) && \is_callable($callback)) {
             $this->executeCallback($callback, new DefinitionConfigurator($this->treeBuilder, $this, $path, $resource), $path);

src/Symfony/Component/Config/Tests/Definition/Loader/DefinitionFileLoaderTest.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Config\Tests\Definition\Loader;
 
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Config\Definition\BaseNode;
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
@@ -39,4 +41,15 @@ public function testLoad()
         $this->assertInstanceOf(BaseNode::class, $children['foo']);
         $this->assertSame('test.foo', $children['foo']->getPath(), '->load() loads a PHP file resource');
     }
+
+    #[IgnoreDeprecations]
+    #[Group('legacy')]
+    public function testTriggersDeprecationWhenAccessingLoaderInternalScope()
+    {
+        $loader = new DefinitionFileLoader(new TreeBuilder('test'), new FileLocator(__DIR__.'/../../Fixtures/Loader'));
+
+        $this->expectUserDeprecationMessageMatches('{^Since symfony/config 7.4: Accessing the internal scope of the loader in config files is deprecated, use only its public API instead in ".+" on line \d+\.$}');
+
+        $loader->load('legacy_internal_scope.php');
+    }
 }

src/Symfony/Component/Config/Tests/Fixtures/Loader/legacy_internal_scope.php

@@ -0,0 +1,4 @@
+<?php
+
+// access the loader's internal scope to trigger deprecation
+$loader->resolver;