Sulu Shared Tools Bundle Laravel Package

Getting Started

Install the package with Composer and let Laravel's package discovery register the service provider:

composer require vendor/package:^0.2.0

There is nothing to publish to get started — the 0.2.0 release ships shared classes you consume directly. Start by browsing the source tree, roughly organized as:

• src/Traits/ — reusable behavior to use inside your own classes
• src/Contracts/ (or src/Interfaces/) — contracts to type-hint and implement
• src/Listeners/ — ready-made event listeners you can register
• src/Services/ — service classes intended for container resolution

Look at the interfaces first: they document the contract the traits and services satisfy, so they tell you what each shared class is for faster than reading implementations.

First use case: pick one trait that matches a concern you already hand-roll (e.g. a "has status" or "sluggable"-style trait), use it in a model, and confirm the expected columns/attributes. This is the lowest-risk way to validate the package before wiring in interfaces and services.

Implementation Patterns

Composing traits into your own classes. Traits are the most direct entry point. Apply them one at a time and let your IDE/static analysis surface any required properties or methods the trait expects:

use Vendor\Package\Traits\HasSharedBehavior;

class Order extends Model
{
    use HasSharedBehavior;
}

Implementing the provided interfaces. Use the package contracts as type hints in your own code so you stay decoupled from concrete classes. Your implementation must match the interface signatures exactly — this is where most integration friction shows up after a minor bump.

use Vendor\Package\Contracts\SharedServiceContract;

class MyService implements SharedServiceContract { /* ... */ }

Registering the shared event listeners. The listener classes are ordinary Laravel listeners. Register them in EventServiceProvider (or via Event::listen) and map them to your own events rather than assuming the package ships event-to-listener mappings:

protected $listen = [
    OrderShipped::class => [
        Vendor\Package\Listeners\HandleSharedEvent::class,
    ],
];

Resolving services from the container. Treat the service classes as bindable dependencies. If the package registers bindings in its provider, resolve by interface; otherwise app(SomeService::class) or constructor-inject the concrete class and bind it yourself in a service provider for testability.

Dependency injection over instantiation. Because 0.2.0 introduces interfaces, prefer constructor injection of the contract and bind your chosen implementation in a provider. This keeps you free to swap the package service for a fake in tests.

Gotchas and Tips

• Trait name collisions. If you already use a trait with the same method names, PHP will fatal on conflict. Resolve with insteadof, or alias the method (HasSharedBehavior::boot() as bootShared). Check method names before adding a second trait to the same class.
• Traits may carry boot hooks. Laravel-style traits can define boot{TraitName} / initialize{TraitName} methods. If behavior seems to "just happen," look for those hooks before assuming a service provider is doing it.
• Interface changes are the real breaking surface. 0.2.0 is a 0.x release, so SemVer protections are weak — pin the exact version (^0.2.0) and read the diff of any interface you implement before upgrading. Adding a method to an interface is effectively a breaking change for your implementers.
• Listener registration is not automatic. Unless the service provider wires them, shared listeners do nothing until you map them. If an event isn't handled, verify EventServiceProvider first, then php artisan event:list.
• Container bindings. If app(MyService::class) returns a fresh instance each time when you expected a singleton, add an explicit singleton() binding in your provider. Don't rely on implicit resolution order for shared services.
• Static analysis pays off. Run PHPStan/Larastan with a strict level; traits and interfaces are exactly the surface where missing properties and signature mismatches surface cheaply instead of at runtime.
• Testing. Bind a fake implementation of the package interface in your test case's setUp so tests don't hit real listeners/services. This is the main payoff of the new interface layer.
• Extension points. Subclassing a service is easy; overriding a trait is not. If you expect to customize behavior heavily, implement the interface yourself rather than using the trait and patching around it.
• Debugging shared code. When something misfires, php artisan about plus a quick dd(class_uses(YourModel::class)) confirms which traits are actually applied — useful when a trait is pulled in transitively via a parent class.

This is the first published assessment, so there is no prior baseline to diff against; the 0.2.0 shared-class surface (traits, interfaces, listeners, services) is documented above as the starting point for day-to-day use.