Doctrine Flysystem Bundle Laravel Package

Product Decisions This Supports

• File Storage Abstraction: Enables seamless integration of file storage (e.g., S3, local FS, cloud) into Doctrine entities, reducing vendor lock-in and simplifying migrations.
• Symfony Media Library: Core component for a media management system (e.g., user uploads, document repositories, or asset libraries) where files are tied to entities (e.g., Post, UserProfile).
• Build vs. Buy: Avoids reinventing file upload/management logic, saving dev time while adhering to Symfony/Doctrine best practices.
• Roadmap Priorities:
  • Phase 1: Basic file uploads for user-generated content (e.g., avatars, attachments).
  • Phase 2: Multi-cloud storage (e.g., fallback to local FS if S3 fails) via Flysystem adapters.
  • Phase 3: Extend to Doctrine ODM (MongoDB) for non-relational use cases.
• Use Cases:
  • User Profiles: Store profile pictures with metadata (size, MIME type).
  • Content Management: Attach files to blog posts, products, or support tickets.
  • Legacy Migration: Replace custom file-handling logic with a standardized approach.

When to Consider This Package

• Adopt If:

  • Your app uses Symfony 2.3+ and Doctrine ORM (not ODM).
  • You need file metadata persistence (e.g., size, MIME type) alongside entities.
  • You’re already using Flysystem or plan to adopt it for storage abstraction.
  • You want to decouple file storage from business logic (e.g., switch from local FS to S3 later).
  • Your team prefers traits over inheritance for reusable behavior.

• Look Elsewhere If:

  • You need active development/maintenance (last release: 2016; no dependents).
  • Your stack uses Symfony 4+ (compatibility untested; requires symfony/symfony: ~2.3|~3.0).
  • You require advanced features like file validation, virus scanning, or chunked uploads (consider VichUploaderBundle instead).
  • You’re using Doctrine ODM (incomplete support).
  • You need modern PHP 8+ support (package targets PHP 5.4–7.x).

How to Pitch It (Stakeholders)

For Executives: "This package lets us standardize file storage across our Symfony app—whether files live on local servers, AWS S3, or Google Cloud—without rewriting upload logic. It’s like a ‘save’ button for files that works the same way as our database. For example, when a user uploads a profile picture, we’ll store the file and its metadata (size, type) in the same transaction as their user record. This cuts dev time, reduces bugs, and makes it trivial to switch storage providers later. The trade-off? It’s a niche tool (last updated in 2016), but it’s battle-tested in Symfony 2/3 and aligns with our tech stack."

For Engineers: *"This bundle adds a Flysystem-powered file storage trait to Doctrine entities, handling:

• Automatic file persistence: Uploaded files are saved to configured storage (local, S3, etc.) and linked to entities.
• Metadata sync: File name, size, MIME type, and path are stored in the DB.
• Lifecycle events: Hooks for pre/post-store/delete actions (e.g., rename files, validate before upload).
• Multi-storage: Copy files to multiple backends (e.g., primary + backup).

Why not build it?

• Saves ~2–4 weeks of dev time (handles edge cases like file deletion, path sanitization).
• Future-proof: Swap storage adapters without changing business logic.
• Gotchas:
  • No Symfony 4+ support (but we can fork if needed).
  • ODM support is incomplete (stick to ORM for now).
  • Last release is old, but the core logic is stable.

Proposal:

1. Pilot: Use it for user avatars in the next sprint (low-risk).
2. Extend: Add S3 adapter for production files.
3. Monitor: Watch for forks or consider maintaining it if critical."*