refactor(core)!: decouple discovery by brendt · Pull Request #2041 · tempestphp/tempest-framework

brendt · 2026-03-11T10:10:54Z

Upgrade Guide

Install Rector if you haven't yet:

composer require rector/rector --dev 
vendor/bin/rector

Next, update Tempest; it's important to add the --no-scripts flag to prevent any errors from being thrown during the update.

composer require tempest/framework:^3.4 --no-scripts

Then configure Rector to upgrade to Tempest 3.4:

// rector.php

use \Tempest\Upgrade\Set\TempestSetList;

return RectorConfig::configure()
    // …
    ->withSets([TempestSetList::TEMPEST_34]);

Next, run Rector:

vendor/bin/rector

Finally: make sure all discovery caches are regenerated:

./tempest discovery:generate

Breaking changes:

Tempest\Core\DiscoveryCache moved to Tempest\Discovery\DiscoveryCache
Tempest\Core\DiscoveryCacheStrategy moved to Tempest\Discovery\DiscoveryCacheStrategy
Tempest\Core\Composer moved to Tempest\Discovery\Composer
Tempest\Core\ComposerJsonCouldNotBeLocated moved to Tempest\Discovery\ComposerJsonCouldNotBeLocated
Tempest\Core\DiscoveryCachingStrategyWasChanged moved to Tempest\Discovery\DiscoveryCachingStrategyWasChanged
Tempest\Core\DiscoveryConfig moved to Tempest\Discovery\DiscoveryConfig
Removed Kernel::$discoveryLocations and Kernel::$discoveryClasses property hooks
Removed FrameworkKernel::$discoveryLocations and FrameworkKernel::$discoveryClasses properties

Non-breaking changes:

(internal class) Tempest\Core\LoadDiscoveryClasses moved to Tempest\Discovery\BootDiscovery
(internal class) Tempest\Core\LoadDiscoveryLocations moved to Tempest\Discovery\AutoloadDiscoveryLocations
(internal class) Tempest\Core\DiscoveryCacheInitializer moved to Tempest\Discovery\DiscoveryCacheInitializer
(internal class) Tempest\Core\DiscoveryDiscovery moved to Tempest\Discovery\DiscoveryDiscovery

Discovery as a standalone package

tempest/discovery can be used as a standalone package in any application. All it needs is a PSR-11 compliant container.

Start by requiring tempest/discovery:

composer require tempest/discovery

Next, you can boot discovery:

use Tempest\Discovery\BootDiscovery;
use Tempest\Discovery\DiscoveryConfig;

// $container is any PSR-11 compliant container, already available in your app

new BootDiscovery(
    container: $container,
    config: DiscoveryConfig::autoload(__DIR__),
)();

Whenever this action is run, discovery will find all discovery classes, and run them against all registered locations.

Manually specify discovery locations

DiscoveryConfig::autoload() will scan a given root path and autmatically determine discovery locations by analyzing the composer.json file in that path. If you prefer another way of defining locations to scan, you can manually provide them via DiscoveryConfig:

use Tempest\Discovery\DiscoveryConfig;
use Tempest\Discovery\DiscoveryLocation;

$config = new DiscoveryConfig(locations: [
    new DiscoveryLocation('App\\', 'src/'),
    // …
]);

Config and caching

You can pass config and cache parameters into the BootDiscovery action, with these you can exclude files and classes from discovery, as well as config caching behavior:

use Tempest\Discovery\BootDiscovery;
use Tempest\Discovery\DiscoveryCache;
use Tempest\Discovery\DiscoveryCacheStrategy;
use Tempest\Discovery\DiscoveryConfig;

new BootDiscovery(
    container: $container,
    config: DiscoveryConfig::autoload(__DIR__)
        ->skipClasses(
            \App\Foo::class,
            \Tempest\Container\AutowireDiscovery::class
        )
        ->skipPaths(
            __DIR__ . '/../vendor/tempest/support'
        ),
    cache: new DiscoveryCache(
        strategy: DiscoveryCacheStrategy::PARTIAL,
        pool: new PhpFilesAdapter(
            directory: __DIR__ . '/.cache/discovery'
        )
    ),
)();

github-actions · 2026-03-11T10:15:32Z

Benchmark Results

Comparison of discovery-improvements against 3.x (ab8cfb14398f19936e9c4be649a2c42c805dbcf1).

Open to see the benchmark results

Benchmark	Set	Mem. Peak	Time	Variability
ContainerBench(benchRegisterSingletonInstance)	-	3.871mb +39.90%	1.251μs +44.40%	±1.19% -18.23%
ContainerBench(benchRegisterDefinition)	-	3.871mb +57.22%	1.427μs +58.91%	±1.56% +12.07%
ContainerBench(benchRegisterInitializer)	-	3.906mb +48.34%	4.222μs +13.03%	±1.20% -2.82%
ContainerBench(benchRegisterDynamicInitializer)	-	3.907mb +43.80%	1.932μs +30.21%	±0.98% -18.21%
ContainerBench(benchRegisterClosureSingleton)	-	3.871mb +48.87%	1.264μs +35.08%	±1.50% +36.52%
DiscoveryScanBench(benchFullDiscoveryScan)	-	23.356mb +0.17%	14.867ms -71.59%	±0.53% +9.71%
DiscoveryScanBench(benchSinglePackageScan)	clock (small)	23.357mb +0.17%	86.886μs -95.52%	±1.16% +85.84%
DiscoveryScanBench(benchSinglePackageScan)	console (large)	23.357mb +0.17%	1.540ms -76.30%	±0.43% +27.52%
DiscoveryScanBench(benchSinglePackageScan)	router (large)	23.357mb +0.17%	1.049ms -86.13%	±0.74% +37.72%

_{Generated by phpbench against commit 72fe86a}

iamdadmin · 2026-03-11T14:44:24Z

Aidan's not the only one who loves the commits :D

brendt · 2026-03-12T09:34:30Z

Todo: add Rectors

packages/discovery/tests/DiscoveryTest.php

packages/discovery/src/Composer.php

xHeaven · 2026-03-12T17:45:11Z

packages/upgrade/src/Tempest34/UpdateKernelDiscoveryPropertiesRector.php

+        // Transform $kernel->discoveryLocations to $kernel->registry->locations
+        return new PropertyFetch(
+            new PropertyFetch($node->var, 'registry'),


Suggested change

// Transform $kernel->discoveryLocations to $kernel->registry->locations

return new PropertyFetch(

new PropertyFetch($node->var, 'registry'),

// Transform $kernel->discoveryLocations to $kernel->discoveryConfig->locations

return new PropertyFetch(

new PropertyFetch($node->var, 'discoveryConfig'),

xHeaven · 2026-03-12T17:46:43Z

packages/upgrade/tests/Tempest34/Tempest34RectorTest.php

+    {
+        $this->rector
+            ->runFixture(__DIR__ . '/Fixtures/KernelDiscoveryLocations.input.php')
+            ->assertContains('$this->kernel->registry->locations')


Suggested change

->assertContains('$this->kernel->registry->locations')

->assertContains('$this->kernel->discoveryConfig->locations')

xHeaven · 2026-03-12T17:46:52Z

packages/upgrade/tests/Tempest34/Tempest34RectorTest.php

+    {
+        $this->rector
+            ->runFixture(__DIR__ . '/Fixtures/KernelDiscoveryClasses.input.php')
+            ->assertContains('$this->kernel->registry->classes')


Suggested change

->assertContains('$this->kernel->registry->classes')

->assertContains('$this->kernel->discoveryConfig->classes')

xHeaven · 2026-03-12T17:50:39Z

packages/discovery/src/BootDiscovery.php

    private function resolveDiscovery(string $discoveryClass): Discovery
    {
        /** @var Discovery $discovery */
        $discovery = $this->container->get($discoveryClass);


Perhaps we could do a check with $this->container->has($discoveryClass) and instantiate a new $discoveryClass if the check returns with false. This would add support for containers with no autowiring.

xHeaven · 2026-03-12T17:51:38Z

packages/core/src/FrameworkKernel.php

    public bool $discoveryCache;



Suggested change

public bool $discoveryCache;

Dead code.

xHeaven · 2026-03-12T18:31:26Z

packages/upgrade/src/Tempest34/UpdateDiscoveryImportsRector.php

+        'Tempest\Core\DiscoveryConfig' => 'Tempest\Discovery\DiscoveryConfig',
+        'Tempest\Core\CouldNotStoreDiscoveryCache' => 'Tempest\Discovery\CouldNotStoreDiscoveryCache',


Suggested change

'Tempest\Core\DiscoveryConfig' => 'Tempest\Discovery\DiscoveryConfig',

'Tempest\Core\CouldNotStoreDiscoveryCache' => 'Tempest\Discovery\CouldNotStoreDiscoveryCache',

'Tempest\Core\DiscoveryConfig' => 'Tempest\Discovery\DiscoveryConfig',

'Tempest\Core\CouldNotStoreDiscoveryCache' => 'Tempest\Discovery\CouldNotStoreDiscoveryCache',

'Tempest\Core\DiscoveryCacheInitializer' => 'Tempest\Discovery\DiscoveryCacheInitializer',

'Tempest\Core\DiscoveryDiscovery' => 'Tempest\Discovery\DiscoveryDiscovery',

xHeaven · 2026-03-12T18:40:32Z

packages/core/src/Commands/DiscoveryGenerateCommand.php

@@ -78,10 +79,11 @@ public function resolveKernel(): Kernel
        {
            $container = new GenericContainer();
            $container->singleton(Container::class, $container);


Suggested change

$container->singleton(Container::class, $container);

new GenericContainer(); already registers Container::class (and a couple others) as singletons.

xHeaven · 2026-03-12T18:43:41Z

docs/1-essentials/05-discovery.md

+
+### Manually specify discovery locations
+
+`DiscoveryConfig::autoload()` will scan a given root path and autmatically determine discovery locations by analyzing the composer.json file in that path. If you prefer another way of defining locations to scan, you can manually provide them via `DiscoveryConfig`:


Suggested change

`DiscoveryConfig::autoload()` will scan a given root path and autmatically determine discovery locations by analyzing the composer.json file in that path. If you prefer another way of defining locations to scan, you can manually provide them via `DiscoveryConfig`:

`DiscoveryConfig::autoload()` will scan a given root path and automatically determine discovery locations by analyzing the composer.json file in that path. If you prefer another way of defining locations to scan, you can manually provide them via `DiscoveryConfig`:

xHeaven · 2026-03-12T18:47:12Z

tests/Integration/Http/Exceptions/ExceptionRendererTest.php

            public array $discoveryLocations;

            public array $discoveryClasses;



discoveryLocations and discoveryClasses got removed from Kernel, dead code.

xHeaven · 2026-03-12T18:48:09Z

tests/Integration/Http/Exceptions/ExceptionRendererTest.php

+                $this->discoveryLocations = $kernel->discoveryConfig->locations;
+                $this->discoveryClasses = $kernel->discoveryConfig->classes;


Suggested change

$this->discoveryLocations = $kernel->discoveryConfig->locations;

$this->discoveryClasses = $kernel->discoveryConfig->classes;

See #2041 (comment)

xHeaven · 2026-03-12T18:52:07Z

packages/discovery/src/DiscoveryCacheInitializer.php

 use Tempest\Container\Container;
 use Tempest\Container\Initializer;
 use Tempest\Container\Singleton;


We still depend on container here, is that okay? container is only pulled in by require-dev.

xHeaven · 2026-03-12T20:11:24Z

There are also a couple Tempest\Core mentions regarding discovery in docs/1-essentials/05-discovery.md that are stale as the classes moved under Tempest\Discovery.

brendt added 3 commits March 11, 2026 10:47

Add registry

69a7c7b

Move things around, decouple things, make Aidan happy.

086545f

QA

e1c00bf

brendt requested a review from aidan-casey as a code owner March 11, 2026 10:10

brendt marked this pull request as draft March 11, 2026 10:10

QA

ad30d43

brendt added 8 commits March 11, 2026 11:39

Moving classes a-round, oh yeah, a-round.

e17108b

Aidan's gonna love reading these commit messages

fccc5c0

Making my code uglier, to make Aidan's code work.

8162e91

The atrocity is real

1eb5cff

Even cleanup can't save us…

2e1ca4c

The horror…

c76c35f

Cleaning up, as far as possible

d50348e

Wip. Yes, it's wip

57b2c2a

brendt added 14 commits March 11, 2026 19:41

Moarrr WIP — but actually getting somewhere. Aidan's gonna be so happy

e5e319b

Forgot to ran QA. Always a good idea

66c4a77

Did we actually… make it green?

8ae0a81

RectOOOOOOOOOOOOOAAAAAArrr

6410671

We did not make it green :(

7852936

Ok now it'll be green!

dda1183

No but now for real

f616bdc

Improvement, yes?

1d62fc6

Update docs

45b46b3

Remove container dependency from support

5876ebb

Update docs

029fdf1

Fix deps

00b9ca9

Making it faster, better, stronger

a7ab796

Docs

223fb13

brendt added 7 commits March 12, 2026 08:59

Docs, of course

ba94673

QA, of course

d991965

Testing

a606c0f

Fixing testing

1b7b3d3

Fixing testing

d1f28b1

QA

5ff8c02

QA

1880b21

brendt changed the title ~~refactor(core): decouple discovery~~ refactor(core)!: decouple discovery Mar 12, 2026

brendt marked this pull request as ready for review March 12, 2026 09:32

brendt requested a review from innocenzi as a code owner March 12, 2026 09:32

brendt marked this pull request as draft March 12, 2026 09:34

brendt added 2 commits March 12, 2026 11:01

Rector wip

c283ecf

Rector wip

d49074c

brendt marked this pull request as ready for review March 12, 2026 10:16

Fix cache path

47c0b6e

xHeaven requested changes Mar 12, 2026

View reviewed changes

packages/discovery/tests/DiscoveryTest.php Outdated Show resolved Hide resolved

packages/discovery/src/Composer.php Show resolved Hide resolved

brendt added 7 commits March 12, 2026 12:29

wip

317215b

Fix namespace

7a3a7b9

Remove registry

dd9d8d5

WIP

16ffd0c

WIP

0bf1bfe

WIP

87f754f

wip

72fe86a

brendt requested a review from xHeaven March 12, 2026 13:49

xHeaven requested changes Mar 12, 2026

View reviewed changes

	->assertContains('$this->kernel->registry->locations')
	->assertContains('$this->kernel->discoveryConfig->locations')

		'Tempest\Core\DiscoveryConfig' => 'Tempest\Discovery\DiscoveryConfig',
		'Tempest\Core\CouldNotStoreDiscoveryCache' => 'Tempest\Discovery\CouldNotStoreDiscoveryCache',


		### Manually specify discovery locations

		`DiscoveryConfig::autoload()` will scan a given root path and autmatically determine discovery locations by analyzing the composer.json file in that path. If you prefer another way of defining locations to scan, you can manually provide them via `DiscoveryConfig`:

		public array $discoveryLocations;

		public array $discoveryClasses;

		$this->discoveryLocations = $kernel->discoveryConfig->locations;
		$this->discoveryClasses = $kernel->discoveryConfig->classes;

Uh oh!

Conversation

brendt commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Upgrade Guide

Breaking changes:

Non-breaking changes:

Discovery as a standalone package

Manually specify discovery locations

Config and caching

Uh oh!

github-actions bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark Results

Uh oh!

iamdadmin commented Mar 11, 2026

Uh oh!

brendt commented Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xHeaven Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xHeaven commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brendt commented Mar 11, 2026 •

edited

Loading

github-actions bot commented Mar 11, 2026 •

edited

Loading

xHeaven Mar 12, 2026 •

edited

Loading