Resource Management¶

Importing Resources¶

Importing resources is one way to create a new resource object. The ResourceManager provides a simple API method for this purpose:

Example: Importing a new resource

class ImageController {

        /**
         * @FLOW3\Inject
         * @var \TYPO3\FLOW3\Resource\ResourceManager
         */
        protected $resourceManager;

        // ... more code here ...

        /**
         * Imports an image
         *
         * @param string $imagePathAndFilename
         * @return void
         */
        public function importImageAction($imagePathAndFilename) {
                $newResource = $this->resourceManager->importResource($imagePathAndFilename);

                $newImage = new \Acme\Demo\Domain\Model\Image();
                $newImage->setOriginalResource($newResource);

                $this->imageRepository->add($newImage);
        }
}

The ImageController in our example provides a method to import a new image. Because an image consists of more than just the image file (we need a title, caption, generate a thumbnail, ...) we created a whole new model representing an image. The imported resource is considered as the “original resource” of the image and the Image model could easily provide a “thumbnail resource” for a smaller version of the original.

This is what happens in detail while executing the importImageAction method:

1. The URI (in our case an absolute path and filename) is passed to the importResource() method which analyzes the file found at that location.
2. The file is imported into FLOW3’s persistent resources storage using the sha1 hash over the file content as its filename. If a file with exactly the same content is imported it will reuse the already stored resource.
3. The Resource Manager returns a new Resource object which refers to the newly imported file.
4. A new Image object is created and the resource is attached to it.
5. The image is added to the ImageRepository. Only from now on the new image and the related resource will be persisted. If we omitted that step, the image, the resource and in the end the imported file would be discarded at the end of the script run.

In order to delete a resource just disconnect the resource object from the persisted object, for example by unsetting originalResource in the Image object.

Resource Uploads¶

The second way to create new resources is uploading them via a POST request. FLOW3’s MVC framework detects incoming file uploads and automatically converts them into Resource objects. In order to persist an uploaded resource you only need to persist the resulting object.

Consider the following Fluid template:

<f:form method="post" action="create" object="{newImage}" name="newImage"
        enctype="multipart/form-data">
        <f:form.textbox property="image.title" value="My image title" />
        <f:form.upload property="image.originalResource" />
        <f:form.submit value="Submit new image"/>
</f:form>

This form allows for submitting a new image which consists of an image title and the image resource (e.g. a JPEG file). The following controller can handle the submission of the above form:

class ImageController {

   /**
    * Creates a new image
    *
    * @param \Acme\Demo\Domain\Model\Image $newImage The new image
    * @return void
    */
   public function createAction(\Acme\Demo\Domain\Model\Image $newImage) {
      $this->imageRepository->add($newImage);
      $this->forward('index');
   }
}

Provided that the Image class has a $title and a $originalResource property and that they are accessible through setTitle() and setOriginalResource() respectively the above code will work just as expected.

Static Resources¶

Static resources (provided by packages) are published to the web directory on the first script run and whenever packages are activated or deactivated.

Published static resources can be used in Fluid templates via the built-in resource view helper:

<img src="{f:uri.resource(path: 'Images/Icons/FooIcon.png', package: 'Acme.Demo')}" />

Note that the package parameter is optional and defaults to the package containing the currently active controller.

Persistent Resources¶

Persistent resources are published on demand because FLOW3 cannot know which resources are meant to be public and which ones need to be kept private. The trigger for publishing persistent resources is the generation of its public web URI. A very common way to do that is displaying a resource in a Fluid template:

The resource view helper (f:uri.resource ) will ask the ResourcePublisher for the web URI of the resource stored in image.originalResource. The publisher checks if the given resource has already been published and if not publishes it right away.

A published persistent resource is accessible through a web URI like http://example.local/_Resources/Persistent/107bed85ba5e9bae0edbae879bbc2c26d72033ab.jpg. One advantage of using the sha1 hash of the resource content as a filename is that once the resource changes it gets a new filename and is displayed correctly regardless of the cache settings in the user’s web browser. Search engines on the other hand prefer more meaningful filenames. For these cases the resource view helper allows for defining a speaking title for a resource URI:

<img src="{f:uri.resource(resource: image.originalResource, title: image.title)}" />

A URI produced by the above template would look like this: http://example.local/_Resources/Persistent/107bed85ba5e9bae0edbae879bbc2c26d72033ab/my-speaking-title.jpg

You can define as many titles for each resource as you want – the resulting file is always the same, identified by the sha1 hash.

Mirror Mode¶

Publishing resources basically means copying files from a private location to the public web directory. FLOW3 instead creates symbolic links, making the resource publishing process fast.

If your operating system does not support symbolic links, you will not be able to use FLOW3.