Laravel Service Providers – Complete Guide to register(), boot() & Deferred Providers

PHASE 1 — register()
─────────────────────────────────────────────────────────────────
Called first on ALL providers before any boot() runs.
Purpose: bind things into the service container — ONLY.

✅ DO:   $this->app->bind(...)
✅ DO:   $this->app->singleton(...)
❌ DON'T: use other services (they may not be registered yet)
❌ DON'T: register event listeners, routes, view composers here

PHASE 2 — boot()
─────────────────────────────────────────────────────────────────
Called after ALL providers have completed register().
Every service is available and safe to use here.

✅ DO:   View::composer(...)
✅ DO:   Event::listen(...)
✅ DO:   Route::macro(...)
✅ DO:   Validator::extend(...)
✅ DO:   Model::observe(...)
✅ DO:   Type-hint dependencies in boot() signature

Provider A → register()  ┐
Provider B → register()  ├── ALL register() calls run first
Provider C → register()  ┘
         ↓
Provider A → boot()      ┐
Provider B → boot()      ├── ALL boot() calls run after
Provider C → boot()      ┘

<?php

namespace App\Providers;

use App\Services\Riak\Connection;
use Illuminate\Support\ServiceProvider;

class RiakServiceProvider extends ServiceProvider
{
    /**
     * PHASE 1 — bind into container only
     * Called before any boot() method runs.
     */
    public function register(): void
    {
        $this->app->singleton(Connection::class, function ($app) {
            return new Connection(config('riak'));
        });
    }

    /**
     * PHASE 2 — configure app behavior
     * All services are now registered and safe to use.
     */
    public function boot(): void
    {
        // View composers, event listeners, model observers, macros...
    }
}

// Key property available in both methods:
// $this->app  →  the Service Container itself

<?php

class AppServiceProvider extends ServiceProvider
{
    // Registered as bind() calls
    public $bindings = [
        ServerProvider::class => DigitalOceanServerProvider::class,
    ];

    // Registered as singleton() calls
    public $singletons = [
        DowntimeNotifier::class => PingdomDowntimeNotifier::class,
        ServerProvider::class   => ServerToolsProvider::class,
    ];
}

// When to use properties vs register():
//   Properties   → simple class-to-class bindings, no extra setup
//   register()   → need closures, config values, or sub-dependencies

public function boot(ResponseFactory $response): void
{
    // Add a custom macro to the response factory
    $response->macro('serialized', function (mixed $value) {
        return response()->json(['data' => serialize($value)]);
    });
}

// This works because by the time boot() runs,
// everything has been registered into the container.

<?php

// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    App\Providers\ComposerServiceProvider::class,
    App\Providers\PaymentServiceProvider::class,
];

php artisan make:provider MyServiceProvider
# Creates app/Providers/MyServiceProvider.php
# AND automatically adds it to bootstrap/providers.php

<?php

namespace App\Providers;

use App\Services\Riak\Connection;
use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class RiakServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(Connection::class, function ($app) {
            return new Connection($app['config']['riak']);
        });
    }

    // Tell Laravel exactly what this provider offers
    public function provides(): array
    {
        return [Connection::class];
    }
}

App boots
  → Laravel reads provides() from all deferred providers
  → Stores map: "Connection::class → RiakServiceProvider"
  → Does NOT load RiakServiceProvider yet ← performance win

Someone calls app(Connection::class) or type-hints Connection
  → Laravel checks its deferred map
  → Loads RiakServiceProvider NOW (register + boot)
  → Returns the Connection instance

✅ Defer when: provider ONLY registers container bindings
✅ Defer when: service is not needed on every request
              (e.g. Riak, Stripe, specialized integrations)

❌ Don't defer if: boot() registers global event listeners
❌ Don't defer if: boot() has side effects needed on every request
                  (route registration, middleware, global observers)

public function register(): void
{
    $this->app->bind(Interface::class, Implementation::class);
    $this->app->singleton(Cache::class, fn($app) => new Cache($app['config']));
    $this->app->instance('key', $prebuiltObject);
}

public function boot(): void
{
    // View composers
    View::composer('profile', ProfileComposer::class);

    // Event listeners
    Event::listen(UserRegistered::class, SendWelcomeEmail::class);

    // Model observers
    User::observe(UserObserver::class);

    // Custom validation rules
    Validator::extend('uppercase', fn($attr, $val) => strtoupper($val) === $val);

    // Route macros
    Route::macro('apiResource', function (...) { /* ... */ });

    // Blade directives
    Blade::directive('datetime', fn($exp) => "<?php echo $exp->format('Y-m-d'); ?>");

    // Gates and policies
    Gate::define('update-post', fn($user, $post) => $user->id === $post->user_id);

    // Response macros
    Response::macro('api', fn($data) => response()->json(['data' => $data]));
}

Provider                        What it bootstraps
──────────────────────────────  ──────────────────────────────────────────
AuthServiceProvider             Gates, policies, auth guards
EventServiceProvider            Event → Listener mappings
RouteServiceProvider            Route files (web.php, api.php), rate limiting
DatabaseServiceProvider         Eloquent, DB connections, query builder
QueueServiceProvider            Queue connections, workers, job dispatch
MailServiceProvider             Mailer, transport drivers (SMTP, SES, etc.)
CacheServiceProvider            Cache drivers and repository
FilesystemServiceProvider       Storage disks, Flysystem adapters
BroadcastServiceProvider        WebSocket broadcasting channels
ValidationServiceProvider       Validator factory and rules

app/Providers/
├── AppServiceProvider.php        ← General bindings, misc boot logic
├── AuthServiceProvider.php       ← Gates and policies
├── EventServiceProvider.php      ← Event → Listener mappings
├── RouteServiceProvider.php      ← Route loading, rate limiters
└── (your custom providers)
    ├── PaymentServiceProvider.php
    ├── NotificationServiceProvider.php
    └── ReportingServiceProvider.php

php artisan make:provider PaymentServiceProvider
# Creates app/Providers/PaymentServiceProvider.php
# Adds it to bootstrap/providers.php automatically

public function register(): void
{
    $this->app->singleton(PaymentGateway::class, function ($app) {
        return new StripeGateway(config('services.stripe.secret'));
    });
}

public function boot(): void
{
    Event::listen(PaymentFailed::class, NotifyAdminListener::class);
    User::observe(UserObserver::class);
}

// Add if this provider only registers bindings and
// the service isn't needed on every request
class PaymentServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function provides(): array
    {
        return [PaymentGateway::class];
    }
}

Request arrives
     │
     ▼
bootstrap/app.php → creates Application (Service Container)
     │
     ▼
HTTP Kernel bootstrappers run:
     │
     ├── 1. LoadEnvironmentVariables  → reads .env
     ├── 2. LoadConfiguration         → loads config/ files
     ├── 3. HandleExceptions          → registers error handlers
     │
     ├── 4. RegisterProviders
     │       → reads bootstrap/providers.php
     │       → instantiates each provider
     │       → calls register() on each  ← PHASE 1
     │
     └── 5. BootProviders
             → calls boot() on each      ← PHASE 2
     │
     ▼
Middleware Stack → Router → Controller → Response

❌ Using a service inside register():
   public function register(): void {
       // WRONG — EventDispatcher may not be registered yet
       Event::listen(...);
   }

❌ Forgetting to add provider to bootstrap/providers.php:
   Your bindings silently don't exist.
   Use make:provider to avoid this.

❌ Putting everything in AppServiceProvider:
   Fine for small apps. For large apps, split by domain.

❌ Deferring a provider that registers event listeners in boot():
   If deferred, boot() only runs when the service is resolved —
   your listeners won't fire if nothing resolves the service first.

❌ Calling DB or external services inside register():
   Config is available, but the DB connection and other services
   may not be. Move cross-service logic to boot().

// In your package's composer.json:
"extra": {
    "laravel": {
        "providers": ["VendorName\\PackageName\\PackageServiceProvider"]
    }
}
// Laravel will automatically register it — no manual providers.php edit needed.