{"id":22153659,"url":"https://github.com/frugan-dev/upload-field-with-uppy-for-acf","last_synced_at":"2025-07-26T06:32:26.834Z","repository":{"id":55377132,"uuid":"326491536","full_name":"frugan-dev/upload-field-with-uppy-for-acf","owner":"frugan-dev","description":"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","archived":false,"fork":false,"pushed_at":"2024-10-30T11:48:40.000Z","size":3270,"stargazers_count":5,"open_issues_count":4,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-30T12:32:34.078Z","etag":null,"topics":["acf","acf-addon","acf-field","php","scf","tus","tus-protocol","uppy","wordpress","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frugan-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["frugan-dev"],"buy_me_a_coffee":"frugan"}},"created_at":"2021-01-03T20:08:26.000Z","updated_at":"2024-10-30T11:48:44.000Z","dependencies_parsed_at":"2022-08-14T22:50:53.823Z","dependency_job_id":"958e8fee-caef-4f67-940e-a383cccf95df","html_url":"https://github.com/frugan-dev/upload-field-with-uppy-for-acf","commit_stats":null,"previous_names":["frugan-dev/acf-uppy","frugan-dev/upload-field-with-uppy-for-acf"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frugan-dev%2Fupload-field-with-uppy-for-acf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frugan-dev%2Fupload-field-with-uppy-for-acf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frugan-dev%2Fupload-field-with-uppy-for-acf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frugan-dev%2Fupload-field-with-uppy-for-acf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frugan-dev","download_url":"https://codeload.github.com/frugan-dev/upload-field-with-uppy-for-acf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227657195,"owners_count":17799911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acf","acf-addon","acf-field","php","scf","tus","tus-protocol","uppy","wordpress","wordpress-plugin"],"created_at":"2024-12-02T01:35:46.949Z","updated_at":"2024-12-02T01:35:47.865Z","avatar_url":"https://github.com/frugan-dev.png","language":"PHP","funding_links":["https://github.com/sponsors/frugan-dev","https://buymeacoffee.com/frugan"],"categories":[],"sub_categories":[],"readme":"![](.wordpress-org/banner-1544x500.jpg)\n\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/frugan-dev/upload-field-with-uppy-for-acf/total)\n![GitHub Actions Workflow Status](https://github.com/frugan-dev/upload-field-with-uppy-for-acf/actions/workflows/main.yml/badge.svg)\n![GitHub Issues](https://img.shields.io/github/issues/frugan-dev/upload-field-with-uppy-for-acf)\n![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)\n![GitHub Release](https://img.shields.io/github/v/release/frugan-dev/upload-field-with-uppy-for-acf)\n![License](https://img.shields.io/github/license/frugan-dev/upload-field-with-uppy-for-acf)\n\u003c!--\n![PHP Version](https://img.shields.io/packagist/php-v/frugan-dev/upload-field-with-uppy-for-acf)\n![Coverage Status](https://img.shields.io/codecov/c/github/frugan-dev/upload-field-with-uppy-for-acf)\n![Code Climate](https://img.shields.io/codeclimate/maintainability/frugan-dev/upload-field-with-uppy-for-acf)\n--\u003e\n\n# Upload Field with Uppy for ACF (WordPress Plugin)\n\n__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](https://www.advancedcustomfields.com) plugin. This custom field allows you to __upload files of all types and sizes__ using the [TUS protocol](https://tus.io) and the [Uppy JS uploader](https://uppy.io), 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`.\n\n![](docs/asset/demo.gif)\n\n## Requirements\n\n- PHP ^8.0 *\n- WordPress ^5.7 || ^6.0\n- [Advanced Custom Fields](https://www.advancedcustomfields.com) ^5.9 || ^6.0\n- APCu **\n\n\u003csub\u003e\u003ci\u003e\n_Note:_  \n_* If you need to support older versions of PHP use [v1.x](../../tree/support/v1.x)._  \n_** 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](https://github.com/ankitpokhrel/tus-php/issues/408#issuecomment-1250229371))._\n\u003c/i\u003e\u003c/sub\u003e\n\n## Features\n\n- no limits by default for upload file size and types\n- support setting per-field size limit, mime-types and upload path\n- support uploads outside public directory (for private files)\n- download file using symlinks (no memory problems with large downloads)\n- many WP hooks available\n- use [TUS protocol](https://tus.io)\n- use [Uppy JS uploader](https://uppy.io)\n- use official [ACF Example Field Type](https://github.com/AdvancedCustomFields/acf-example-field-type)\n- support for logging with [Wonolog](https://github.com/inpsyde/Wonolog) ^2.x, if available\n- made with [Vanilla JS](http://vanilla-js.com) (no jQuery)\n- autoload classes with Composer and PSR-4\n- assets built with Webpack\n- support ACF nested repeater\n- translations managed via [Crowdin](https://crowdin.com/project/upload-field-with-uppy-for-acf)\n\n## Installation\n\nYou can install the plugin in three ways: manually, via Composer (wpackagist) _(coming soon)_ or via Composer (package).\n\n\u003cdetails\u003e\n\u003csummary\u003eManual Installation\u003c/summary\u003e\n\n1. Go to the [Releases](../../releases) section of this repository.\n2. Download the latest release zip file.\n3. Log in to your WordPress admin dashboard.\n4. Navigate to `Plugins` \u003e `Add New`.\n5. Click `Upload Plugin`.\n6. Choose the downloaded zip file and click `Install Now`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstallation via Composer \"wpackagist\" (coming soon)\u003c/summary\u003e\n\nIf you use Composer to manage WordPress plugins, you can install it from [WordPress Packagist](https://wpackagist.org):\n\n1. Open your terminal.\n2. Navigate to the root directory of your WordPress installation.\n3. Ensure your `composer.json` file has the following configuration: *\n\n```json\n{\n    \"require\": {\n        \"composer/installers\": \"^1.0 || ^2.0\",\n        \"wpackagist-plugin/upload-field-with-uppy-for-acf\": \"^3.0\"\n    },\n    \"extra\": {\n        \"installer-paths\": {\n            \"wp-content/plugins/{$name}/\": [\n               \"type:wordpress-plugin\"\n            ]\n        }\n    }\n}\n```\n4. Run the following command:\n\n```sh\ncomposer update\n```\n\n\u003csub\u003e\u003ci\u003e\n_Note:_  \n_* `composer/installers` might already be required by another dependency._\n\u003c/i\u003e\u003c/sub\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstallation via Composer \"package\"\u003c/summary\u003e\n\nIf you use Composer to manage WordPress plugins, you can install it from this repository directly:\n\n1. Open your terminal.\n2. Navigate to the root directory of your WordPress installation.\n3. Ensure your `composer.json` file has the following configuration: *\n\n```json\n{\n    \"require\": {\n        \"composer/installers\": \"^1.0 || ^2.0\",\n        \"frugan-dev/upload-field-with-uppy-for-acf\": \"^3.0\"\n    },\n    \"repositories\": [\n        {\n            \"type\": \"package\",\n            \"package\": {\n                \"name\": \"frugan-dev/upload-field-with-uppy-for-acf\",\n                \"version\": \"3.0.0\",\n                \"type\": \"wordpress-plugin\",\n                \"dist\": {\n                    \"url\": \"https://github.com/frugan-dev/upload-field-with-uppy-for-acf/releases/download/v3.0.0/upload-field-with-uppy-for-acf.zip\",\n                    \"type\": \"zip\"\n                }\n            }\n        }\n    ],\n    \"extra\": {\n        \"installer-paths\": {\n            \"wp-content/plugins/{$name}/\": [\n               \"type:wordpress-plugin\"\n            ]\n        }\n    }\n}\n```\n4. Run the following command:\n\n```sh\ncomposer update\n```\n\n\u003csub\u003e\u003ci\u003e\n_Note:_  \n_* `composer/installers` might already be required by another dependency._\n\u003c/i\u003e\u003c/sub\u003e\n\u003c/details\u003e\n\n## Configuration\n\nOnce installed:\n\n1. In your WordPress admin dashboard, navigate to the `Plugins` section and click `Activate Plugin`.\n2. Create a new field via ACF and select the `Uppy` type.\n3. Read the description above for advanced usage instructions.\n\n### Enabling Cache Busting\n\nIf you use filename-based cache busting, the plugin supports the following definition in `wp-config.php`:\n\n```php\ndefine('FRUGAN_UFWUFACF_CACHE_BUSTING_ENABLED', true);\n```\n\nFor more information, see filename-based cache busting on [Nginx](https://github.com/h5bp/server-configs-nginx/blob/main/h5bp/location/web_performance_filename-based_cache_busting.conf) and [Apache](https://github.com/h5bp/server-configs-apache/blob/main/h5bp/web_performance/filename-based_cache_busting.conf).\n\n## Actions\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_fallback\u003c/summary\u003e\n\n```php\ndo_action(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_fallback', $postId);\n```\n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_fallback/type={$postType}\u003c/summary\u003e\n\n```php\ndo_action(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_fallback/type={$postType}', $postId);\n```\n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n- `$postType` _(string)_: The type of the post containing _Upload Field with Uppy for ACF_.\n\n\u003c/details\u003e\n\n## Filters\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/dest_path\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/dest_path', $dest_path);\n```\n- `$dest_path` _(string)_: The file destination absolute base path.  \nDefault: `{ABSPATH}wp-content/uploads/uppy`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/dest_path/type={$postType}\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/dest_path/type={$postType}', $dest_path, $postId, $field);\n```\n- `$dest_path` _(string)_: The file destination absolute base path.  \nDefault: `{ABSPATH}wp-content/uploads/uppy`.\n- `$postType` _(string)_: The type of the post containing _Upload Field with Uppy for ACF_.\n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n- `$field` _(array)_: The field array holding all the field options.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/tmp_path\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/tmp_path', $tmp_path);\n```\n- `$tmp_path` _(string)_: The file temporary absolute path.  \nDefault: `{sys_get_temp_dir()}/upload-field-with-uppy-for-acf/{get_current_user_id()}`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/symlink_url\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/symlink_url', $symlink_url);\n```\n- `$symlink_url` _(string)_: The symlinks absolute base url.  \nDefault: `{site_url()}/wp-content/plugins/upload-field-with-uppy-for-acf/symlink`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/symlink_path\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/symlink_path', $symlink_path);\n```\n- `$symlink_path` _(string)_: The symlinks absolute base path.  \nDefault: `{ABSPATH}wp-content/plugins/upload-field-with-uppy-for-acf/symlink`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/base_path\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/base_path', $basePath);\n```\n- `$basePath` _(string)_: The base url endpoint.  \nDefault: `uppy`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/api_path\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/api_path', $apiPath);\n```\n- `$apiPath` _(string)_: The TUS base url endpoint.  \nDefault: `wp-tus`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/cache\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/cache', $cacheType);\n```\n- `$cacheType` _(string)_: The TUS cache type.  \nOptions: `redis`, `apcu` or `file`.  \nDefault: `apcu`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/cache_ttl\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/cache_ttl', $cache_ttl);\n```\n- `$cache_ttl` _(string)_: The TUS cache TTL in secs.  \nDefault: `86400`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/file_name_exists\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/file_name_exists', $fileName, $dest_path, $pathinfo, $counter);\n```\n- `$fileName` _(string)_: The file name renamed.  \nDefault: `{$pathinfo['filename']}-{$counter}.{$pathinfo['extension']}`.\n- `$dest_path` _(string)_: The directory absolute path to the file. \n- `$pathinfo` _(array)_: The [pathinfo](https://www.php.net/manual/en/function.pathinfo.php) of the file. \n- `$counter` _(int)_: The incremented counter. \n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/file_name\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/file_name', $fileName, $dest_path);\n```\n- `$fileName` _(string)_: The file name. \n- `$dest_path` _(string)_: The directory absolute path to the file. \n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_hash\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_hash', $hash, $destFile, $postId);\n```\n- `$hash` _(int|string)_: The hash used in download url.  \nDefault: `wp_hash( $destFile )`.\n- `$destFile` _(string)_: The absolute path of the file. \n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_hash/type={$postType}\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_hash/type={$postType}', $hash, $destFile, $postId);\n```\n- `$hash` _(string)_: The hash used in download url.  \nDefault: `wp_hash( $destFile )`.\n- `$postType` _(string)_: The type of the post containing _Upload Field with Uppy for ACF_.\n- `$destFile` _(string)_: The absolute path of the file. \n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_allow\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_allow', $allow, $destFile, $postId);\n```\n- `$allow` _(bool)_: Whether or not to allow the file download. \n- `$destFile` _(string)_: The absolute path of the file. \n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_allow/type={$postType}\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_allow/type={$postType}', $allow, $destFile, $postId);\n```\n- `$allow` _(bool)_: Whether or not to allow the file download. \n- `$postType` _(string)_: The type of the post containing _Upload Field with Uppy for ACF_.\n- `$destFile` _(string)_: The absolute path of the file. \n- `$postId` _(int)_: The ID of the post containing _Upload Field with Uppy for ACF_.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_symlink_delete_days\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_symlink_delete_days', $days);\n```\n- `$days` _(int)_: Number of days before old symlinks are deleted.  \nDefault: `1`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/download_symlink_delete_max\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/download_symlink_delete_max', $max);\n```\n- `$max` _(int)_: How many old symlinks need to be deleted on each request.  \nDefault: `10`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eupload_field_with_uppy_for_acf/custom_post_types\u003c/summary\u003e\n\n```php\napply_filters(FRUGAN_UFWUFACF_NAME_UNDERSCORE.'/custom_post_types', $postTypes);\n```\n- `$postTypes` _(array)_: The types of the post containing _Upload Field with Uppy for ACF_.  \nDefault: `[]`.\n\n\u003c/details\u003e\n\n## More info\n\nSee [LINKS](docs/LINKS.md) file.\n\n## Changelog\n\nSee auto-[CHANGELOG](CHANGELOG.md) file.\n\n## Contributing\n\nFor your contributions please use:\n\n- [git-flow workflow](https://danielkummer.github.io/git-flow-cheatsheet/)\n- [conventional commits](https://www.conventionalcommits.org)\n\n## Sponsor\n\n[\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" width=\"200\" alt=\"Buy Me A Coffee\"\u003e](https://buymeacoff.ee/frugan)\n\n## License\n\n(ɔ) Copyleft 2024 [Frugan](https://frugan.it).  \n[GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/), see [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrugan-dev%2Fupload-field-with-uppy-for-acf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrugan-dev%2Fupload-field-with-uppy-for-acf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrugan-dev%2Fupload-field-with-uppy-for-acf/lists"}