Filament Uploadcare Field Laravel Package

Getting Started

Use this package when you want Filament form uploads to go directly to Uploadcare while Laravel stores only a reference. Treat it as a Filament form-field adapter, not a complete digital asset management layer.

Minimal steps:

1. Install with Composer: composer require backstage/filament-uploadcare-field.
2. Check composer.json for the supported Filament version. This is important because Filament v3 and v4 form APIs differ.
3. Configure the Uploadcare public key in .env/config as documented. Only put the secret key server-side if you are also doing server-side Uploadcare API calls.
4. Publish config/assets/views if the README provides publish tags; run php artisan filament:assets if the package ships Filament assets.
5. Add the field to a Filament Resource form and store the returned value in a model column.

Look first at:

• README.md for install/config and exact component namespace.
• src/ for the component class and supported methods.
• The service provider for asset registration, config merging, and publish tags.
• resources/ for JS/widget initialization.
• The parent package backstage/cms for real-world usage, because this repository is a READ ONLY subtree split.

First use case: replace a normal Filament FileUpload with an Uploadcare-backed image field on a Resource form.

use Backstage\FilamentUploadcareField\Forms\Components\UploadcareFileUpload;

UploadcareFileUpload::make('cover_image')
    ->label('Cover image')
    ->required();

Add a cover_image column to the model/table, make it fillable, and render it through an accessor or CDN URL helper.

Implementation Patterns

Basic single-file field

public static function form(Schema $schema): Schema
{
    return $schema->components([
        UploadcareFileUpload::make('cover_image')
            ->label('Cover image')
            ->required()
            ->helperText('Uploaded to Uploadcare; only a reference is stored locally.'),
    ]);
}

Adjust the method signature for Filament v3 vs v4.

Normalize what you store

Confirm whether the component stores an Uploadcare UUID, a full CDN URL, or a file group. Pick one convention and stick to it. UUIDs are usually better because you can generate CDN transformations later without rewriting stored data.

// app/Models/Post.php
use Illuminate\Database\Eloquent\Casts\Attribute;

protected function coverUrl(): Attribute
{
    return Attribute::get(fn () => $this->cover_image
        ? "https://ucarecdn.com/{$this->cover_image}/"
        : null);
}

Render in tables and infolists

If you store UUIDs, build the CDN URL in an accessor or column state callback. Do not make every view know Uploadcare URL structure.

ImageColumn::make('cover_url')
    ->label('Cover')
    ->getStateUsing(fn ($record) => $record->cover_url);

Use Uploadcare transformations instead of storing variants

Store the source reference and generate display variants at render time:

$thumb = "https://ucarecdn.com/{$uuid}/-/resize/400x/";
$webp  = "https://ucarecdn.com/{$uuid}/-/format/webp/";

This keeps the database clean and lets you change image sizes later.

Multiple files

Only use ->multiple() if the component actually supports it. If it does, store a JSON array and cast it:

protected $casts = [
    'gallery' => 'array',
];

Validate that every value is a UUID or expected URL shape. Test repeaters and Builder blocks carefully because custom JS widgets often need stable wire:key values.

Validation

Use Filament validation where available, plus Uploadcare-side restrictions for accepted file types and size. Because the file may already be uploaded to Uploadcare before Laravel sees it, server-side MIME/size validation may need Uploadcare metadata rather than a normal Laravel uploaded-file rule.

UploadcareFileUpload::make('cover_image')
    ->required()
    ->rules(['string']);

Cleanup

Deleting a model record will not automatically delete the Uploadcare file. If orphan files matter, add a model observer/job that calls the Uploadcare API, or schedule periodic orphan cleanup. Otherwise document that Uploadcare remains the source of truth.

Testing

Do not drive the real Uploadcare widget in feature tests. Set model attributes directly or fake the upload response. Assert that the form exposes the field, that values are stored in the expected format, and that rendering uses the accessor/CDN URL.

Gotchas and Tips

• READ ONLY subtree split: this repository is for installation only. Issues, PRs, and real source changes belong in backstage/cms. Do not expect fixes to land here directly.
• Low adoption: 3 stars and 0 dependents means you should pin an exact version, review the source, and avoid assuming a stable public API. This is a niche integration.
• Public vs secret keys: the Uploadcare public key is browser-side. Never expose the secret key in Blade, Livewire state, or frontend config.
• CORS/domain restrictions: Uploadcare uploads happen from the browser. Configure allowed domains in the Uploadcare dashboard, or uploads may work locally and fail in production.
• Storage format ambiguity: verify whether the field returns UUID, CDN URL, or file group. Mixing formats across models creates messy accessors and broken image rendering.
• Filament version mismatch: check the package’s Filament constraint before installing. Filament v3 and v4 form APIs are not interchangeable.
• Livewire lifecycle issues: custom JS widgets can lose initialization in modals, repeaters, and Builder blocks. Use stable wire:key values and test those contexts explicitly.
• Config cache: after changing Uploadcare env values, run php artisan config:clear or php artisan optimize:clear, then re-cache if needed.
• Asset cache: if the widget does not appear, check that the package service provider is registered, assets are published/loaded, and php artisan filament:assets has been run.
• Orphaned files: deleting a record does not delete the Uploadcare asset. Decide whether that is acceptable or add cleanup logic.
• Extension points: inspect the component class for uploadcare widget options, publishable views/config, and overridable methods. If the package does not expose what you need, wrap it in your own Filament component rather than editing vendor code.