PHPackages backstage/uploadcare-field - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. backstage/uploadcare-field ActiveLibrary[Utility & Helpers](/categories/utility) backstage/uploadcare-field ========================== Uploadcare Field component for the Backstage CMS. v5.0.5(3mo ago)3434[3 PRs](https://github.com/backstagephp/uploadcare-field/pulls)MITPHPPHP ^8.3CI passing Since Jan 17Pushed 1mo ago2 watchersCompare [ Source](https://github.com/backstagephp/uploadcare-field)[ Packagist](https://packagist.org/packages/backstage/uploadcare-field)[ Docs](https://github.com/backstagephp/uploadcare-field)[ GitHub Sponsors](https://github.com/vormkracht10)[ RSS](/packages/backstage-uploadcare-field/feed)WikiDiscussions main Synced 1w ago READMEChangelog (5)Dependencies (55)Versions (366)Used By (0) Uploadcare Field component for the Backstage CMS. ================================================= [](#uploadcare-field-component-for-the-backstage-cms) [![Latest Version on Packagist](https://camo.githubusercontent.com/841d932bfa5b9e0e1214f27112edd99e0056298284190699d1ca894c373b0e10/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6261636b73746167652f75706c6f6164636172652d6669656c642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/backstage/uploadcare-field)[![GitHub Tests Action Status](https://camo.githubusercontent.com/5f19067522d9ce5a634044878bec8d247ad40e6936a8e7b2d7b604ab5d03d5c1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6261636b73746167652f75706c6f6164636172652d6669656c642f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/backstagephp/uploadcare-field/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/d26e7328d1534eefb913a5b8ce5bcd3f400691d6d3c47a517fe3e3e339d89219/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6261636b73746167652f75706c6f6164636172652d6669656c642f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/backstagephp/uploadcare-field/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/60dae4cc177dd777ea927a05bf2eb7e475b4dbce1254b19ac849edb734e2a8f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6261636b73746167652f75706c6f6164636172652d6669656c642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/backstage/uploadcare-field) Nice to meet you, we're [Vormkracht10](https://vormkracht10.nl) --------------------------------------------------------------- [](#nice-to-meet-you-were-vormkracht10) Hi! We are a web development agency from Nijmegen in the Netherlands and we use Laravel for everything: advanced websites with a lot of bells and whitles and large web applications. About this package ------------------ [](#about-this-package) This package adds an Uploadcare field to the Backstage CMS. Uploadcare is a powerful file handling platform that provides file uploads, storage, transformations and delivery. With this package, you can easily integrate Uploadcare's functionality into your Backstage CMS forms. The field supports: - Single and multiple file uploads - Image previews - File size limits - Allowed file types - Direct CDN delivery - Image transformations - Secure file storage Once installed, you can use the Uploadcare field in your Backstage forms just like any other field type, while leveraging Uploadcare's robust file handling capabilities. ### Other custom fields [](#other-custom-fields) For a list of other custom fields, please see the [Backstage CMS documentation](https://github.com/vormkracht10/backstage/blob/main/docs/04-plugins/01-introduction.md). Installation ------------ [](#installation) You can install the package via composer: ``` composer require backstage/uploadcare-field ``` Then you need to add the Uploadcare public key to your services.php config file: ``` return [ 'uploadcare' => [ 'public_key' => env('UPLOADCARE_PUBLIC_KEY') ] ]; ``` Then you need to add the Uploadcare field to your `backstage/fields.php` config file: ``` return [ // ... 'custom_fields' => [ Backstage\UploadcareField\Uploadcare::class, ], ]; ``` ### CSS and Styling [](#css-and-styling) This package includes a MediaGridPicker component that requires Tailwind CSS classes to be properly compiled. The package automatically registers its CSS assets with Filament, but you may need to ensure your main application's Tailwind build includes the package's source files. If you're using Tailwind CSS v4 in your main application, add the package's source directories to your `resources/css/sources.css` file: ``` @source "/path/to/backstage-uploadcare-field/resources/"; @source "/path/to/backstage-uploadcare-field/src/"; ``` For Tailwind CSS v3, add the package paths to your `tailwind.config.js`: ``` module.exports = { content: [ // ... your existing paths './vendor/backstage/uploadcare-field/resources/**/*.blade.php', './vendor/backstage/uploadcare-field/src/**/*.php', ], // ... rest of your config } ``` The package's CSS is automatically loaded in Filament admin panels and includes all necessary styles for the MediaGridPicker component. ### MediaGridPicker Integration [](#mediagridpicker-integration) The package includes a MediaGridPicker component that allows users to select existing media files from the media library and add them directly to Uploadcare fields. This feature is automatically available when using uploadcare fields in Filament forms. **How it works:** 1. When editing content with uploadcare fields, a "Select from Media" button appears next to the field 2. Clicking this button opens a modal with a grid of existing media files 3. Selecting a media file automatically adds it to the Uploadcare field 4. The integration uses Alpine.js events and JavaScript to communicate between the MediaGridPicker and Uploadcare components **Technical details:** - The MediaGridPicker dispatches an `add-uploadcare-file` event when a file is selected - The package's JavaScript listens for this event and attempts to add the file to the Uploadcare field - Multiple fallback methods are used to ensure compatibility with different Uploadcare configurations: 1. **Direct Uploadcare API**: Tries to use the Uploadcare widget's API to add files 2. **Livewire State Management**: Updates the Livewire component state directly 3. **Hidden Input Fields**: Sets values on hidden input fields and triggers events 4. **File Object Creation**: Attempts to create File objects from CDN URLs 5. **Generic Input Fields**: Falls back to setting values on any matching input fields **Debugging:** - The JavaScript includes comprehensive console logging to help debug integration issues - Check the browser console for detailed information about which methods are being attempted - The system will log which Uploadcare elements are found and which methods succeed or fail Automatic Migration ------------------- [](#automatic-migration) This package includes an automatic migration that fixes double-encoded JSON data in Uploadcare fields. This migration runs automatically when the package is installed or updated. ### What the migration does: [](#what-the-migration-does) - **Fixes double-encoded JSON**: Removes unnecessary JSON encoding layers that were created in earlier versions - **Updates both tables**: Processes both `content_field_values` and `settings` tables - **Safe execution**: Only runs if the relevant tables exist - **Logging**: Logs all changes for transparency and debugging The migration will run automatically when you: - Install the package for the first time - Update the package via Composer - Run `composer update` or `composer install` ⚠️ **Important**: This migration is not reversible. Always make a database backup before updating the package. Usage ----- [](#usage) After adding the Uploadcare field to your `backstage/fields.php` config file, the field will automatically be available in the Backstage CMS. ### Field Configuration [](#field-configuration) The Uploadcare field supports several configuration options: - **Multiple**: Allow multiple file uploads - **With metadata**: Store full file metadata (recommended for cropping support) - **Images only**: Restrict uploads to image files only - **Uploader style**: Choose between Inline, Minimal, or Regular uploader styles ### Image Cropping and Transformations [](#image-cropping-and-transformations) The Uploadcare field stores comprehensive metadata about uploaded images, including cropping information. This allows you to access both the original and cropped versions of images in your front-end. #### Understanding the Data Structure [](#understanding-the-data-structure) When an image is uploaded and cropped, the field stores data in this format: ``` { "uuid": "12345678-1234-1234-1234-123456789abc", "cdnUrl": "https://ucarecdn.com/12345678-1234-1234-1234-123456789abc/-/crop/912x442/815,0/-/preview/", "cdnUrlModifiers": "-/crop/912x442/815,0/-/preview/", "fileInfo": { "uuid": "12345678-1234-1234-1234-123456789abc", "cdnUrl": "https://ucarecdn.com/12345678-1234-1234-1234-123456789abc/", "imageInfo": { "width": 1783, "height": 442, "format": "JPEG" } } } ``` #### Cropping Parameters Explained [](#cropping-parameters-explained) The cropping is defined by URL parameters: - `-/crop/912x442/815,0/`: - `912x442` = target width and height - `815,0` = x,y coordinates where cropping starts - `-/preview/` = preview mode #### Front-end Usage [](#front-end-usage) ##### 1. Direct URL Access [](#1-direct-url-access) ``` // Access the cropped version $croppedUrl = $image['cdnUrl']; // Contains crop parameters // Access the original version $originalUrl = $image['fileInfo']['cdnUrl']; // No crop parameters ``` ##### 2. Using Uploadcare Transformations [](#2-using-uploadcare-transformations) If you have the `backstage/php-uploadcare-transformations` package installed: ``` // Basic resize $resizedImage = uc($image['uuid'])->resize(width: 800); // Smart crop with AI $smartCropped = uc($image['uuid'])->smartCrop(width: 400, height: 300, type: 'smart_objects'); // Manual crop $manualCrop = uc($image['uuid'])->crop(width: 400, height: 300, x: 100, y: 50); ``` ##### 3. In Blade Templates [](#3-in-blade-templates) ``` {{-- Use the pre-cropped version --}} {{-- Use the original version --}} {{-- Apply new transformations --}} ``` #### Best Practices [](#best-practices) 1. **Enable metadata storage**: Set `withMetadata: true` in your field configuration to ensure cropping information is preserved. 2. **Use appropriate versions**: - Use `cdnUrl` for pre-cropped images - Use `fileInfo.cdnUrl` for original images - Apply new transformations as needed 3. **Performance considerations**: - Pre-cropped images load faster than on-the-fly transformations - Use appropriate image sizes for your use case - Consider using WebP format for better compression 4. **Responsive images**: Use different crop sizes for different screen sizes: ``` // Mobile $mobileImage = uc($image['uuid'])->resize(width: 400); // Desktop $desktopImage = uc($image['uuid'])->resize(width: 1200); ``` Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Baspa](https://github.com/vormkracht10) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 50 — FairBetter than 95% of packages Maintenance85 Actively maintained with recent releases Popularity16 Limited adoption so far Community13 Small or concentrated contributor base Maturity74 Established project with proven stability Bus Factor1 Top contributor holds 75% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 264 Last Release 102d ago Major Versions v1.1.54 → v2.0.0-beta232026-01-21 2.x-dev → v4.0.12026-03-13 v2.0.22 → v4.0.02026-03-13 v2.0.26 → v4.0.32026-04-11 v4.1.1 → 5.x-dev2026-05-08 PHP version history (2 changes)v0.1.0PHP ^8.2 v1.1.1PHP ^8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/7c6a425dc8645907a118a007438172d58c2016773f54ab3a834beff172632f13?d=identicon)[ux](/maintainers/ux) --- Top Contributors [![Baspa](https://avatars.githubusercontent.com/u/10845460?v=4)](https://github.com/Baspa "Baspa (39 commits)")[![Casmo](https://avatars.githubusercontent.com/u/385764?v=4)](https://github.com/Casmo "Casmo (7 commits)")[![mhortulanus](https://avatars.githubusercontent.com/u/91618246?v=4)](https://github.com/mhortulanus "mhortulanus (4 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags backstagefieldfilamentuploadcarelaravelvormkracht10backstage-uploadcare-field ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/backstage-uploadcare-field/health.svg) ``` [![Health](https://phpackages.com/badges/backstage-uploadcare-field/health.svg)](https://phpackages.com/packages/backstage-uploadcare-field) ``` ### Alternatives [codewithdennis/filament-select-tree The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths. 329575.9k35](/packages/codewithdennis-filament-select-tree)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3915.5k](/packages/rawilk-profile-filament-plugin) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)