feat(core)!: make discovery standalone

[brendt]

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 and config cache is cleared:

rm -r .tempest/cache/config
rm -r .tempest/cache/discovery
./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]

Benchmark Results

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

Open to see the benchmark results

Benchmark	Set	Mem. Peak	Time	Variability
ContainerBench(benchRegisterSingletonInstance)	-	3.871mb +39.90%	1.218μs +40.75%	±2.53% +53.75%
ContainerBench(benchRegisterDefinition)	-	3.871mb +57.22%	1.407μs +58.49%	±1.91% +109.73%
ContainerBench(benchRegisterInitializer)	-	3.906mb +48.34%	4.210μs +11.62%	±0.39% -55.86%
ContainerBench(benchRegisterDynamicInitializer)	-	3.907mb +43.80%	1.941μs +28.70%	±1.48% +17.48%
ContainerBench(benchRegisterClosureSingleton)	-	3.871mb +48.87%	1.262μs +38.41%	±1.37% +49.27%
KernelBootBench(benchBoot)	-	27.147mb +0.45%	102.288ms -6.18%	±0.33% -85.64%
DiscoveryScanBench(benchFullDiscoveryScan)	-	23.356mb +0.19%	14.827ms -72.43%	±1.27% -40.20%
DiscoveryScanBench(benchSinglePackageScan)	clock (small)	23.357mb +0.19%	88.835μs -95.40%	±1.14% +155.77%
DiscoveryScanBench(benchSinglePackageScan)	console (large)	23.357mb +0.19%	1.534ms -76.26%	±1.48% -2.88%
DiscoveryScanBench(benchSinglePackageScan)	router (large)	23.357mb +0.19%	1.034ms -86.39%	±1.53% +17.00%
ViewRenderBench(benchPlainHtml)	-	21.482mb +0.38%	477.952μs -5.29%	±2.43% +58.54%

_{Generated by phpbench against commit 2888faf}

[iamdadmin]

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

[xHeaven]

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]

TODO: make actions for discovery generate and discovery clean