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
.
- PHP ^8.0 *
- WordPress ^5.7 || ^6.0
- Advanced Custom Fields ^5.9 || ^6.0
- APCu **
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).
- 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
You can install the plugin in three ways: manually, via Composer (wpackagist) (coming soon) or via Composer (package).
Manual Installation
- Go to the Releases section of this repository.
- Download the latest release zip file.
- Log in to your WordPress admin dashboard.
- Navigate to
Plugins
>Add New
. - Click
Upload Plugin
. - 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:
- Open your terminal.
- Navigate to the root directory of your WordPress installation.
- 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"
]
}
}
}
- Run the following command:
composer update
Note:
* composer/installers
might already be required by another dependency.
Installation via Composer (package)
If you use Composer to manage WordPress plugins, you can install it from this repository directly:
- Open your terminal.
- Navigate to the root directory of your WordPress installation.
- 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"
]
}
}
}
- Run the following command:
composer update
Note:
* composer/installers
might already be required by another dependency.
Once installed:
- In your WordPress admin dashboard, navigate to the
Plugins
section and clickActivate Plugin
. - Create a new field via ACF and select the
Uppy
type. - Read the description above for advanced usage instructions.
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.
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
orfile
.
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:[]
.
See LINKS file.
See auto-CHANGELOG file.
For your contributions please use: