Contracts Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require charcoal-dev/contracts
   

   No configuration is required—this is a pure contract package with zero runtime dependencies.

2. First Use Case: Defining a Custom Contract Extend the base Charcoal\Contracts\Foundation\FoundationContract or use standalone interfaces:

   use Charcoal\Contracts\Foundation\FoundationContract;
   
   class MyService implements FoundationContract
   {
       public function __invoke(): void
       {
           // Implementation
       }
   }
   

3. Where to Look First

   • src/Contracts/: Core interfaces (e.g., FoundationContract, ServiceContract).
   • src/Traits/: Optional reusable traits (e.g., HasDependencies).
   • README.md: Framework-agnostic design principles (if available).

Implementation Patterns

1. Dependency Injection Readiness

Use contracts to enforce DI-compatible interfaces:

use Charcoal\Contracts\Service\ServiceContract;

class UserRepository implements ServiceContract
{
    public function find(int $id): ?UserModel
    {
        // ...
    }
}

• Integration Tip: Pair with Laravel’s bind() or tag() in AppServiceProvider:

  $this->app->bind(UserRepository::class, function ($app) {
      return new UserRepository($app->make(Database::class));
  });
  

2. Modular Service Layers

Organize contracts by domain (e.g., Auth/, Payment/):

app/Contracts/
├── Auth/
│   ├── AuthenticatorContract.php
│   └── TokenManagerContract.php
└── Payment/
    └── GatewayContract.php

3. Testing with Contracts

Mock contracts in unit tests:

$this->mock(ServiceContract::class)
     ->shouldReceive('execute')
     ->once();

4. Leveraging Traits

Use provided traits for common patterns:

use Charcoal\Contracts\Traits\HasDependencies;

class LoggerService implements ServiceContract
{
    use HasDependencies;

    protected $dependencies = [LoggerInterface::class];
}

Gotchas and Tips

Pitfalls

1. No Runtime Behavior Contracts are interfaces only—implementations must be provided elsewhere (e.g., Laravel services). Avoid expecting magic methods or default logic.

2. Namespace Collisions If extending Laravel’s built-in contracts (e.g., Illuminate\Contracts\Auth\Authenticatable), prefix your contracts (e.g., App\Contracts\Auth\Authenticatable).

3. Over-Engineering Resist creating contracts for trivial classes. Focus on abstraction boundaries (e.g., repositories, gateways).

Debugging

• Missing Implementations: Use php artisan tinker to verify bound services:

  $this->app->make(UserRepository::class); // Should resolve without errors.
  

• Interface Mismatches: Enable strict typing (declare(strict_types=1)) and IDE hints (PHPStorm/VsCode) to catch unimplemented methods early.

Extension Points

1. Custom Contracts Extend FoundationContract for framework-specific needs:

   namespace App\Contracts;
   
   use Charcoal\Contracts\Foundation\FoundationContract;
   
   interface QueueWorkerContract extends FoundationContract
   {
       public function process(string $payload): void;
   }
   

2. Dynamic Binding Use Laravel’s when() for conditional contract resolution:

   $this->app->when(ServiceContract::class)
              ->needs(LoggerInterface::class)
              ->give(function ($app) {
                  return new FileLogger();
              });
   

3. Documentation Add PHPDoc @method annotations for IDE autocompletion:

   /**
    * @method void execute()
    */
   interface ServiceContract {}