Builder Bundle Laravel Package

Getting Started

Release cadence is the first thing to internalise: v3.0.1 is a single-line patch that fixes one Symfony deprecation, and it is the only maintenance signal since the v3.0.0 line was cut. Read that as alive but not actively developed — the package gets deprecation sweeps, not features. Adoption is still 2 stars with no dependents, so the source remains your documentation. Budget 20–30 minutes in src/ before wiring it in.

Install, pinned to the patch

composer require iter8/builder-bundle:3.0.1

Settle the framework question first — the changelog just answered most of it. v3.0.1 is a Symfony deprecation fix, which confirms the -bundle suffix: treat this as a Symfony bundle that happens to be installable via Composer in a Laravel app. Verify in composer.json:

• type: symfony-bundle → you'll need manual wiring if you run a Symfony app (config/bundles.php), and on Laravel you get no auto-discovery and no extra.laravel.providers — you instantiate builders yourself.
• extra.laravel.providers present → then the Symfony deprecation fix is incidental and you can rely on discovery. Confirm with php artisan package:discover.

In a Laravel codebase, plan on the first branch: no provider, no config tag, no facade. Wiring is yours to write.

Where to look first, in order:

1. composer.json — PHP and framework constraints. Check whether v3.0.0's constraints actually admit your Laravel/Symfony version, or merely don't exclude it.
2. src/ — the Builder contract or abstract base. Everything else implements it.
3. src/*/*Builder.php — shipped concrete builders show the intended granularity better than any prose.
4. tests/ — the de facto usage examples. Copy setup from a test case rather than guessing.
5. config/*.php — publish if a tag is offered, so you see every knob at once. If there's no publish tag, there's no config registry; stop looking for one.

First use case. Instantiate a shipped concrete builder, run it end-to-end on a fixture, and dump the result. That answers "what does this actually produce?" before you write a subclass. If no concrete builder runs standalone, it was extracted from a host application and expects context you don't have — reconsider the dependency at that point.

Implementation Patterns

Subclass the base builder, don't fork it. The value is the base class's fluent pipeline; your job is the terminal step.

use Iter8\BuilderBundle\Builder; // verify exact namespace in src/

class InvoiceBuilder extends Builder
{
    protected function build(): Invoice
    {
        return new Invoice(
            number: $this->get('number'),
            lines:  $this->get('lines', []),
        );
    }
}

Fluent configuration, terminal resolution. Match whatever the package already does — if build() is terminal upstream, don't invent ->get() in your subclass.

$invoice = InvoiceBuilder::make()
    ->withNumber('INV-001')
    ->withLines($lines)
    ->build();

Bind builders in your own provider. With no auto-discovered Laravel provider, this is entirely on you — and it's the highest-leverage step, because it makes builders swappable in tests and keeps new out of controllers.

// AppServiceProvider::register()
$this->app->bind(InvoiceBuilder::class, fn () => new InvoiceBuilder());

Compose builders rather than deepening one. If the package ships a builder for a sub-object (address, line item), call it from the parent's build() instead of duplicating its logic.

protected function build(): Invoice
{
    return new Invoice(
        lines: array_map(
            fn ($row) => LineBuilder::make()->fromArray($row)->build(),
            $this->get('lines', [])
        ),
    );
}

Push it behind an action, not into controllers. Wrap the invocation in a single-purpose class (CreateInvoice) so the app depends on your action, not the package. When you replace it, you change one file.

In tests, build fixtures through the builder — it keeps test data honest:

$invoice = InvoiceBuilder::make()->withNumber('T-1')->withLines([])->build();

If the builder has side effects (writes, events, HTTP), that's a design smell — isolate the side effect into a decorator and keep the builder pure so fixtures stay fast.

Macros, if supported. If the base class is Macroable, register a macro in a provider for one-off tweaks. Subclass once you need a distinct terminal type.

Gotchas and Tips

v3.0.1 tells you nothing about v3.0.0 — and v3.0.0 is where the risk lives. If you're coming from the 1.x/2.x line, a major bump happened and this changelog only covers the patch on top of it. Read the v3.0.0 release notes and diff before upgrading, and pin exactly ("iter8/builder-bundle": "3.0.1") rather than a ^3.0 range that will silently absorb 3.1.

A deprecation fix is not a compatibility commitment. v3.0.1 proves someone still runs the test suite against a current Symfony. It does not prove Laravel 11/12 support, and it says nothing about the next deprecation cycle. Check the constraints: an uncapped one that installs cleanly and then fatals on a removed contract is worse than an obvious install failure. Add one happy-path integration test so a future framework upgrade fails loudly.

State leakage on long-running workers. Fluent builders that accumulate state in instance properties are the classic bug here. Under Octane, queue workers, or a container singleton, a reused instance carries the previous call's data. Verify by calling build() twice with different inputs. Mitigate with bind() — never singleton() — plus a fresh instance per operation.

make() vs new. Static factories often resolve through a container or cache configuration. Mixing the two gives you two behaviours. Pick one and enforce it in review — in Laravel this matters more, since there's no bundle container doing the resolving for you.

Silent defaults. Builders love optional setters that quietly default to null/[]/false, so a missing ->withX() yields a valid-looking but wrong object with no exception. Add validation in your terminal build() for anything the domain requires.

Debugging fluent chains. Chains swallow intermediate state — dump inside the terminal method, not at the call site. Add a temporary dump()/ray($this->all()) at the top of build(). Prefer toArray()/all() if it exists; that's usually the only window into accumulated state.

Extension points to check before subclassing: a Builder contract (implementing is cheaper than extending), the abstract build() you must fulfil, Macroable, and any config-driven registry of builder classes. A registry means swapping implementations without touching call sites — the cheapest insurance against the package stalling again.

Plan for the project to go quiet. One patch after a long gap is not a revival. If you need a fix upstream won't ship, fork to a VCS repository and pin the commit — never edit vendor/, which vanishes on the next composer install:

"repositories": [{"type": "vcs", "url": "[email protected]:yourorg/builder-bundle.git"}]

Keep an exit criterion and a usage note. Record which of the package's classes you actually touch — with no upgrade notes, that list is your migration checklist. Define the trigger now: "if a framework upgrade is blocked and v3.x hasn't moved, we absorb src/ into app/Support/Builder/." Deciding in advance turns a fire drill into a planned afternoon.