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. v4.0.1(2mo ago)3430[2 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 1mo ago READMEChangelog (5)Dependencies (33)Versions (291)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, ], ]; ``` 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 51 — FairBetter than 96% of packages Maintenance89 Actively maintained with recent releases Popularity16 Limited adoption so far Community12 Small or concentrated contributor base Maturity73 Established project with proven stability Bus Factor1 Top contributor holds 50% 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 233 Last Release 66d ago Major Versions v1.1.52 → v2.0.0-beta152026-01-12 v1.1.53 → v2.0.0-beta162026-01-13 v1.1.54 → v2.0.0-beta232026-01-21 v2.0.25 → v4.0.02026-03-13 v2.0.21 → 4.x-dev2026-03-13 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 (8 commits)")[![Casmo](https://avatars.githubusercontent.com/u/385764?v=4)](https://github.com/Casmo "Casmo (6 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 [spatie/laravel-data Create unified resources and data transfer objects 1.7k28.9M627](/packages/spatie-laravel-data)[hirethunk/verbs An event sourcing package that feels nice. 513162.9k6](/packages/hirethunk-verbs)[worksome/exchange Check Exchange Rates for any currency in Laravel. 123544.7k](/packages/worksome-exchange)[ralphjsmit/livewire-urls Get the previous and current url in Livewire. 82270.3k4](/packages/ralphjsmit-livewire-urls)[hydrat/filament-table-layout-toggle Filament plugin adding a toggle button to tables, allowing user to switch between Grid and Table layouts. 6292.3k1](/packages/hydrat-filament-table-layout-toggle)[ralphjsmit/laravel-helpers A package containing handy helpers for your Laravel-application. 13704.6k2](/packages/ralphjsmit-laravel-helpers) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)