Default Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require php-standard-library/default
   

   Add to composer.json under require or require-dev based on needs.

2. First Use Case Define a class implementing DefaultInterface:

   use PhpStandardLibrary\Default\DefaultInterface;
   
   class User implements DefaultInterface
   {
       public static function getDefault(): self
       {
           return new self('default@example.com', 'guest');
       }
   
       public function __construct(
           private string $email,
           private string $name
       ) {}
   }
   

   Use the default instance:

   $defaultUser = User::getDefault();
   

3. Where to Look First

   • Review DefaultInterface in src/DefaultInterface.php for contract details.
   • Check tests/ for usage examples and edge cases.

Implementation Patterns

Core Workflows

1. Standardized Defaults in Services

   class OrderService
   {
       public function createOrder(User $user = null): Order
       {
           $user = $user ?? User::getDefault();
           return new Order($user);
       }
   }
   

   • Useful for optional parameters with sensible fallbacks.

2. Dependency Injection

   // In Laravel's service container
   $app->bind(User::class, function () {
       return User::getDefault();
   });
   

   • Bind defaults globally for lazy initialization.

3. Factory Patterns

   class UserFactory
   {
       public static function createGuest(): User
       {
           return User::getDefault();
       }
   }
   

   • Encapsulate default logic in factories for cleaner code.

Integration Tips

• Laravel Facades: Extend facades to return defaults:

  class UserFacade extends Facade
  {
      public static function guest(): User
      {
          return User::getDefault();
      }
  }
  

• Form Requests: Use defaults in validation:

  public function rules()
  {
      return [
          'email' => 'required|email',
          'name'  => 'required|string',
      ];
  }
  
  public function prepareForValidation()
  {
      $this->merge([
          'email' => User::getDefault()->email,
          'name'  => User::getDefault()->name,
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. Immutable Defaults

   • Avoid modifying default instances directly; create copies if needed:

     $default = User::getDefault();
     $modified = clone $default;
     $modified->name = 'Admin';
     

   • Defaults may be shared across requests (e.g., in Laravel’s singleton container).

2. Thread Safety

   • If using static defaults in multi-threaded environments (e.g., queues), ensure thread-safe initialization:

     public static function getDefault(): self
     {
         static $instance = null;
         return $instance ?? ($instance = new self(...));
     }
     

3. Testing Quirks

   • Mock defaults in tests to avoid side effects:

     $this->mock(User::class)
         ->shouldReceive('getDefault')
         ->andReturn(new User('test@example.com', 'Test'));
     

Debugging Tips

• Verify Implementation: Use instanceof checks:

  if ($user instanceof DefaultInterface) {
      $default = $user::getDefault();
  }
  

• Override Defaults: Allow runtime overrides via config:

  config(['user.default' => ['email' => 'custom@example.com']]);
  
  // In User::getDefault()
  $config = config('user.default', ['email' => 'default@example.com']);
  return new self($config['email'], 'guest');
  

Extension Points

1. Dynamic Defaults
   • Use traits to generate defaults dynamically:

     trait DynamicDefault
     {
         public static function getDefault(): self
         {
             return new self(...self::defaultValues());
         }
     
         protected static function defaultValues(): array
         {
             return [];
         }
     }
     

2. Serialization
   • Implement __serialize()/__unserialize() to preserve defaults:

     public function __serialize(): array
     {
         return ['email' => $this->email, 'name' => $this->name];
     }
     
     public function __unserialize(array $data): void
     {
         $this->email = $data['email'] ?? User::getDefault()->email;
         $this->name = $data['name'] ?? User::getDefault()->name;
     }
     

3. Laravel Service Providers
   • Register defaults as singletons:

     $this->app->singleton(User::class, function () {
         return User::getDefault();
     });