Container Facade Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require geekcell/container-facade
   

2. Register the Service Provider Add to config/app.php under providers:

   Geekcell\ContainerFacade\ContainerFacadeServiceProvider::class,
   

3. Publish Config (Optional)

   php artisan vendor:publish --provider="Geekcell\ContainerFacade\ContainerFacadeServiceProvider"
   

4. Define a Static Facade Create a facade class extending Geekcell\ContainerFacade\ContainerFacade:

   namespace App\Facades;
   
   use Geekcell\ContainerFacade\ContainerFacade;
   
   class MyServiceFacade extends ContainerFacade
   {
       protected static $serviceName = 'my.service'; // Matches your container binding
   }
   

5. Bind the Service in Container In a service provider:

   $this->app->bind('my.service', function ($app) {
       return new \App\Services\MyService();
   });
   

6. Use the Facade

   use App\Facades\MyServiceFacade;
   
   MyServiceFacade::doSomething(); // Resolves via container
   

First Use Case

Replace direct instantiation of a service with a facade for cleaner, testable code:

// Before
$service = new MyService();

// After
MyServiceFacade::doSomething();

Implementation Patterns

Workflow: Facade Creation

1. Identify Reusable Services Target services used across multiple classes (e.g., logging, caching, APIs).

2. Facade Naming Convention Use *Facade suffix (e.g., LoggerFacade, CacheFacade) for clarity.

3. Service Binding Bind interfaces or concrete classes to the container for flexibility:

   $this->app->bind('App\Contracts\LoggerInterface', function ($app) {
       return new \App\Services\LogService();
   });
   

4. Facade Methods Mirror the service’s public methods in the facade:

   class LoggerFacade extends ContainerFacade
   {
       protected static $serviceName = 'App\Contracts\LoggerInterface';
   
       public static function emergency($message) {
           return static::getContainer()->get(static::$serviceName)->emergency($message);
       }
   }
   

Integration Tips

• Laravel-Specific: Works seamlessly with Laravel’s IoC container. Prefer facades for services not tied to HTTP requests (e.g., background jobs, CLI commands).
• Testing: Mock the container binding in tests:

  $this->app->instance('my.service', Mockery::mock(\App\Services\MyService::class));
  

• Avoid Overuse: Reserve facades for truly shared services. Overuse can obscure dependencies and hurt testability.
• Dynamic Facades: For dynamic service names, override getServiceName():

  protected static function getServiceName()
  {
      return config('services.dynamic_key');
  }
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies Facades resolve services on-demand, which can hide circular dependency issues. Test thoroughly.

2. Container Not Bootstrapped Facades fail silently if the container isn’t initialized (e.g., in non-Laravel contexts). Ensure the service provider is registered.

3. Static Facade State Facades cache the resolved service instance. Clear the cache if the service is stateful:

   MyServiceFacade::flush(); // If implemented
   

4. Namespace Collisions Ensure facade namespaces are unique to avoid autoloading conflicts.

Debugging

• Service Not Found: Verify the binding name in $serviceName matches the container key.
• Method Not Found: Check if the facade method proxies to the correct service method.
• Container Binding Issues: Use app()->bound('service.name') to verify bindings.

Config Quirks

• Default Config: The package publishes a minimal config (config/container-facade.php) for global settings (e.g., default namespace for facades).
• Override Service Name: Use setServiceName() dynamically if needed:

  MyServiceFacade::setServiceName('new.service');
  

Extension Points

1. Custom Resolution Logic Override resolveService() to add pre/post-resolution logic:

   protected static function resolveService()
   {
       $service = static::getContainer()->get(static::$serviceName);
       // Add logic (e.g., logging, middleware)
       return $service;
   }
   

2. Facade Events Trigger events before/after resolution by extending the facade:

   protected static function beforeResolve()
   {
       event(new ServiceResolving(static::$serviceName));
   }
   

3. Facade Groups Create a base facade for shared functionality:

   abstract class BaseFacade extends ContainerFacade
   {
       protected static function getContainer() { /* custom logic */ }
   }