ACF Uppy Field (WordPress Plugin)

ACF Uppy Field is a WordPress plugin that adds a new "Uppy" custom field to the list of fields of the Advanced Custom Fields plugin.
This "Uppy" custom field allows you to overcome the limits of the default "File" field present in ACF, and to upload files of all types and sizes via the TUS protocol and the Uppy JS uploader, regardless of the limits set on the server side (there is no need to increase INI parameters like upload_max_filesize, post_max_size, max_execution_time, memory_limit, etc.).

Requirements

• PHP v7.x
• WordPress v5.x
• Advanced Custom Fields v5.x

Recommendations

• Composer

Features

• use official Advanced Custom Fields - Field Type Template
• use TUS protocol
• use Uppy JS uploader
• made with Vanilla JS (no jQuery)
• autoload classes with Composer and PSR-4
• assets built with Webpack
• support ACF nested repeater
• no limits by default for upload file size and types
• support setting per-field size limit, mime-types and upload path
• support uploads outside public directory (for private files)
• download file using symlinks (no memory problems with large downloads)
• many WP hooks available

Installation

1. Copy the acf-uppy folder into your wp-content/plugins or wp-content/mu-plugins folder.

2. Run this command inside the acf-uppy folder:

   $ composer install

   Alternatively, if you don't have shell access to your hosting space, read here.

3. Activate the Advanced Custom Fields: Uppy plugin via the plugins admin page.

4. Create a new field via ACF and select the Uppy type.

5. Read the description above for advanced usage instructions.

Actions

do_action( 'acf_uppy/download_fallback', $postId );

• $postId (int): The ID of the post containing ACF Uppy Field.

do_action( 'acf_uppy/download_fallback/type={$postType}', $postId );

• $postId (int): The ID of the post containing ACF Uppy Field.
• $postType (string): The type of the post containing ACF Uppy Field.

Filters

apply_filters( 'acf_uppy/dest_path', $destPath );

• $destPath (string): The file destination absolute base path.
  Default: {ABSPATH}wp-content/uploads/acf-uppy.

apply_filters( 'acf_uppy/dest_path/type={$postType}', $destPath, $postId, $field );

• $destPath (string): The file destination absolute base path.
  Default: {ABSPATH}wp-content/uploads/acf-uppy.
• $postType (string): The type of the post containing ACF Uppy Field.
• $postId (int): The ID of the post containing ACF Uppy Field.
• $field (array): The field array holding all the field options.

apply_filters( 'acf_uppy/tmp_path', $tmpPath );

• $tmpPath (string): The file temporary absolute path.
  Default: {sys_get_temp_dir()}/acf-uppy/{get_current_user_id()}.

apply_filters( 'acf_uppy/symlink_url', $symlinkUrl );

• $symlinkUrl (string): The symlinks absolute base url.
  Default: {site_url()}/wp-content/plugins/acf-uppy/symlink.

apply_filters( 'acf_uppy/symlink_path', $symlinkPath );

• $symlinkPath (string): The symlinks absolute base path.
  Default: {ABSPATH}wp-content/plugins/acf-uppy/symlink.

apply_filters( 'acf_uppy/base_path', $basePath );

• $basePath (string): The base url endpoint.
  Default: acf-uppy.

apply_filters( 'acf_uppy/api_path', $apiPath );

• $apiPath (string): The TUS base url endpoint.
  Default: wp-tus.

apply_filters( 'acf_uppy/cache', $cacheType );

• $cacheType (string): The TUS cache type.
  Options: redis, apcu or file.
  Default: file.

apply_filters( 'acf_uppy/cache_ttl', $cacheTtl );

• $cacheTtl (string): The TUS cache TTL in secs.
  Default: 86400.

apply_filters( 'acf_uppy/file_name_exists', $fileName, $destPath, $pathinfo, $counter );

• $fileName (string): The file name renamed.
  Default: {$pathinfo['filename']}-{$counter}.{$pathinfo['extension']}.
• $destPath (string): The directory absolute path to the file.
• $pathinfo (array): The pathinfo of the file.
• $counter (int): The incremented counter.

apply_filters( 'acf_uppy/file_name', $fileName, $destPath );

• $fileName (string): The file name.
• $destPath (string): The directory absolute path to the file.

apply_filters( 'acf_uppy/download_hash', $hash, $destFile, $postId );

• $hash (int|string): The hash used in download url.
  Default: wp_hash( $destFile ).
• $destFile (string): The absolute path of the file.
• $postId (int): The ID of the post containing ACF Uppy Field.

apply_filters( 'acf_uppy/download_hash/type={$postType}', $hash, $destFile, $postId );

• $hash (string): The hash used in download url.
  Default: wp_hash( $destFile ).
• $postType (string): The type of the post containing ACF Uppy Field.
• $destFile (string): The absolute path of the file.
• $postId (int): The ID of the post containing ACF Uppy Field.

apply_filters( 'acf_uppy/download_allow', $allow, $destFile, $postId );

• $allow (bool): Whether or not to allow the file download.
• $destFile (string): The absolute path of the file.
• $postId (int): The ID of the post containing ACF Uppy Field.

apply_filters( 'acf_uppy/download_allow/type={$postType}', $allow, $destFile, $postId );

• $allow (bool): Whether or not to allow the file download.
• $postType (string): The type of the post containing ACF Uppy Field.
• $destFile (string): The absolute path of the file.
• $postId (int): The ID of the post containing ACF Uppy Field.

apply_filters( 'acf_uppy/download_symlink_delete_days', $days );

• $days (int): Number of days before old symlinks are deleted.
  Default: 1.

apply_filters( 'acf_uppy/download_symlink_delete_max', $max );

• $max (int): How many old symlinks need to be deleted on each request.
  Default: 10.

Webpack tasks

• Build sources:

  $ npm run develop

• Start file watcher for recompiling:

  $ npm run watch

• Build sources for production:

  $ npm run production

Changelog

See auto-CHANGELOG file.

Roadmap

1. Add support for Uppy fields associated with WP users.
2. Test PHP 8.x.

Do you need other features? Send me a new enhancement!

Contributing

For your contributions please use the git-flow workflow.

Support

Usefull links

• https://www.advancedcustomfields.com/resources/creating-a-new-field-type/
• https://github.com/AdvancedCustomFields/acf-field-type-template
• http://youmightnotneedjquery.com
• http://vanilla-js.com/
• https://vanillajstoolkit.com
• https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/
• https://dmitripavlutin.com/string-interpolation-in-javascript/
• https://github.com/ankitpokhrel/tus-php/wiki/WordPress-Integration
• transloadit/uppy#179
• https://dev.to/konsole/resumable-file-upload-in-php-handle-large-file-uploads-in-an-elegant-way-4a84
• https://dev.to/oyetoket/fastest-way-to-generate-random-strings-in-javascript-2k5a
• https://mortoray.com/2014/04/09/allowing-unlimited-access-with-cors/
• https://www.html5rocks.com/en/tutorials/cors//
• https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials#What_went_wrong
• https://choosealicense.com
• https://learnwithdaniel.com/2019/09/publishing-your-first-wordpress-plugin-with-git-and-svn/

License

(ɔ) Copyleft 2021 Frugan GNU GPLv3, see COPYING file.