Media Bundle Laravel Package

Getting Started

First, verify the framework before you run composer require. Despite the assessment title, every artifact points to this being a Symfony bundle (201Created\MediaBundle, *Bundle naming, a model.xml touched in a patch release, and explicit "Support for PHP 8 and Symfony 6" release notes). There is no service provider, no vendor:publish, no Laravel package discovery. If your target is Laravel, treat this as "framework-agnostic PHP I will wrap myself" and budget for the bridge; if you expected a drop-in Laravel package, stop here and compare against spatie/laravel-medialibrary or a plain Flysystem wrapper first.

Minimal steps (Symfony path):

1. Pin an exact tag — composer require 201created/media-bundle:2.1.0 (or whichever tag the spike validates). Do not use ^ constraints; there are zero dependents and no stated compatibility matrix, so you are the compatibility matrix.
2. Register the bundle in config/bundles.php (Symfony) or equivalent — this is the step a README would normally show you, and it does not exist. Read vendor/201created/media-bundle/src/ and the DependencyInjection/ folder to learn the bundle alias and config key before guessing.
3. Run bin/console debug:config <alias> and bin/console debug:container --tag=<whatever the compiler pass tags> to discover the actual service IDs and configuration tree. This is your substitute for documentation.
4. Stand up one upload against local disk before touching S3.

Where to look first. The README is literally the string test123 — it is not a source of truth. Go directly to:

• src/ for the public API surface (the media entity/abstraction and the upload entry point)
• DependencyInjection/Configuration.php for the real config schema
• Resources/config/ (or config/) for service wiring, especially anything registering PostProcessorPool
• model.xml — the presence of this in a patch changelog tells you the persistence/entity model is bundled and versioned here, so read it to understand the table shape before you write migrations

First use case. Attach a single image to one existing Doctrine entity and render it. That exercises the whole stack — storage write, metadata persistence, entity relation, and (if any processors are pre-registered by default) the post-processing pool. Keep it on an internal/admin surface so a hiccup during evaluation is recoverable.

Implementation Patterns

Put a seam between your domain and the bundle. The single most useful day-to-day pattern given the undocumented state is to define your own narrow contract and implement it with bundle calls behind it:

interface MediaStore
{
    public function attach(object $entity, UploadedFile $file): MediaRef;
    public function url(MediaRef $ref, ?string $variant = null): string;
    public function delete(MediaRef $ref): void;
}

Domain code depends on MediaStore, not on 201Created\MediaBundle\*. When the spike reveals the real API (or when you fork), you change one adapter class rather than every call site. This also makes the build-vs-buy decision reversible, which matters for a package with 3 stars and no dependents.

Attach via the entity relation, not raw IDs. The bundle's value proposition is "attach media to your Doctrine models." Model the relation on your entity (one-to-one for an avatar, one-to-many for a gallery) and let the bundle own the media record. Verify during the spike whether it creates its own table or writes polymorphically — that determines whether your migrations reference its table or extend it.

Treat PostProcessorPool as an extension point, not a default. The 1.5.2 patch touching PostProcessorPool.php is the one concrete signal about derived-asset generation (thumbnails, resized variants). The day-to-day pattern is: register your processors into the pool, keep each processor small and idempotent, and assume synchronous execution until proven otherwise. If it runs inline on upload, wrap the call in your own queued job so a slow resize doesn't tie up a PHP worker:

// Your job, not the bundle's
final class StoreMediaJob implements ShouldQueue
{
    public function handle(MediaStore $store): void
    {
        $store->attach($this->entity, $this->file);
    }
}

Because you control the seam, you can move the upload off the request path immediately and defer the question of whether the bundle's pool is queue-backed.

Storage configuration lives in config, swap adapters behind it. The stated purpose is a reusable media abstraction across backends. Configure local disk in dev/test and S3-compatible storage in staging early — the spike should prove both, because "swappable adapters" is the claim the whole adoption case rests on. If swapping requires code changes, that's a finding, not a footnote.

Strangler/feature-flag pattern for adoption. Route one non-critical upload surface (admin avatar, internal attachment) through the bundle behind a flag, keep the legacy handler warm, and run a full sprint before migrating the media table. Do not plan a phased "full migration" until that pilot has produced evidence — the prior planning artifacts assumed documentation and production validation that do not exist.

Test against a fake filesystem. Use an in-memory or temp-directory adapter in tests so integration tests don't hit S3, and assert on both the persisted media record and the storage write — post-processor failures can leave one without the other.

Gotchas and Tips

• The README is a placeholder. test123. Do not scope work from it, do not quote it in a design doc, and do not assume any documented public API. The source is the spec; budget a timeboxed source read (2–3 days) before committing to any roadmap item.
• Framework identity is the highest-risk unknown. Everything says Symfony 6 / PHP 8. Symfony 7 support is unstated and unproven. If you're Laravel-first and want zero glue code, the honest answer is that this doesn't fit and the integration cost is yours to own.
• Post-processor failure atomicity is unverified. If a processor throws mid-upload, you may get an orphaned file, a missing derivative, or a half-written record — silently. Confirm behavior in the spike and add a compensating cleanup job keyed on the media record.
• Entity deletion likely leaves media behind. Storage creep and GDPR exposure both live here. Verify cascade/soft-delete behavior explicitly and add a retention job regardless of what the package does.
• Security posture is undocumented. No prose on MIME sniffing, size caps, path traversal, or signed URLs. Enforce an allowlist, size cap, and Content-Disposition at your edge before exposing any upload endpoint to low-trust users. The model.xml/entity path handling in particular deserves a tenant-prefix review if you're multi-tenant.
• Zero dependents means no field-tested version matrix. You are the first integration. Pin exact tags, read the diff between them on upgrade, and keep fork rights ready under MIT.
• Datestamp oddity. The latest release is dated 2026-05-21, ahead of the assessment. Verify actual cadence from git tags rather than release metadata before assuming active maintenance.
• Debugging tips. In Symfony, debug:container will show you the real service IDs and which compiler pass registers the pool; the profiler's Doctrine panel shows the media table writes. Because there's no docs, keep a running one-page internal API reference from the spike — it's the difference between a second engineer onboarding in an hour versus a day.
• Budget for fork-and-own. Single-agency ownership, no issue-tracker signal, no commercial tier advertised. MIT makes the fork legally clean but not free. Name an internal owner and put periodic source review into the platform team's capacity plan rather than assuming it away.
• Recommended gate. If the spike can't produce (a) confirmation of framework fit and (b) a self-authored API reference, pre-commit to not adopting and extend your existing upload code instead. That's the reversible decision; an unmaintained abstraction in your upload path is not.