Tempest logo
Community Blog Docs
Essentials

Discovery

Tempest automatically locates controller actions, event handlers, console commands, and other components of your application, without needing any configuration from you.

Overview

Tempest introduces a unique approach to bootstrapping applications. Instead of requiring manual registration of project code and packages, Tempest automatically scans the codebase and detects the components that should be loaded. This process is called discovery.

Discovery is powered by composer metadata. Every package that depends on Tempest, along with your application's own code, are included in the discovery process.

Tempest applies various rules to determine the purpose of different pieces of code—it can analyze file names, attributes, interfaces, return types, and more. For instance, web routes are discovered when methods are annotated with route attributes:

app/HomeController.php
final readonly class HomeController
{
    #[Get(uri: '/home')]
    public function __invoke(): View
    {
        return view('home.view.php');
    }
}

Read the getting started with discovery guide if you want to know more about the philosophy of discovery and how it works.

Discovery in production

Discovery comes with performance considerations. In production, it is always cached to avoid scanning files on every request.

To ensure that the discovery cache is up-to-date, add the discovery:generate command before any other Tempest command in your deployment pipeline.

>_ ./tempest discovery:generate --no-interaction
Clearing discovery cache ..................................... 2025-12-30 15:51:46
Clearing discovery cache ..................................... DONE
Generating discovery cache using the `full` strategy ......... 2025-12-30 15:51:46
Generating discovery cache using the `full` strategy ......... DONE

Discovery for local development

During development, discovery is only enabled for application code. This implies that the cache should be regenerated whenever a package is installed or updated.

It is recommended to add the discovery:generate command to the post-package-update script in composer.json:

composer.json
{
	"scripts": {
		"post-package-update": [
			"@php tempest discovery:generate"
		]
	}
}

Disabling discovery cache

In some situations, you may want to enable discovery even for vendor code. For instance, if you are working on a third-party package that is being developed alongside your application, you may want to have discovery enabled all the time.

To achieve this, set the DISCOVERY_CACHE environment variable to false:

.env
DISCOVERY_CACHE=false

Troubleshooting

The discovery:clear command clears the discovery cache, which will be rebuilt the next time the framework boots. discovery:generate can be used to manually regenerate the cache.

If the discovery cache gets corrupted and even discovery:clear is not enough, the .tempest/cache/discovery may be manually deleted from your project.

Implementing your own discovery

While Tempest provides a variety of built-in discovery classes, you may want to implement your own to extend the framework's capabilities in your application or in a package you are building.

Discovering code in classes

Tempest discovers classes that implement Discovery, which requires implementing the discover() and apply() methods. The IsDiscovery trait provides the rest of the implementation.

The discover() method accepts a DiscoveryLocation and a ClassReflector parameter. The reflector can be used to loop through a class' attributes, methods, parameters or anything else. If the class matches your expectations, you may register it using $this->discoveryItems->add().

As an example, the following is a simplified version of the event bus discovery:

EventBusDiscovery.php
use Tempest\Discovery\Discovery;
use Tempest\Discovery\IsDiscovery;

final class EventBusDiscovery implements Discovery
{
    // This provides the default implementation for `Discovery`'s internals
    use IsDiscovery;

    public function __construct(
        // Discovery classes are autowired,
        // so you can inject all dependencies you need
        private EventBusConfig $eventBusConfig,
    ) {
    }

    public function discover(DiscoveryLocation $location, ClassReflector $class): void
    {
        foreach ($class->getPublicMethods() as $method) {
            $eventHandler = $method->getAttribute(EventHandler::class);

            // Extra checks to determine whether
            // we can actually use the current method as an event handler

            // …

            // Finally, we add all discovery-related data into `$this->discoveryItems`:
            $this->discoveryItems->add($location, [$eventName, $eventHandler, $method]);
        }
    }

    // Next, the `apply` method is called whenever discovery is ready to be
    // applied into the framework. In this case, we want to loop over all
    // registered discovery items, and add them to the event bus config.
    public function apply(): void
    {
        foreach ($this->discoveryItems as [$eventName, $eventHandler, $method]) {
            $this->eventBusConfig->addClassMethodHandler(
                event: $eventName,
                handler: $eventHandler,
                reflectionMethod: $method,
            );
        }
    }
}

Discovering files

It is possible to discover files instead of classes. For instance, view files, front-end entrypoints or SQL migrations are not PHP classes, but still need to be discovered.

In this case, you may implement the additional DiscoversPath interface. It requires a discoverPath() method that accepts a DiscoveryLocation and a string path.

The example below shows a simplified version of the Vite entrypoint discovery:

ViteDiscovery.php
use Tempest\Discovery\Discovery;
use Tempest\Discovery\DiscoversPath;
use Tempest\Discovery\IsDiscovery;
use Tempest\Support\Str;

final class ViteDiscovery implements Discovery, DiscoversPath
{
    use IsDiscovery;

    public function __construct(
        private readonly ViteConfig $viteConfig,
    ) {}

    // We are not discovering any class, so we return immediately.
    public function discover(DiscoveryLocation $location, ClassReflector $class): void
    {
        return;
    }

    // This method is called for every file in registered discovery locations.
    // We can use the `$path` to determine whether we are interested in it.
    public function discoverPath(DiscoveryLocation $location, string $path): void
    {
        // We are interested in `.ts`, `.css` and `.js` files only.
        if (! Str\ends_with($path, ['.ts', '.css', '.js'])) {
            return;
        }

        // These files need to be specifically marked as `.entrypoint`.
        if (! str($path)->beforeLast('.')->endsWith('.entrypoint')) {
            return;
        }

        $this->discoveryItems->add($location, [$path]);
    }

    // When discovery is cached, `discover` and `discoverPath` are not called.
    // Instead, `discoveryItems` is already fed with serialized data, which
    // we can use. In this case, we add the paths to the Vite config.
    public function apply(): void
    {
        foreach ($this->discoveryItems as [$path]) {
            $this->viteConfig->addEntrypoint($path);
        }
    }
}

Excluding files and classes from discovery

Files and classes may be excluded from discovery by providing a DiscoveryConfig configuration file.

src/discovery.config.php
use Tempest\Core\DiscoveryConfig;

return new DiscoveryConfig()
    ->skipClasses(GlobalHiddenDiscovery::class)
    ->skipPaths(__DIR__ . '/../../Fixtures/GlobalHiddenPathDiscovery.php');

Built-in discovery classes

Most of Tempest's features are built on top of discovery. The following is a non-exhaustive list that describes which discovery class is associated to which feature.