Deliver Order Bundle Laravel Package

Getting Started

This is the first tagged release (0.0.1) of tourze/deliver-order-bundle, and the release notes contain nothing beyond a changelog link — so treat the source as the only documentation.

Minimal steps:

1. Install and inspect what you actually got:

   composer require tourze/deliver-order-bundle
   

   Then read vendor/tourze/deliver-order-bundle/composer.json before writing any code. Look at require to see whether this pulls in symfony/framework-bundle, symfony/dependency-injection, doctrine/orm, or similar. The -bundle suffix strongly suggests Symfony bundle conventions rather than Laravel conventions.
2. Look at these first, in order:
   • README.md (if present) — likely thin or absent at 0.0.1.
   • src/*Bundle.php — the bundle class will tell you whether it implements Bundle from Symfony or has a Laravel-style service provider.
   • src/DependencyInjection/ — *Extension.php and Configuration.php reveal the entire config surface; this is the single most useful directory in any bundle.
   • src/Entity/ or src/Model/ — tells you whether it is Doctrine-based, Eloquent-based, or plain PHP.
   • Resources/config/ — service wiring and any default container parameters.
3. Resolve the framework mismatch early. For a Laravel app you will likely need to bridge manually: register the bundle's services in a custom ServiceProvider, and map its entities to Eloquent models or expose them as read models. Do not assume php artisan vendor:publish exists.
4. First use case to validate: install it, boot the app, and confirm the container compiles and the bundle's services resolve. A php artisan about or a trivial app()->make(SomeService::class) smoke test tells you more about viability than reading 20 files. Only after that attempt the real workflow — recording a delivery/fulfilment against an order and reading it back.

Because this is 0.0.x, pin an exact version in composer.json ("tourze/deliver-order-bundle": "0.0.1") and commit the lock file. There is no stability promise here.

Implementation Patterns

Treat it as a domain package, not a CRUD package. A "deliver order" bundle will most plausibly center on a delivery/fulfilment record tied to an order and a state (pending → shipped → delivered, or similar). The useful way to consume it is to wrap it behind your own application service rather than letting controllers touch its classes directly — this keeps a future 0.1.x/1.0 upgrade contained to one class.

Adapter/provider pattern for Laravel. Put the integration in a single dedicated provider:

// app/Providers/DeliverOrderServiceProvider.php
public function register(): void
{
    $this->app->singleton(DeliveryManager::class, fn ($app) => new DeliveryManager(
        $app->make(/* bundle service or repository */),
    ));
}

Bind the bundle's concrete classes to your own interfaces so application code depends on your contracts, not the vendor's.

State transitions as events. If the bundle exposes transitions, publish domain events from your wrapper (OrderMarkedDelivered) and subscribe Laravel listeners. This is also your escape hatch if the bundle's event naming changes — your listeners stay stable.

Configuration discipline. Any bundle Configuration.php should be mirrored into config/deliver-order.php and read from config() in your wrapper. Never read env() directly in application code; keep the bundle's tunables in one config file so a config-tree change on upgrade is a one-file edit.

Testing pattern. Because the package may be Doctrine-oriented while your app is Eloquent, write a thin repository adapter and test against that interface with an in-memory/fake implementation. Integration-test against a real database only in one or two tests; otherwise every upgrade breaks a large test suite for reasons unrelated to your code.

Workflow fit. Best suited to a bounded context: delivery/fulfilment tracking attached to an existing order aggregate you already own. Avoid letting it become the system of record for orders — keep your order model authoritative and let this package describe delivery of it.

Gotchas and Tips

• Framework mismatch is the headline risk. tourze/*-bundle packages are Symfony-oriented. In Laravel you will typically need symfony/* components available and a hand-written bridge. Verify that the bundle does not require a full Symfony kernel; if it does, budget real time for the bridge or reconsider.
• 0.0.1 means no compatibility contract. Semver below 1.0.0 permits breaking changes in the minor position, and at 0.0.x even patches may break. Pin exactly and re-read the diff before bumping.
• The release notes are effectively empty. There is no changelog content describing features, so do not infer capability from the package name alone. Enumerate the public classes under src/ and treat that as the API list.
• Check for a persistence assumption. If the entities are Doctrine-mapped, they will not work with Eloquent out of the box; either map them manually or write DTOs and repositories. Watch for Doctrine\ORM\Mapping imports — their presence is the tell.
• Bundle config tree validation is strict. Symfony config trees reject unknown keys by default. If you copy-paste config keys from a newer version into an older one, container compilation fails with a message that points at the config file, not the bundle. Read Configuration.php when that happens.
• No published docs means debugging is by reading services. When a service is missing, dump the compiled container (php artisan tinker → inspect the container, or Symfony's debug:container) and grep Resources/config/ for the service id. Most wiring questions are answered there.
• Extension points to inspect before you need them: any interface the bundle type-hints against (swap implementations), the bundle's event/subscriber classes (hook in without patching), and its config parameters (tune without forking). If none of those exist, treat the package as read-only and wrap it.
• Do not patch vendor code. With a 0.0.x dependency and a sparse changelog, your local patches are guaranteed to conflict. Wrap, don't fork; if you must fork, vendor it into your own namespace immediately.
• Re-assessment trigger: this assessment is provisional. Revisit when the package reaches 0.1.0 or publishes a real README/changelog — that is the point at which its API and framework assumptions become knowable.