Skip to content

Latest commit

 

History

History
210 lines (151 loc) · 5.46 KB

README.md

File metadata and controls

210 lines (151 loc) · 5.46 KB
Raw

EntityFileBundle

With this bundle, you can attach files to entities.

Installation

composer require 2lenet/entity-file-bundle

Configuration

This bundle works with configurations. A configuration = 1 entity 1 file system.

For example, you may have a configuration for the logo of multiple sellers, and a configuration for the pictures of the products they sell.

Basic configuration

In lle_entity_file.yaml

lle_entity_file:
    configurations:
        seller_logos:
            class: "App\\Entity\\Seller"
            storage_adapter: "lle_entity_file.storage.default"

That's it! With the default storage adapter configuration, those files will be saved under data/seller_logos

Change the storage adapter

This bundle uses the FlySystem Symfony Bundle. You can create your own storage adapters, (Local disk, FTP, Drive...).

For that, you need to configure a new adapter. Then, change the storage_adapter of your configuration.

Usage

First of all, you need to get the manager for your configuration. For that, use the Lle\EntityFileBundle\Service\EntityFileLoader

$manager = $entityFileLoader->get("seller_logos");

Create a file

$entityFile = $manager->save($seller, $data, $path);

$this->em->persist($entityFile);
$this->em->flush();

$data may be a string, a Symfony File object (including UploadedFile) or a resource.

⚠️ Never forget to persist and flush the EntityFile.

  • I want my EntityFile to contain additional properties!

You can use your own Entity class, it needs to be a Doctrine entity that implements Lle\EntityFileBundle\Entity\EntityFileInterface. For your convenience, the trait LleEntityFileBundle\Entity\Trait\EntityFileTrait exists.

You will also have to update your configuration:

unicorn:
    # ...
    entity_file_class: "App\\Entity\\UnicornEntityFile"
  • I want to edit my new properties!
$entityFile = $manager->save($seller, $data, "unicorn.png");

$entityFile->setDescription("Picture of a very sexy unicorn");
$this->em->persist($entityFile);
$this->em->flush();
  • I want to have a dynamic path in my file structure!
$manager->save($order, $data, "you/can/do/this");

// example:

$dir = $order->getDate()->format("Y-m");
$name = $order->getId() . ".xml";

$manager->save($order, $data, $dir . "/" . $name)
  • For some reason, I want to save my files somewhere else than data

Create your own storage adapter in flysystem.yaml, which is basically a copy of the default one with different directory option.

flysystem:
    storages:
        unicorn.storage:
            adapter: "local"
            options:
                directory: "%kernel.project_dir%/unicorns"
                permissions:
                    file:
                        public: 511
                        private: 511
                    dir:
                        public: 511
                        private: 511

Retrieve files

$manager->get($seller);
$manager->getOne($seller);

Retrieve files from URL

If you didn't use Symfony Flex, you need to add the routes in routes.yaml:

lle_entity_file:
    resource: "@LleEntityFileBundle/Resources/config/routes.yaml"

Two routes are available:

  • lle_entityfile_entityfile_read (requires configName and id)
    Example: /lle-entity-file/seller_logos/1
  • lle_entityfile_entityfile_readbypath (requires configName and path)
    Example: /lle-entity-file/seller_logos?path=2le.png

Protect your urls

By default, only logged in users can access those urls. You can change the role key in the configuration:

operation_reports:
    # ...
    role: "ROLE_OPERATOR"
  • I want the files to be public !

You can use "PUBLIC_ACCESS" in the role key.

  • I want to do something more complex !

Create a custom voter.

Change content disposition (Show in browser or automatically download)

By default, files are served inline. You can change the disposition key under your configuration:

zip_reports:
    # ...
    disposition: "attachment"

Access file contents

$manager->read($file);
$manager->readStream($file);

Delete a file

// deletes the entity and the actual file
$manager->delete($file);

Rename or move a file

$manager->move($file, "actually_not_an_unicorn.png");
$this->em->flush();

⚠️ Never forget to flush the EntityFile.

Exception handling

https://flysystem.thephpleague.com/docs/usage/exception-handling/

Crudit

This bundle is compatible with 2LE's Crudit bundle.

You can use the EntityFileBrick, for example in tabs:

  public function getTabs(): array
  {
      return [
          "tab.files" => EntityFileBrickConfig::new("seller_logos"),
      ];
  }

It features a dropzone where you can see, add, remove and download files.