Skip to content

Service Providers

David Ciulla edited this page Nov 7, 2026 · 1 revision

Service Providers

Introduction

Service providers are the central place to configure and bootstrap every piece of your Laravex application — registering container bindings, configuring rate limiters, registering event listeners, defining middleware, and more. They are the Laravex equivalent of Laravel's ServiceProvider classes.


The Provider List

All providers are declared in bootstrap/providers.ex:

defmodule Bootstrap.Providers do
  def list do
    [
      App.Providers.AppServiceProvider,
      App.Providers.EventServiceProvider
    ]
  end
end

During application boot, Laravex.Foundation.Application.create/1 iterates Bootstrap.Providers.list/0 twice:

  1. Register phase — calls register/0 on every provider (if exported).
  2. Boot phase — calls boot/0 on every provider (if exported).

This two-phase approach mirrors Laravel exactly: all register callbacks complete before any boot callback runs, so providers can safely depend on bindings registered by other providers during boot.


Writing a Provider

A provider is a plain Elixir module with optional register/0 and boot/0 callbacks. No use or defstruct is required:

defmodule App.Providers.AppServiceProvider do
  def register do
    # Register container bindings here
    Laravex.Container.singleton(App.Services.PdfRenderer, fn _params ->
      App.Services.PdfRenderer.new()
    end)
    :ok
  end

  def boot do
    # Everything is registered; configure the application here
    Laravex.Http.RateLimiter.for("api", fn _req -> [max: 60, decay: 1] end)
    Laravex.Http.RateLimiter.for("web", fn _req -> [max: 120, decay: 1] end)
    :ok
  end
end

Both callbacks must return :ok (or any value — the return is ignored, but :ok is conventional).

register/0

Use register/0 exclusively for Service-Container bindings. Do not use services or raise exceptions here — other providers may not have registered their bindings yet.

boot/0

Use boot/0 for everything else:

  • Configuring rate limiters
  • Registering event listeners (see Events)
  • Setting up mail configurations
  • Defining model observers
  • Registering Blade directives or view composers
  • Any startup logic that depends on other providers being registered

Built-in Providers

App.Providers.AppServiceProvider

The primary application provider. The default implementation registers rate limiters for the "api" and "web" limiter groups:

defmodule App.Providers.AppServiceProvider do
  def register, do: :ok

  def boot do
    Laravex.Http.RateLimiter.for("api", fn _req -> [max: 60, decay: 1] end)
    Laravex.Http.RateLimiter.for("web", fn _req -> [max: 120, decay: 1] end)
    :ok
  end
end

This is where you should put your own service registrations.

App.Providers.EventServiceProvider

Registers event-to-listener mappings. See Events for the event system API.


Adding a New Provider

  1. Create a module in app/Providers/:

    # app/Providers/billing_service_provider.ex
    defmodule App.Providers.BillingServiceProvider do
      def register do
        Laravex.Container.singleton(App.Billing.Client, fn _params ->
          App.Billing.Client.connect(
            key: Laravex.Config.Repository.get("services.stripe.key")
          )
        end)
        :ok
      end
    
      def boot, do: :ok
    end
    
  2. Add it to bootstrap/providers.ex:

    defmodule Bootstrap.Providers do
      def list do
        [
          App.Providers.AppServiceProvider,
          App.Providers.EventServiceProvider,
          App.Providers.BillingServiceProvider   # ← new
        ]
      end
    end
    

Providers are booted in the order they appear in list/0.


Deferred Providers

Laravex does not currently implement deferred provider loading. All providers in Bootstrap.Providers.list/0 are registered and booted eagerly at startup. If a provider's register/0 is expensive, consider moving that work to boot/0 or lazily initializing it inside a singleton factory.


Provider Boot Order

Application.create/1
  │
  ├─ for each provider: provider.register()   ← register phase (all providers)
  │
  └─ for each provider: provider.boot()       ← boot phase (all providers)

Both phases are synchronous and run in process during OTP supervision startup. Providers that crash during register or boot will cause the supervisor to restart the application.

Clone this wiki locally