Upload Field with Uppy for ACF (WordPress Plugin)

Upload Field with Uppy for ACF is a WordPress plugin that adds a new Uppy custom field to the list of fields of the Advanced Custom Fields plugin. This custom field allows you to upload files of all types and sizes using the TUS protocol and the Uppy JS uploader, overcoming the limitations of the default ACF File field. With Upload Field with Uppy for ACF, you no longer need to increase server-side INI parameters such as upload_max_filesize, post_max_size, max_execution_time and memory_limit.

Requirements

• PHP ^8.0 *
• WordPress ^5.7 || ^6.0
• Advanced Custom Fields ^5.9 || ^6.0
• APCu **

<sub>Note:
* If you need to support older versions of PHP use v1.x.
** If your environment doesn't support APCu, you can try setting the cache to file with the upload_field_with_uppy_for_acf/cache filter, although file is not recommended in production (see here).</sub>

Features

• 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
• use TUS protocol
• use Uppy JS uploader
• use official ACF Example Field Type
• support for logging with Wonolog ^2.x, if available
• made with Vanilla JS (no jQuery)
• autoload classes with Composer and PSR-4
• assets built with Webpack
• support ACF nested repeater
• translations managed via Crowdin

Installation

You can install the plugin in three ways: manually, via Composer (wpackagist) (coming soon) or via Composer (package).

Manual Installation

1. Go to the Releases section of this repository.
2. Download the latest release zip file.
3. Log in to your WordPress admin dashboard.
4. Navigate to Plugins > Add New.
5. Click Upload Plugin.
6. Choose the downloaded zip file and click Install Now.

Installation via Composer "wpackagist" (coming soon)

If you use Composer to manage WordPress plugins, you can install it from WordPress Packagist:

1. Open your terminal.
2. Navigate to the root directory of your WordPress installation.
3. Ensure your composer.json file has the following configuration: *

{
    "require": {
        "composer/installers": "^1.0 || ^2.0",
        "wpackagist-plugin/upload-field-with-uppy-for-acf": "^3.0"
    },
    "extra": {
        "installer-paths": {
            "wp-content/plugins/{$name}/": [
               "type:wordpress-plugin"
            ]
        }
    }
}

4. Run the following command:

composer update

<sub>Note:
* composer/installers might already be required by another dependency.</sub>

Installation via Composer "package"

If you use Composer to manage WordPress plugins, you can install it from this repository directly:

1. Open your terminal.
2. Navigate to the root directory of your WordPress installation.
3. Ensure your composer.json file has the following configuration: *

{
    "require": {
        "composer/installers": "^1.0 || ^2.0",
        "frugan-dev/upload-field-with-uppy-for-acf": "^3.0"
    },
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "frugan-dev/upload-field-with-uppy-for-acf",
                "version": "3.0.0",
                "type": "wordpress-plugin",
                "dist": {
                    "url": "https://github.com/frugan-dev/upload-field-with-uppy-for-acf/releases/download/v3.0.0/upload-field-with-uppy-for-acf.zip",
                    "type": "zip"
                }
            }
        }
    ],
    "extra": {
        "installer-paths": {
            "wp-content/plugins/{$name}/": [
               "type:wordpress-plugin"
            ]
        }
    }
}

4. Run the following command:

composer update

<sub>Note:
* composer/installers might already be required by another dependency.</sub>

Configuration

Once installed:

1. In your WordPress admin dashboard, navigate to the Plugins section and click Activate Plugin.
2. Create a new field via ACF and select the Uppy type.
3. Read the description above for advanced usage instructions.

Enabling Cache Busting

If you use filename-based cache busting, the plugin supports the following definition in wp-config.php:

define('FRUGAN_UFWUFACF_CACHE_BUSTING_ENABLED', true);

For more information, see filename-based cache busting on Nginx and Apache.

Actions

upload_field_with_uppy_for_acf/download_fallback

do_action(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_fallback', $postId);

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

upload_field_with_uppy_for_acf/download_fallback/type={$postType}

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

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

Filters

upload_field_with_uppy_for_acf/dest_path

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/dest_path', $dest_path);

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

upload_field_with_uppy_for_acf/dest_path/type={$postType}

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

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

upload_field_with_uppy_for_acf/tmp_path

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/tmp_path', $tmp_path);

• $tmp_path (string): The file temporary absolute path.
  Default: {sys_get_temp_dir()}/upload-field-with-uppy-for-acf/{get_current_user_id()}.

upload_field_with_uppy_for_acf/symlink_url

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/symlink_url', $symlink_url);

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

upload_field_with_uppy_for_acf/symlink_path

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/symlink_path', $symlink_path);

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

upload_field_with_uppy_for_acf/base_path

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/base_path', $basePath);

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

upload_field_with_uppy_for_acf/api_path

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/api_path', $apiPath);

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

upload_field_with_uppy_for_acf/cache

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/cache', $cacheType);

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

upload_field_with_uppy_for_acf/cache_ttl

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/cache_ttl', $cache_ttl);

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

upload_field_with_uppy_for_acf/file_name_exists

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/file_name_exists', $fileName, $dest_path, $pathinfo, $counter);

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

upload_field_with_uppy_for_acf/file_name

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/file_name', $fileName, $dest_path);

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

upload_field_with_uppy_for_acf/download_hash

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/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 Upload Field with Uppy for ACF.

upload_field_with_uppy_for_acf/download_hash/type={$postType}

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/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 Upload Field with Uppy for ACF.
• $destFile (string): The absolute path of the file.
• $postId (int): The ID of the post containing Upload Field with Uppy for ACF.

upload_field_with_uppy_for_acf/download_allow

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/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 Upload Field with Uppy for ACF.

upload_field_with_uppy_for_acf/download_allow/type={$postType}

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/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 Upload Field with Uppy for ACF.
• $destFile (string): The absolute path of the file.
• $postId (int): The ID of the post containing Upload Field with Uppy for ACF.

upload_field_with_uppy_for_acf/download_symlink_delete_days

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_symlink_delete_days', $days);

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

upload_field_with_uppy_for_acf/download_symlink_delete_max

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_symlink_delete_max', $max);

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

upload_field_with_uppy_for_acf/custom_post_types

apply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/custom_post_types', $postTypes);

• $postTypes (array): The types of the post containing Upload Field with Uppy for ACF.
  Default: [].

More info

See LINKS file.

Changelog

See auto-CHANGELOG file.

Contributing

For your contributions please use:

• git-flow workflow
• conventional commits

Sponsor

License

(ɔ) Copyleft 2024 Frugan.
GNU GPLv3, see LICENSE file.