Laravel Digital Business Cards Laravel Package

Getting Started

The package builds on Filament: a business card is a standard Eloquent model edited through a Filament resource, with a shared form schema driving both the create and edit screens. Install and wire it up the same way as any Filament plugin:

1. composer require the package and run php artisan vendor:publish --tag="<package>-migrations" (plus the config tag if you need to change defaults), then php artisan migrate.
2. Register the plugin/provider in your panel (->plugin(BusinessCardPlugin::make())) or, if it ships a resource only, point your panel at BusinessCardResource.
3. Open the resource in the panel — /admin/business-cards/create — and confirm the form renders before touching any config.

Look first at the resource's form() definition and the CreateBusinessCard / EditBusinessCard page classes: in v1.4.0 these are unified, so the field list lives in one place and both pages consume it. That single schema is the extension point you'll spend most of your time in.

The first use case to exercise is the new preview: fill in the form (name, title, company, avatar, links), click Preview, and verify the modal renders the card from live form state without a record being written. That confirms two things at once — your form schema is valid and your card Blade partial renders outside the persisted-model path.

Implementation Patterns

Shared schema, two pages. Because create and edit now share a layout, put your custom fields in the package's schema class/method (or a BusinessCardForm you own) rather than duplicating them per page. Any field you add automatically appears in both screens and in the preview modal — that's the whole payoff of the unified layout.

Preview from live state. The modal is populated from the Filament form's current state (roughly $this->form->getState() inside a ->modalContent() closure), not from a saved model. Build your card Blade partial so it accepts a plain array:

->modalContent(fn () => view('business-cards.preview', [
    'card' => $this->form->getState(),
]))

Rendering that same partial from your public card route keeps preview and reality honest — if they diverge, users lose trust in the preview.

Make state live. For the preview to feel responsive, mark the fields that matter with ->live() (or ->live(onBlur: true) for text inputs and rich editors) so the modal reflects edits. Reserve onBlur for anything expensive; plain live() on a debounced text field is usually fine.

Two-step workflow. A common day-to-day pattern: draft with the preview modal open, iterate on copy/avatar, then save once. Encourage this in your UI by placing the preview action next to the submit button rather than in the page header.

Integration tips. If you generate public slugs, use the same value the preview shows as a hint ("this card will live at /c/acme-jane"), and derive it from the same state array. If cards are tenant-scoped, ensure the resource query and the preview both respect the current tenant — the preview should never reveal another tenant's data.

Gotchas and Tips

• Uploads are not URLs yet. Unsaved file uploads come back as temporary upload objects. The preview must handle TemporaryUploadedFile (e.g. ->temporaryUrl()); anything that calls a persisted media conversion or Storage::url() on a non-existent path will 404 or throw.
• No model means no accessors, casts, or observers. Anything your production card gets from the model — computed display names, slug generation, Spatie Media Library conversions, morph relations — is absent in preview. Format/prepare the state explicitly before handing it to the view, and keep that preparation in one place used by both paths.
• getState() is dehydrated state, not your model. Repeaters arrive as arrays, rich text as raw HTML (sanitize it), dates as strings. Treat the preview input as untrusted.
• Modal reactivity. modalContent() is evaluated when the modal opens; if ->live() isn't set on the fields you care about, edits made while the modal is open won't refresh. Debug by dumping the state inside the closure.
• Live validation noise. With ->live() on many fields, users see validation errors mid-typing. Debounce, or restrict live to display fields and leave validation on submit.
• Version drift. Filament v3 and v4 differ in form/schema namespaces and action APIs. Pin your Filament constraint to whatever the package's composer.json declares and re-check the preview action after any minor Filament bump.
• Authorization. The preview action lives on the create page, which generally has no policy subject. Don't let a preview action become a back door to rendering stored data for records the user can't view — pass only unsaved state.
• Performance. A large live form re-renders the whole card on each keystroke. If your card partial is heavy (image processing, remote fetches), cache or defer it.