Paths and URLs

The path and filename of a stored file is generated by a path builder. The event listener that stored your file used a path builder to generate the path based on the entity data. This means that if you have the entity and instantiate a path builder, you can rebuild the path to the file anywhere.

The plugin provides several convenience shortcuts to do that.

Use the same builder and options

Whenever you use a path builder, you must use the same path builder and options that were used when the entity was created. They are usually the same as those configured in your event listener — otherwise you end up with a different path.

From an entity

Entities from this plugin (or those extending them) implement the PathBuilderTrait. This lets you set and get the path builder on the entities.

You can't pass options to the entity when calling Table::newEntity(). There are two workarounds.

Set it manually on the entity instance:

$entity->pathBuilder('PathBuilderName', ['options-array' => 'goes-here']);
$entity->path(); // path in the storage backend to the file
$entity->url();  // URL to the file, if possible

Or do it in the constructor of the entity. Pay attention to the two properties _pathBuilderClass and _pathBuilderOptions. Set whatever you need here. If you inherit FileStorage\Model\Entity\FileStorage, these options and the code below are already present:

namespace App\Model\Entity;

use PhpCollective\Infrastructure\Storage\PathBuilder\PathBuilderTrait;

class SomeEntityInYourApp extends Entity
{
    use PathBuilderTrait;

    /**
     * Path builder class.
     *
     * Named $_pathBuilderClass because $_pathBuilder is already used by the
     * trait to store the path builder instance.
     *
     * @var string|null
     */
    protected $_pathBuilderClass = null;

    /**
     * Path builder options.
     *
     * @var array
     */
    protected $_pathBuilderOptions = [];

    public function __construct(array $properties = [], array $options = [])
    {
        $options += [
            'pathBuilder' => $this->_pathBuilderClass,
            'pathBuilderOptions' => $this->_pathBuilderOptions,
        ];

        parent::__construct($properties, $options);

        if ($options['pathBuilder']) {
            $this->pathBuilder(
                $options['pathBuilder'],
                $options['pathBuilderOptions'],
            );
        }
    }
}

If you want to choose the path builder depending on the kind of file or the identifier stored in the model field of the file_storage table, you can implement that logic here as well, using the entity's data to determine the path builder class or options.

Using the storage helper

The storage helper is essentially a proxy to a path builder. It takes two configuration options:

• pathBuilder — name of the path builder to use.
• pathBuilderOptions — the options passed to the path builder's constructor.

WARNING

Make sure the options you pass and the path builder are the same you used when you uploaded the file. Otherwise you end up with a different path.

// Load the helper
$this->loadHelper('FileStorage.Storage', [
    'pathBuilder' => 'Base',
    // The builder options must match those used to store the file!
    'pathBuilderOptions' => [
        'modelFolder' => true,
    ],
]);

// Use it in your views
$url = $this->Storage->url($yourEntity);

// Change the path builder at run time
// Careful: this changes the path builder instance in the helper!
$this->Storage->pathBuilder('SomePathBuilder', ['options' => 'here']);