@Api\Upload

Control where files are uploaded to in your TYPO3 RestAPi

With the @Api\Upload(...) annotation you can control, where the file uploads of a multipart/form-data request are moved to.

The syntax is:

@Api\Upload( option )

Where option can have one of the following expressions to either define a direct file path, a custom Class to return the upload-path or the key to a configuration in the TypoScript setup:

Important

Note that @Api\Upload(...) must explicitly be set as an Annotation on the endpoint - otherwise the nnrestapi will ignore any file upload passed during the request. This is to prevent uncontrolled uploads and misuse of the Api.

The Annotation is placed in the comment block above your method / endpoint:

<?php

namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Upload("default")
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction()
   {
      $result = $this->someComplicatedOperation();
      return $result;
   }

}

Let’s have a look at the configuration in TypoScript setup for plugin.tx_nnrestapi.settings.fileUploads:

plugin.tx_nnrestapi.settings.fileUploads {

   # Use this key in your endpoint annotation "@api\upload default"
   default {

      // if nothing else fits, use fileadmin/api/
      defaultStoragePath = 1:/api/

      // Optional: Use a custom class to return configuration
      //pathFinderClass = Nng\Nnrestapi\Helper\UploadPathHelper::getUserUidPath

      // target-path for file, file-0, file-1, ...
      file = 1:/api/tests/
   }
}

Make sure the upload-folder exists and has the correct rights for reading/writing.

Custom method for resolving the upload path

You can define a custom class that resolves the upload-path for each individual file. This can either be done by …

• Setting the class name in the Annotation itself like this:

  // will call \My\Extname\UploadProcessor->getUploadPath()
  @Api\Upload( \My\Extname\UploadProcessor::class )
  

  In this case, the nnrestapi will automatically try to call the method getUploadPath() of your class and will expect an array as return value. Refer to the examples below to see, which values need to be returned in the array.

• Creating a configuration in the TypoScript setup at plugin.tx_nnrestapi.settings.fileUploads.[name].pathFinderClass. In this case, you can also set the method name to call:

  plugin.tx_nnrestapi.settings.fileUploads {
     myconf {
        pathFinderClass = My\Extension\Helper\UploadPathHelper::getPathForDate
     }
  }
  

  Then use the configuration name in your Annotations like this:

  @Api\Upload("config[myconf]")
  

Tip

Have a look at the Nng\Nnrestapi\Helper\UploadPathHelper for detailled examples.

Example of custom path resolvers

Let’s create an UploadPathHelper that uploads the files to a folder-structure depending on the current month and date. You probably have seen this structure in WordPress.

The Helper will return a configuration array which has the same keys and structure that the TypoScript setup uses. You can keep things simple and just return the key defaultStoragePath which will upload all fileUploads to the same location, independent of their fileKey/name in the POST-data:

return ['defaultStoragePath'=>'1:/my/custom/path']

And/or you can return a path for the individual fileKeys:

return ['file'=>'1:/files/', 'image-0':'1:/images/', ...];

Here is a full example for a UploadPathHelper that returns a combined identifier folder name in the style of 1:/api/YYYY-MM

<?php

namespace My\Extension\Helper;

class UploadPathHelper
{
   /**
    * Return upload-path based on current date (e.g. `1:/api/2021-12/`)
    *
    * @return array
    */
   public static function getPathForDate( $request = null, $settings = null )
   {
      return [
         'defaultStoragePath' => '1:/api/' . date('Y-m') . '/'
      ];
   }

}

Next, create a TypoScript setting that points to your helper-method:

plugin.tx_nnrestapi.settings.fileUploads {
   monthdate {
      pathFinderClass = My\Extension\Helper\UploadPathHelper::getPathForDate
   }
}

Last step: Use the key monthdate in the @Api\Upload("monthdate") annotation of your endpoint:

<?php

namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Upload("config[monthdate]")
    * @Api\Access("public")
    *
    * @param \My\Extension\Domain\Model\ApiTest $apiTest
    * @return array
    */
   public function getAllAction( $apiTest = null )
   {
      return $apiTest;
   }

}

Check out the File uploads(…) section of this documentation for more information and examples.