Service Providers
Apiato service providers are just Laravel Service Providers, and they function in the exact same way as Laravel service providers. However, they come with additional rules and conventions specific to Apiato.
To generate new service providers
you may use the apiato:generate:provider
interactive command:
php artisan apiato:generate:provider
There are two distinct types of service providers within a container:
the Main Service Provider
and additional service providers.
The Main Service Provider serves as the central registration point for all custom service providers within the container.
It orchestrates the setup and integration of these custom providers,
ensuring the seamless functioning of your application's components.
Rulesβ
- You MUST NOT register any Service Provider in the
config/app.php
(except Laravel default service providers). - Each Container:
- MAY have one or many Service Providers.
- MUST have a
Main Service Provider
->App\Containers\{Section}\{Container}\Providers\MainServiceProvider
class.- MUST be named
MainServiceProvider
. - MUST extend the
App\Ship\Parents\Providers\MainServiceProvider
class.- The parent extension SHOULD be aliased as
ParentMainServiceProvider
.
- The parent extension SHOULD be aliased as
- MUST be named
- All container-specific Service Providers:
- MUST be placed in the
app/Containers/{Section}/{Container}/Providers
directory. - MUST be registered in their respective container's
App\Containers\{Section}\{Container}\Providers\MainServiceProvider
class.
- MUST be placed in the
- All general Service Providers:
- MUST be placed in the
app/Ship/Providers
directory. - MUST be registered in the
App\Ship\Prviders\ShipProvider
class.
- MUST be placed in the
- All non-Laravel or third-party package Service Providers:
- MUST extend the
App\Ship\Parents\Providers\MainServiceProvider
class. - The parent extension SHOULD be aliased as
ParentMainServiceProvider
.
- MUST extend the
- When using Laravel default service providers:
AuthServiceProvider
MUST extendApp\Ship\Parents\Providers\AuthServiceProvider
.BroadcastServiceProvider
MUST extendApp\Ship\Parents\Providers\BroadcastServiceProvider
.EventServiceProvider
MUST extendApp\Ship\Parents\Providers\EventServiceProvider
.MiddlewareServiceProvider
MUST extendApp\Ship\Parents\Providers\MiddlewareServiceProvider
.RouteServiceProvider
MUST extendApp\Ship\Parents\Providers\RouteServiceProvider
.- The parent extension SHOULD be aliased as
Parent{ServiceProviderName}
. For example:ParentAuthServiceProvider
.
Folder Structureβ
The highlighted sections showcase service provider registration points:
MainServiceProvider.php
acts as the central registration point for custom service providers specific to a container.ShipProvider.php
acts as the central registration point for the Ship (general) service providers.
app
βββ Containers
β βββ Section
β βββ Container
β βββ Providers
β βββ AuthServiceProvider.php
β βββ BroadcastServiceProvider.php
β βββ EventServiceProvider.php
β βββ MainServiceProvider.php
β βββ MiddlewareServiceProvider.php
β βββ RouteServiceProvider.php
β βββ CustomServiceProvider.php
β βββ ...
βββ Ship
βββ Providers
βββ RouteServiceProvider.php
βββ ShipProvider.php
βββ ...
Code Exampleβ
Main Service Provider:β
use ...
use App\Ship\Parents\Providers\MainServiceProvider as ParentMainServiceProvider;
class MainServiceProvider extends ParentMainServiceProvider
{
// This providers will be automatically registered
public array $serviceProviders = [
CustomServiceProvider::class,
MiddlewareServiceProvider::class,
PassportServiceProvider::class,
// ...
];
public array $aliases = [
// ...
];
}
Register Providersβ
The registration process for a service provider varies depending on its intended scope within the application. Different places are designated for different levels of service provider usage.
In essence, the decision of where to register a service provider boils down to two key factors: the scope of service provider usage and the logical location for its registration.
Container Service Providersβ
Main Service Providerβ
A container Main Service Provider
will be automatically registered by Apiato
so manual registration isn't necessary.
In turn,
Main Service Providers will register all service providers listed in their $serviceProviders
property.
Additional Service Providersβ
To register a provider,
add the provider's class name to the serviceProviders
array in the App\Containers\{Section}\{Container}\Providers\MainServiceProvider
class.
public array $serviceProviders = [
CustomServiceProvider::class,
AnotherCustomServiceProvider::class,
EventsServiceProvider::class,
// ...
];
You can also list aliases in the $aliases
property of the App\Containers\{Section}\{Container}\Providers\MainServiceProvider
class.
public array $aliases = [
'CustomAlias' => CustomFacade::class,
'AnotherCustomAlias' => AnotherCustomFacade::class,
// ...
];
General Service Providersβ
General service providers must be registered in the App\Ship\Providers\ShipProvider
class.
This can be done by adding the provider class name to the serviceProviders
array.
public array $serviceProviders = [
CustomServiceProvider::class,
AnotherCustomServiceProvider::class,
EventsServiceProvider::class,
// ...
];
Third Party Service Providersβ
When dealing with third-party packages that require service provider registration in config/app.php
,
you should follow these guidelines:
-
Specific Container Usage: If the package is used within a particular container, register its service provider in that container
App\Containers\{Section}\{Container}\Providers\MainServiceProvider
class. -
Framework-wide Usage: If the package is generic and used throughout the entire application, you can register its service provider in the
App\Ship\Prviders\ShipProvider
class. However, avoid registering it directly inconfig/app.php
.
Laravel Service Providersβ
Apiato introduces a refined organization for Laravel service providers.
By default, Laravel standard service providers,
located in the app/providers
directory,
have been restructured in Apiato to reside in the app/Ship/Parents/Providers
directory.
Here's the mapping of Laravel's default service providers to their new locations in Apiato:
App\Providers\AppServiceProvider
βApp\Ship\Parents\Providers\MainServiceProvider
- Note: Laravel
AppServiceProvider
is renamed toMainServiceProvider
in Apiato.
- Note: Laravel
App\Providers\AuthServiceProvider
βApp\Ship\Parents\Providers\AuthServiceProvider
App\Providers\BroadcastServiceProvider
βApp\Ship\Parents\Providers\BroadcastServiceProvider
App\Providers\EventServiceProvider
βApp\Ship\Parents\Providers\EventServiceProvider
App\Providers\RouteServiceProvider
βApp\Ship\Parents\Providers\RouteServiceProvider
You should not modify these providers directly.
Instead, extend them within your container's Providers
directory.
For instance,
the App\Containers\AppSection\Authentication\Providers\AuthServiceProvider
class extends App\Ship\Parents\Providers\AuthServiceProvider
.
Those providers are not auto registered by default,
thus writing any code there will not be available, unless you extend them.
Once extended, the child Service Provider should be registered in its container MainServiceProvider
,
which makes it available.
Do note that the App\Ship\Parents\Providers\RouteServiceProvider
is a unique case.
Because it's required by Apiato, it is registered by the App\Ship\Prviders\ShipProvider
and is loaded automatically.
Service Providers Registration Flowβ
If you want to understand the service provider registration process, here is a breakdown of the registration flow.
Consider the following folder structure:
app
βββ Containers
β βββ Section
β βββ ContainerA
β β βββ Providers
β β βββ CustomServiceProvider.php ββββββββββΊβββββββββ
β β βββ EventServiceProvider.php ββββββββββΊβββββββββ€
β β βββ MainServiceProvider.php βββregisteredβinββββ
β β βββ ...
β βββ ContainerB
β βββ Providers
β βββ AnotherCustomServiceProvider.php βββββββββΊβββββββββ
β βββ EventServiceProvider.php βββββββββΊβββββββββ€
β βββ MainServiceProvider.php βββregisteredβinββββ€
β ββ β MiddlewareServiceProvider.php βββββββββΊβββββββββ
β βββ ...
βββ Ship
βββ Providers
βββ CustomGeneralServiceProvider.php βββββββββΊβββββββββ
βββ RouteServiceProvider.php βββββββββΊβββββββββ€
βββ ShipProvider.php βββregisteredβinββββ
βββ ...
The following diagram illustrates the registration flow of service providers in the above folder structure: