Common Laravel Package

Getting Started

Minimal Setup

1. Installation Add to your project via Composer (though the README warns against direct inclusion):

   composer require dualmedia/common
   

   Best practice: Only include this via a private package or monorepo dependency if you're building a DualMedia ecosystem.

2. First Use Case Check the src/Contracts directory for shared interfaces (e.g., EntityInterface, RepositoryInterface). Example:

   use DualMedia\Common\Contracts\EntityInterface;
   
   class User implements EntityInterface {
       public function getId(): string { ... }
   }
   

3. Where to Look First

   • src/Contracts/: Core interfaces (e.g., RepositoryInterface, ServiceInterface).
   • src/Traits/: Reusable logic (e.g., Uuids, Timestamps).
   • src/Exceptions/: Shared exception hierarchy.

Implementation Patterns

Core Workflows

1. Interface Adoption Extend shared interfaces to enforce consistency across services:

   class ProductRepository implements \DualMedia\Common\Contracts\RepositoryInterface {
       public function findById(string $id): ?EntityInterface { ... }
   }
   

2. Trait Utilization Use traits for boilerplate (e.g., UUID handling):

   use DualMedia\Common\Traits\Uuids;
   
   class Order {
       use Uuids;
       protected string $id;
   }
   

3. Exception Handling Catch base exceptions and rethrow domain-specific ones:

   try {
       $repository->delete($id);
   } catch (\DualMedia\Common\Exceptions\NotFoundException $e) {
       abort(404);
   }
   

Integration Tips

• Laravel Service Providers: Bind interfaces to implementations in register():

  $this->app->bind(
      \DualMedia\Common\Contracts\RepositoryInterface::class,
      \App\Repositories\ProductRepository::class
  );
  

• Dependency Injection: Prefer constructor injection for interfaces:

  public function __construct(private RepositoryInterface $repository) {}
  

• Testing: Mock interfaces (e.g., RepositoryInterface) in unit tests.

Gotchas and Tips

Pitfalls

1. Direct Usage Warning The package is designed for internal DualMedia use. Avoid direct dependency unless you’re part of their ecosystem.

2. PHP 8.3+ Requirement Ensure your project meets the >=8.3 PHP version constraint.

3. Interface Rigidity Overly strict interfaces (e.g., EntityInterface::getId() returning string) may require workarounds for legacy systems.

Debugging

• Missing Methods: If implementing an interface fails, check for:
  • Undeclared return types (e.g., getId(): string).
  • Case sensitivity in method names.
• Trait Conflicts: Avoid naming collisions when using multiple traits.

Extension Points

1. Custom Exceptions Extend \DualMedia\Common\Exceptions\BaseException for domain-specific errors:

   class InvalidOrderException extends BaseException {}
   

2. Trait Overrides Override trait methods (e.g., generateUuid()) for custom logic:

   use DualMedia\Common\Traits\Uuids;
   
   class CustomOrder {
       use Uuids {
           generateUuid as private generateCustomUuid;
       }
       public function generateUuid(): string { ... }
   }
   

3. Repository Decorators Wrap implementations to add cross-cutting concerns:

   class LoggingRepository implements RepositoryInterface {
       public function __construct(private RepositoryInterface $decorated) {}
       public function findById(string $id): ?EntityInterface {
           Log::info("Finding ID: {$id}");
           return $this->decorated->findById($id);
       }
   }
   

Config Quirks

• No Config File: The package is logic-only; configuration is handled externally (e.g., Laravel’s config/services.php).