Check Format Bundle Laravel Package

Getting Started

v2.0 changes one thing: the bundle now accepts Symfony 5 (previously Symfony 4-only or 4.x-capped). Nothing else. There is no Laravel support, no service-provider glue, no config publishing, no new features. Treat the verdict from the previous review as unchanged and adjust only the why.

Before writing any integration code, confirm what you actually have: despite the imanaging-document vendor name, check-format-bundle is a Symfony bundle, not a Laravel package. That single fact shapes every step below.

Minimal steps:

1. Inspect composer.json at the v2.0 tag first. Expect "type": "symfony-bundle", require containing symfony/framework-bundle (now ^4.4|^5.0) plus symfony/dependency-injection and symfony/config. The PHP floor will be Symfony 5's (>=7.2.5), so the old "caps at PHP 7.4" concern is gone — the blocker is now the Symfony component major, not PHP.
2. Diff v1.x...v2.0 before assuming anything. The release note is a one-liner; verify the tag is a constraint bump and not a code change. git diff --stat should show composer.json and little else. If that's all it is, your integration risk profile is identical to v1.
3. Read the Bundle class and Resources/config/services.*. That tells you which concrete services exist (a format checker, a filesystem/path mapper) and what they depend on. Those two services are the only parts you'd realistically reuse.
4. Try the install on a throwaway branch, then read the failure. Laravel 10/11 pins symfony/console, symfony/http-foundation, symfony/process, etc. at ^6.2/^7.0; a Symfony 5 bundle drags the whole symfony/* tree toward 5.4 and Composer will refuse. Confirm with composer why-not imanaging-document/check-format-bundle, don't guess.
5. Look for the service definitions, not the bundle wiring. In Symfony the bundle registers services into a container; in Laravel you have no such container. You instantiate the underlying classes yourself inside a ServiceProvider.

First use case to target: validating uploaded documents against an expected format and resolving a logical file path to a physical storage location. That is the narrow slice worth proving out before committing to it.

Implementation Patterns

Wrap the services in a Laravel service provider. Do not try to boot the Symfony bundle. Pick the two or three classes you need (format checker, mapping resolver) and bind them:

// app/Providers/CheckFormatServiceProvider.php
public function register(): void
{
    $this->app->singleton(FormatChecker::class, function ($app) {
        // pass config explicitly — the Symfony bundle would
        // normally inject this via services.yaml
        return new FormatChecker(config('check-format.allowed'));
    });

    $this->app->singleton(FileSystemMapper::class, function ($app) {
        return new FileSystemMapper(config('check-format.mapping'));
    });
}

Publish your own config file. The bundle ships config under Resources/config (Symfony convention), not a Laravel config/ file. Copy the keys you need into config/check-format.php and drive everything from there — never read from the bundle's YAML at runtime.

Use it as a custom validation rule. The highest daily-leverage integration for a Laravel dev is a rule wrapping the format checker:

class AllowedFormat implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (! app(FormatChecker::class)->check($value->getPathname())) {
            $fail("The {$attribute} has an unsupported format.");
        }
    }
}

Then 'document' => ['required', 'file', new AllowedFormat] in a FormRequest. This keeps the package behind a boundary you control.

Map storage paths through your own filesystem config. "Mapping file system" in this bundle means resolving logical identifiers to physical paths. Mirror that intent in config/filesystems.php and let the mapper translate between a logical key and a Laravel disk:

$path = app(FileSystemMapper::class)->resolve($logicalKey);
Storage::disk('documents')->put($path, $contents);

Batch and queue. Format checks against large uploads belong in a job, not the request cycle. Dispatch CheckDocumentFormat and write the result back to the model. This also keeps you insulated if the checker is slow or throws.

If you genuinely need the bundle's runtime behaviour, isolate it. A ~20-line Symfony 5 microservice (or a symfony/framework-bundle-only throwaway app) that exposes POST /check is far cheaper than fighting Composer inside your Laravel app. Call it from a queued job. Only do this if the format rules turn out to be non-trivial — see the ROI note below.

Testing pattern. Use Storage::fake('documents') and UploadedFile::fake()->create('x.pdf') for happy paths, plus a real fixture for the format checker — fakes don't exercise real mime detection.

Gotchas and Tips

• v2.0 raises the Symfony floor, not the Laravel ceiling. Symfony 5 is itself end-of-life, and Laravel 10/11 ship Symfony 6.2/7 components. The new constraint makes the bundle installable in more Symfony apps while remaining just as uninstallable in a current Laravel app. Don't read "compatible symfony 5" as "now Laravel-friendly."
• Don't --ignore-platform-reqs your way past the conflict. You'll get Symfony 5.4 components silently coexisting with Laravel's Symfony 6/7 ones — duplicate-class errors, odd container behaviour, and bugs that only surface in production. If Composer says no, believe it.
• A one-line changelog is not maintenance. v2.0 shows someone bumped a constraint. There's still no Laravel integration, no tests, no meaningful changelog, no dependent ecosystem. Pin the exact tag, and if you vendor the code, note the fork point in your README.
• Symfony container coupling is the main failure mode. Even "plain" service classes often type-hint ContainerInterface, ParameterBagInterface, or read from %kernel.parameters%. If the checker does, you cannot instantiate it standalone — extract the logic or replace it. Symfony 5's ContainerBuilder behaves the same as 4's here; nothing about the upgrade helps you.
• No Laravel auto-discovery, no config:publish, no facade. You write all the glue. Budget for that, or skip the package and reimplement (see below).
• Mime detection depends on ext-fileinfo. If the checker uses finfo or mime_content_type, verify the extension is enabled in every environment (local, CI, prod). Mismatched results between environments are a classic source of "works on my machine" bugs.
• Path mapping is a security boundary. Validate that a resolved path stays inside the intended base directory before writing or reading. Reject .. segments and absolute paths supplied by users, even if the mapper claims to normalise them.
• Config quirks live in the bundle's YAML, not your config/. If a key is missing at runtime, it's usually because you copied the wrong key name from the Symfony config tree. Read Configuration.php (the TreeBuilder) for the authoritative schema.
• Extension points are thin. If the bundle exposes interfaces for checker or mapper implementations, use them — swapping in your own implementation is far cheaper than patching vendor code. If it exposes none, that's a strong signal to reimplement.
• Honest ROI call: for the two features advertised — format checking and filesystem mapping — the equivalent Laravel-native code is typically 50–100 lines using finfo, Storage, and a small config array. v2.0 does not change that arithmetic. Keep the bundle as a spec reference for the exact format rules it enforces; write the implementation yourself against symfony/* 6/7 so it stays upgradeable with Laravel.