Package Auto-Discovery vs. Manual Registration in Laravel

Laravel package authors choose how an application loads a package’s service provider. A service provider connects a package to Laravel. It can register services and tell Laravel to load resources such as configuration, views, and routes. With auto-discovery, the package lists its provider in its own composer.json, and Laravel finds it after installation. With manual registration, the application owner adds the provider to the application’s provider list.

Auto-discovery is the convenient default when a Laravel package should integrate as soon as someone installs it. Manual registration suits packages whose Laravel integration should require an explicit choice. Application owners can opt out of discovery, so they still control whether Laravel activates a provider. Laravel’s package documentation describes both discovery and the opt-out.

How Laravel discovers a package provider

A package author enables auto-discovery by listing the provider under extra.laravel.providers in the package’s composer.json:

{
  "extra": {
    "laravel": {
      "providers": [
        "Acme\\Courier\\CourierServiceProvider"
      ]
    }
  }
}

Laravel reads this package metadata and registers the provider, so the application owner does not ordinarily need to edit a provider list. The provider controls what the package does. Its register method adds services to Laravel’s service container, which holds services for other parts of the code to use. Its boot method handles setup, such as loading routes or event listeners. Discovery determines how Laravel finds the provider; it does not change the provider’s responsibilities.

Auto-discovery is separate from PHP class autoloading. Composer generates the class autoloader, which lets PHP find classes by name. Laravel’s application skeleton runs artisan package:discover during Composer’s post-autoload-dump event. Composer’s scripts documentation describes that event and how Composer runs scripts.

Application owners can disable discovery for a particular package through the dont-discover setting in the application’s composer.json. Laravel also documents * as a way to disable discovery for all packages. An owner who opts out can still use the package by adding its provider manually.

How manual registration works

With manual registration, the package author leaves the provider out of the auto-discovery metadata and tells users which file to add it to. The file depends on the Laravel version. Laravel 10 documents the providers array in config/app.php; Laravel 11 documents the array returned by bootstrap/providers.php. Laravel’s Laravel 10 package instructions and Laravel 11 provider documentation show the version-specific locations.

For example, a Laravel 11 application can add the provider to bootstrap/providers.php:

return [
    App\Providers\AppServiceProvider::class,
    Acme\Courier\CourierServiceProvider::class,
];

A package’s installation instructions should not present one file path as if it applied to every supported Laravel version. Name the relevant versions and show the matching location for each. If the package supports versions with different provider-list files, provide separate instructions rather than asking readers to infer which example applies.

Choosing between convenience and explicit activation

Auto-discovery reduces setup steps. It fits a Laravel package whose provider should normally load as soon as the package is installed, such as an integration that registers services or loads package resources. Laravel presents discovery as a way to avoid requiring users to register providers themselves.

Manual registration makes provider activation an application-level choice. Choose manual registration when a package also serves non-Laravel PHP projects and its Laravel integration should remain optional. Choose it as well when the application owner needs to control provider activation directly. The owner must add the correct provider entry, so the package documentation needs to make that step clear.

Neither choice establishes a runtime performance advantage. A deferred provider, which Laravel loads only when its services are needed, is a separate provider behavior; choosing manual registration does not itself defer loading. Laravel discusses deferred providers separately in its service provider documentation.

Document the activation path clearly

For auto-discovery, explain that Laravel registers the provider automatically, so users ordinarily do not need to add it to the application’s provider list. Identify supported Laravel versions and explain how to opt out when that matters to your users. Also separate provider registration from other setup tasks. For example, if users must publish configuration or assets, say so explicitly; discovering a provider does not by itself mean those separate tasks have been completed.

For manual registration, name the provider class and give the exact file and version scope. Include a copyable example and say whether registration is the only activation step. If users can also opt out of discovery and register the provider manually, explain that relationship so they do not follow both paths by mistake.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com