Add the ability to define subdirectories for file uploads (2.x)

[rhclayto]

This change makes it possible to set an option for creating a subdirectory when saving a file, & it also adds the ability to optionally place files in a dated (Y-m-d) subdirectory within your named subdirectory.

This mimics the ability to set subdirectories & dated subdirectories when cteating a file field on a content type in Drupal core. For instance, you can add a file field & in the field settings you can put something like the following in the 'File directory' field: avatars/[current-date:custom:Y]-[current-date:custom:m]-[current-date:custom:d].

If setting a dated subdirectory, the date format is configurable using any format accepted by PHP's date function: https://secure.php.net/manual/en/function.date.php .

Example annotation for file upload plug-in:

/**
 * Class FilesUpload__1_0
 * @package Drupal\restful_example\Plugin\Resource
 *
 * @Resource(
 *   name = "files_upload:1.0",
 *   resource = "files_upload",
 *   label = "File upload",
 *   description = "A file upload wrapped with RESTful.",
 *   authenticationTypes = TRUE,
 *   dataProvider = {
 *     "entityType": "file",
 *     "options": {
 *       "scheme": "public",
 *       "subdir": "avatars",
 *       "datedir": TRUE,
 *       "date_format": "Y-m-d"
 *     }
 *   },
 *   menuItem = "file-upload",
 *   majorVersion = 1,
 *   minorVersion = 0
 * )
 */