Nova Field Cloudinary Laravel Package

Getting Started

Treat silvanite/nova-field-cloudinary as a tactical Nova field set, not a media platform. It is a thin integration around Cloudinary’s upload widget and a Flysystem adapter: you replace selected Nova Image/File fields with Cloudinary-backed fields, store a public ID or URL on the model, and let Cloudinary handle upload, transformations, and CDN delivery. The day-to-day value is fast back-office media administration; the cost is adopting an old, low-adoption dependency that you must read, pin, and likely fork if you are on modern Nova.

Minimal path:

1. Compatibility gate first. The last release was 2019-11-19. Inspect the package composer.json for PHP/Laravel/Nova constraints before installing. If you are on Nova 4/5, run a throwaway spike on a branch; if the field component or field lifecycle APIs break, plan to fork the base field class rather than fight it in place. Pin an exact version in composer.json and commit the lockfile.
2. Install and configure. Install with Composer, publish the package config using its service provider, and set Cloudinary credentials in .env — typically cloud name, API key, API secret, and optionally upload preset/folder. Keep secrets out of Nova field definitions and JavaScript. Run php artisan config:clear after changing env values.
3. Use one low-risk resource first. Add a string column for the Cloudinary public ID (or URL, depending on package config), then replace a single Nova image field with the package field. Verify the exact namespace and field class names in vendor/silvanite/nova-field-cloudinary/src/Fields rather than assuming.
4. First use case: a single image on a low-risk model in a staging Cloudinary cloud. Upload through Nova, confirm the value written to the database, confirm index/detail previews, replace the image, clear the field, and delete the record using a disposable asset. Check the Cloudinary dashboard after each action.
5. Where to look first: the README, config/cloudinary.php, src/Fields/*, the service provider, and the Flysystem adapter. The field options and deletion behavior are defined there; do not rely on the README alone for an old package.

Implementation Patterns

• Replace per resource, not globally. Start with one model and one asset type. Use the package’s image field for images, and the file/audio/video fields only after image upload, preview, replace, and delete are proven. Keep the rest of Nova on standard fields until the pattern is stable.
• Decide public ID vs URL deliberately. Prefer storing the Cloudinary public ID if you need transformations, folders, or versioning; generate delivery URLs at render time through the package adapter or your Cloudinary SDK. If the package stores a URL, confirm that in the database after the first upload and avoid building transformation logic that assumes a public ID.
• Model ownership explicitly. The package field should own only assets it uploaded. Shared, evergreen, or cross-record assets should live in a plain public-ID column with lifecycle managed by a job or observer, not by the Nova field. The v1.3.0 deletion fix makes this distinction important: clearing a field can destroy the remote asset.
• Centralize transformations, presets, and folders. Use Cloudinary named transformations and upload presets instead of hardcoding transformation strings per field. Set folders per model or tenant where supported. This keeps URL generation and asset organization consistent as resources grow.
• Use Nova lifecycle intentionally. Add help text and validation where the field allows it. If editors should not delete assets casually, add a confirmation pattern through a custom field extension or a separate “replace only” workflow. Use onlyOnForms/hideFromIndex for expensive media where thumbnails are not needed.
• Guard destructive operations. Before enabling the field on production data, log public IDs in model observers and document when remote deletion is allowed. Test field clear, model delete, bulk delete, and cascading delete separately. Soft-deleting a model does not protect the remote Cloudinary asset if the field clear already destroyed it.
• Backfill carefully. Add the new column, map existing URLs to public IDs or re-upload assets, and keep the legacy column until preview and delivery parity are verified. Nova-only workflows make this simpler, but do not drop the old data until rollback is no longer needed.
• Test against a staging cloud. Use disposable assets for every upload, preview, replace, clear, and delete test. Add application tests for URL/accessor generation and mock Cloudinary API calls for deletion paths. Do not point tests at production assets.
• Fork or extend for modern Nova. Keep a fork small: extend or copy the field class, preserve the component contract, and override only the behavior you need — transformation defaults, folder selection, delete confirmation, or compatibility shims. Treat the Flysystem adapter and config as extension points, but avoid mixing Cloudinary and local/S3 storage on the same model.

Gotchas and Tips

• The v1.3.0 delete fix is a breaking behavioral change. Audio and File fields now actually delete remote Cloudinary assets. Previously “deleted” assets may still exist remotely. Audit existing records before upgrading, and update deletion policy, admin guidance, and tests. Accidental deletion is not undone by a Nova or Eloquent soft delete.
• Package age is the dominant risk. Last release 2019, low adoption, no listed dependents. Nova upgrades, PHP upgrades, and Cloudinary SDK changes are effectively your maintenance problem. Pin the version, nominate an owner, and budget for a fork or internal replacement if the admin media path is critical.
• Config cache causes “missing credentials” bugs. After php artisan config:cache, env changes may not be picked up. Clear and rebuild config in deploy, and verify the exact env variable names the package reads.
• Smaller thumbnails are intentional. v1.3.0 reduced Nova thumbnail size for performance. Do not treat smaller previews as a regression. For video and heavy media, index views can still be slow; avoid unnecessary media fields on index and use poster/thumbnail transformations where supported.
• Upload widget issues are usually CSP, CORS, or presets. Check browser network logs, allowed upload domains, and whether you are using unsigned presets. Never expose the API secret in frontend code. Restrict upload presets by format, size, and folder.
• Video/raw/audio support is improved but less common. Do not assume image transformations apply to raw files. Test delivery and transformation paths per resource type, and watch Cloudinary quota and transformation costs for video.
• Multi-tenant isolation is limited. The package likely assumes one Cloudinary cloud and credential set. Folder-based separation is not tenant isolation. If you need private assets, signed delivery, or per-tenant credentials, verify support or fork before committing.
• Do not mix storage backends on one model. Local/S3 and Cloudinary deletion semantics diverge, and orphaned assets become invisible. Keep Cloudinary-owned media on Cloudinary-backed fields and lifecycle-managed shared assets in separate columns.
• Debug from the asset outward. Check the database value, the Cloudinary dashboard, browser upload requests, storage/logs/laravel.log, and the resolved config. If the field renders but upload fails, it is usually credentials, preset, or widget configuration; if delete fails, check public ID format, permissions, and whether the asset still exists.
• Plan rollback before rollout. Remote deletion has no native undo. Confirm Cloudinary backup/retention behavior, test restore with a disposable asset, and document the manual recovery process. If that process is unacceptable, extend the field to require confirmation or disable field-level deletion entirely.