Download the PHP package team-mate-pro/doctrine-utils-bundle without Composer

Team Mate Pro Doctrine Utils Bundle

A Symfony bundle providing Doctrine utilities for file persistence with Flysystem storage backends.

Features

• Automatic file upload to Flysystem storage on entity persist
• Automatic file deletion from storage on entity removal
• Automatic entity timestamping (createdAt/updatedAt)
• Configurable storage backends (local, S3, Azure, etc.)
• Enable/disable functionality via configuration
• Factory pattern for flexible entity integration
• Reusable entity traits (AutoIncrementIdTrait, UuidIdTrait)

Requirements

• PHP 8.3+
• Symfony 7.0+
• Doctrine ORM 3.0+
• League Flysystem 3.0+

Installation

Register the Bundle

If you're not using Symfony Flex, add the bundle to config/bundles.php:

Configuration

Create config/packages/team_mate_pro_doctrine_utils.yaml:

Configuration Options

Setup

1. Use the Built-in File Entity (Recommended)

The bundle provides a ready-to-use File entity with UUID-based IDs:

The built-in File entity:

• Uses UuidIdTrait for UUID-based primary keys
• Implements FileInterface from team-mate-pro/contracts
• Includes isWebImage() helper method
• Supports optional fileUrl for public URLs (S3, CDN, etc.)
• Provides File::createFromUploadedFile(UploadedFile $file) for Symfony file uploads
• Provides File::createFromInterface(FileInterface $file) for copying from other implementations

Register Doctrine Mapping for the Built-in Entity

To use the built-in File entity, you need to register its mapping in your Doctrine configuration.

Add to config/packages/doctrine.yaml:

Then generate and run the migration:

The migration will create the files table with the following structure:

2. Custom File Entity (Optional)

If you need a custom entity, implement TeamMatePro\Contracts\Model\FileInterface:

Then create a custom factory implementing EntityFileFactoryInterface:

Register your custom factory in config/services.yaml:

3. Configure Flysystem Storage

Using league/flysystem-bundle:

Or define your own Flysystem service:

Usage

Once configured, the bundle automatically handles file persistence:

Disabling File Persistence

To disable the listener without removing the bundle:

When disabled, the service is completely removed from the container (zero overhead).

Using Different Storage Backends

AWS S3

Azure Blob Storage

Testing

Timestamp Listener

The bundle provides automatic timestamping for entities implementing TimeStampAbleInterface.

Setup

1. Enable the listener in configuration:

2. Implement TimeStampAbleInterface on your entity:

The listener automatically calls timestamp() on:

• prePersist - When entity is first persisted
• preUpdate - When entity is updated

Entity Traits

AutoIncrementIdTrait

Provides auto-incrementing integer ID functionality for Doctrine entities.

The trait provides:

• protected ?int $id - Auto-incrementing primary key
• getId(): string - Returns the ID as string (or 'N/A' if not yet persisted)

UuidIdTrait

Provides UUID-based ID functionality for Doctrine entities using Symfony UID component.

The trait provides:

• protected Uuid $id - UUID primary key (requires manual initialization in constructor)
• getId(): string - Returns the UUID as string

Helper Functions

The bundle provides utility functions for UUID binary conversion:

Usage in Doctrine Queries

Troubleshooting

Verify Factory Registration

Check Listener Registration

Clear Cache

License

See LICENSE file.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.