GitHub Downloads (all assets, all releases) GitHub Issues GitHub Release License

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 **

_{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)._}

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](../../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](https://wpackagist.org): 1. Open your terminal. 2. Navigate to the root directory of your WordPress installation. 3. Ensure your `composer.json` file has the following configuration: * ```json { "require": { "composer/installers": "^1.0 || ^2.0", "wpackagist-plugin/acf-uppy": "^2.1" }, "extra": { "installer-paths": { "wp-content/plugins/{$name}/": [ "type:wordpress-plugin" ] } } } ``` 4. Run the following command: ```sh 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: 1. Open your terminal. 2. Navigate to the root directory of your WordPress installation. 3. Ensure your `composer.json` file has the following configuration: * ```json { "require": { "composer/installers": "^1.0 || ^2.0", "frugan-dev/acf-uppy": "^2.1" }, "repositories": [ { "type": "package", "package": { "name": "frugan-dev/acf-uppy", "version": "2.1.0", "type": "wordpress-plugin", "dist": { "url": "https://github.com/frugan-dev/acf-uppy/releases/download/v2.1.0/acf-uppy.zip", "type": "zip" } } } ], "extra": { "installer-paths": { "wp-content/plugins/{$name}/": [ "type:wordpress-plugin" ] } } } ``` 4. Run the following command: ```sh composer update ``` _{_Note:_
_* `composer/installers` might already be required by another dependency._}

Configuration

Once installed:

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

Actions

acf_uppy/download_fallback

```php do_action( 'acf_uppy/download_fallback', $postId ); ``` - `$postId` _(int)_: The ID of the post containing _ACF Uppy Field_.

acf_uppy/download_fallback/type={$postType}

```php 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

```php 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}

```php 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

```php 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

```php 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

```php 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

```php apply_filters( 'acf_uppy/base_path', $basePath ); ``` - `$basePath` _(string)_: The base url endpoint. Default: `acf-uppy`.

acf_uppy/api_path

```php apply_filters( 'acf_uppy/api_path', $apiPath ); ``` - `$apiPath` _(string)_: The TUS base url endpoint. Default: `wp-tus`.

acf_uppy/cache

```php apply_filters( 'acf_uppy/cache', $cacheType ); ``` - `$cacheType` _(string)_: The TUS cache type. Options: `redis`, `apcu` or `file`. Default: `apcu`.

acf_uppy/cache_ttl

```php apply_filters( 'acf_uppy/cache_ttl', $cacheTtl ); ``` - `$cacheTtl` _(string)_: The TUS cache TTL in secs. Default: `86400`.

acf_uppy/file_name_exists

```php 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](https://www.php.net/manual/en/function.pathinfo.php) of the file. - `$counter` _(int)_: The incremented counter.

acf_uppy/file_name

```php 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

```php 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}

```php 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

```php 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}

```php 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

```php 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

```php 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

```php 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:

Sponsor

License

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

frugan-dev / acf-uppy

readme