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 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 ACF Uppy Field, 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 acf_uppy/cache filter, although file is not recommended in production (see here).</sub>

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

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/acf-uppy": "^2.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/acf-uppy": "^2.0"
    },
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "frugan-dev/acf-uppy",
                "version": "2.0.0",
                "type": "wordpress-plugin",
                "dist": {
                    "url": "https://github.com/frugan-dev/acf-uppy/releases/download/v2.0.0/acf-uppy.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.

Actions

acf_uppy/download_fallback

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

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

acf_uppy/download_fallback/type={$postType}

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

acf_uppy/dest_path

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

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

acf_uppy/dest_path/type={$postType}

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.

acf_uppy/tmp_path

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()}.

acf_uppy/symlink_url

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

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

acf_uppy/symlink_path

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

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

acf_uppy/base_path

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

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

acf_uppy/api_path

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

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

acf_uppy/cache

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

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

acf_uppy/cache_ttl

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

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

acf_uppy/file_name_exists

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.

acf_uppy/file_name

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

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

acf_uppy/download_hash

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.

acf_uppy/download_hash/type={$postType}

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.

acf_uppy/download_allow

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.

acf_uppy/download_allow/type={$postType}

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.

acf_uppy/download_symlink_delete_days

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

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

acf_uppy/download_symlink_delete_max

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

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

acf_uppy/custom_post_types

apply_filters( 'acf_uppy/custom_post_types', $postTypes );

• $postTypes (array): The types of the post containing ACF Uppy Field.
  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.