Download the PHP package arxy/files without Composer

About

Provides easy file management (with persistence layer for metadata).

• Uses FlySystem for File management (this allows you to use existing adapters to save files anywhere)
• Persist file information in database
• Uses checksums (md5) to prevent double upload (thus saving space). If same file is found - it's reused
• Automatic hooks that manages the files (on entity persist file will be uploaded, on entity remove - file will be removed)
• Different naming strategies for handling files.

Usage

Configuring

Create the object which will holds the file

In case you want to use embeddable instead of Entity for file object:

Create the repository.

Or using plain services:

or using pure PHP

Upload file

In case of embeddable:

Please note that file is not actually moved to its final location until file is persisted into db, which is done by Listeners. (Arxy\FilesBundle\DoctrineORMListener for example)

Upload using form Type:

Read file content

Read stream

This bundle also contains form and constraint for uploading and validating files. You can write your own naming strategy how files are created on Filesystem. You can even write your own FileSystem backend for Flysystem and use it here.

Currently, only Doctrine ORM is supported as persistence layer. Feel free to submit PRs for others.

Serving files from controller

1. Serving with Controller

Create the controller which will serve files.

If you want to force different download name, you can decorate file with Arxy\FilesBundle\Utility\DownloadableFile:

Serving

You might want to use LiipImagineBundle or CDN solution, or even controller.

Directly

If you want directly to serve file with CDN, you can use Path Resolver + Normalizer:

You will receive following json as response:

LiipImagineBundle

If you want to use it with LiipImagineBundle, you probably could add something like that:

and fill these from Event Listener or ORM Listener or Serializer Normalizer.

here is example with Serializer Normalizer:

You will receive following json as response:

Naming Strategies:

Naming strategy is responsible to converting File object to filepath. Several built-in strategies exists:

DateStrategy

Use file's createdAt property. Default format: Y/m/d/hash. Example: 2021/05/17/59aeac36ae75786be1b573baad0e77c0

SplitHashStrategy

Use file's md5hash and split it into chucks. Example: 098f6bcd4621d373cade4e832627b4f6 will result in 098f6bcd/4621d373/cade4e83/2627b4f6/098f6bcd4621d373cade4e832627b4f6

UuidV5Strategy

Uses UUID V5 to generate hash for file. It consists of namespace (configurable) and value (Uses md5Hash of file).

AppendExtensionStrategy

Decorator which adds extension of file (.jpg, .pdf, etc).

DirectoryPrefixStrategy

Decorator which prefixes the generated directory of another naming strategy.

NullDirectoryStrategy

Decorator which always return null directory.

PersistentPathStrategy

Use persisted pathname in file. Useful if you want to generate completely random path for each file. (For example UUID v4) or you just want the path to the file persisted for some reason. Expects instanceof Arxy\FilesBundle\Model\PathAwareFile. It's your responsibility to handle the path itself. You can do that with custom Arxy\FilesBundle\ModelFactory (recommended) or use built in Event Listener, which will set the pathname on upload (Arxy\FilesBundle\EventListener\PathAwareListener)

UUID V4 Strategy:

Generates random path.

Migrating between naming strategy.

Register Migrator service and command:

then run it.

PathResolver: used to generate browser URL to access the file. Few built-in resolvers exists:

AssetsPathResolver:

AwsS3PathResolver:

AzureBlobStoragePathResolver:

AzureBlobStorageSASPathResolver:

• Decorator that accepts Arxy\FilesBundle\PathResolver\AzureBlobStoragePathResolver and adds SAS Signature

Create AzureBlobStorageSASParametersFactory instance that will be responsible for creating parameters for signature.

CachePathResolver:

Used to cache the result from decorated Path Resolver. Useful for example in conjunction with AwsS3PathResolver, where to get the path to uploaded file, an API call is made. This resolver will cache the response from AWS S3 servers and next time you need the file path, it will be returned from cache. Uses https://symfony.com/doc/current/components/cache.html

DelegatingPathResolver:

Used when your system have multiple file entities:

You can also combine Manager and PathResolver into one, using PathResolverManager decorator, so you can use singe instance for both operations:

There is also DelegatingManager, which can be used as router to different other managers, supporting different classes.

Then you can do: $manager->getManagerFor(File::class)->upload($file). Note: If you do directly $manager->upload($file) - it will call first manager's upload method. Reading is even easier: Just pass the $file directly, it will determine the correct inner manager for that file. $manager->read($file)

Sending additional parameters to path resolver.

Ok, we have path generated to our files now, but what if we want to represent same file, differently? Obviously we cannot do this currently. Let's change that! Let's say we need to enforce different download name.

1. We start by creating decorated file.

2. Then we create/decorate also the path resolver

3. Then we can use path resolver as usual:

Twig Extensions:

1. Arxy\FilesBundle\Twig\FilesExtensions:

• int 12345|format_bytes(int $precision = 2) - format bytes as kb,mb, etc.
• Arxy\FilesBundle\Model\File $file|file_content - return the contents of file.

2. Arxy\FilesBundle\Twig\PathResolverExtension:

• file_path(Arxy\FilesBundle\Model\File $file) - return downloadable path for file using path resolver.

LiipImagine:

If you need to generate thumbnails for your files, you could use built-in integration with LiipImagineBundle:

1. Setup LiipImagineBundle.
2. Register Arxy\FilesBundle\LiipImagine\FileFilterPathResolver as service.
3. Use service from point2 as follows: $pathResolver->getPath(new \Arxy\FilesBundle\LiipImagine\FileFilter($file, 'filterName'));

Usage with API Platform:

Uploading

Events

PostUpload

Arxy\FilesBundle\Events\PostUpload event is called right after File object is created. It is NOT called if existing file is found and re-used. At this moment file is located on local FS.

PreMove

Arxy\FilesBundle\Events\PreMove event is called right before File object is moved into its final location. At this moment file is still located locally. so ManagerInterface::getPathname() returns local filepath.

PostMove

Arxy\FilesBundle\Events\PostMove event is called right after File object is moved into its final location. At this moment file is located in FlySystem. so ManagerInterface::getPathname() returns filepath generated from naming strategy.

PreUpdate

Arxy\FilesBundle\Events\PreUpdate event is called right before File object is updated through write, writeStream.

PostUpdate

Arxy\FilesBundle\Events\PostUpdate event is called right after File object is updated through write, writeStream.

PreRemove

Arxy\FilesBundle\Events\PreRemove event is called right before file is deleted from filesystem.

Preview

There is a sub-system for preview generation for files: It generates preview and saves it as another file. There are 2 ways to enable it:

1. Synchronous generation: Arxy\FilesBundle\Preview\PreviewGeneratorListener

2. Asynchronous generation using Symfony Messenger: Arxy\FilesBundle\Preview\GeneratePreviewMessageHandler Arxy\FilesBundle\Preview\PreviewGeneratorMessengerListener

And then register common services:

Currently, only image preview generator exists. You can add your own image preview generator. Just implement the Arxy\FilesBundle\Preview\PreviewGeneratorInterface.

Known issues

• If file entity is deleted within transaction and transaction is rolled back - file will be deleted. I'm waiting for DBAL 3.2.* release to be able to fix that.