Import Export Laravel Package

Getting Started

• Install with composer require vrok/import-export. There is no service provider requirement documented for most helper packages of this shape — check vendor/vrok/import-export/composer.json for extra.laravel.providers and for a publishable config before assuming zero setup.
• Read the source first. With 0 stars and 0 dependents, the test suite (if present) and src/ are the real documentation. Budget 20–30 minutes to skim the entry points — you are looking for the export/import facade or service, the JSON shape it emits, and how it resolves relations.
• First use case: a read-only reference-data snapshot. Export a small aggregate (e.g. Category → children → translations) to a file, commit it, and restore it in a test. This exercises the round-trip with zero production blast radius.
• Verify the round-trip end-to-end before anything else: export → delete the rows → import → assertDatabaseHas on the root and at least one nested relation. If the shape doesn't survive that, stop there.

Implementation Patterns

• Wrap the package, don't call it directly. Put it behind your own SnapshotService or an Artisan command (snapshot:export, snapshot:import). Given the package's maturity signals, you want a single seam to patch or replace if an edge case bites you.
• Treat the JSON as a versioned DTO. Add a format_version key to anything you persist and write a small upgrader. The emitter's shape is not a stable contract at 0.x.
• Test fixtures are the highest-value pattern: capture a realistic production-like graph once, anonymize it, and load it in feature tests instead of hand-writing dozens of factories. Keep the fixtures small — one aggregate, not a whole schema.
• Environment promotion (dev → staging content) works well for content-ish tables: taxonomies, CMS pages, email templates. Not for user data or anything with PII.
• Transaction + idempotency. Wrap imports in DB::transaction(). Define a natural key (slug, code, external_id) and use updateOrCreate semantics so re-running an import is safe. Prefer this over preserving source IDs.
• Queue large imports. Dispatch a job, write progress to the cache or a snapshots table, and surface it in the UI. Do not import a multi-megabyte graph inside a request.
• Validate before writing. Run Validator against the decoded array against a schema (or a hand-rolled assertShape()) before touching the database. A malformed JSON should fail loudly at step zero, not halfway through the graph.

Gotchas and Tips

• Primary key strategy is the whole ballgame. Decide up front: preserve source IDs (fast, but collides with existing rows and breaks auto-increment sequences) or remap via natural keys (safer, more code). Most failures of this package class come from this decision being made implicitly.
• Model events fire on import. Observers, search indexing, and notification listeners will all trigger. Wrap imports in a flag (Model::withoutEvents() or a static $importing guard) and re-index in a single pass afterward.
• Fillable/guarded. Importers typically use fill() or forceFill(). Know which — with fill() any column not in $fillable silently disappears from the round-trip, and you'll only notice months later.
• Casts and enums. JSON-encoded columns, dates, and enum casts often come back as strings. Assert on types in your round-trip test, not just values.
• Circular and deep relations. A bidirectional relation graph can blow the recursion limit or exhaust memory. Find the relation-depth config or export-scope mechanism before exporting anything with back-references, and chunk by root model for large sets.
• Polymorphic relations and pivot tables are the usual unsupported edge — verify explicitly, or export those separately.
• Timestamps and soft deletes. Decide whether created_at/deleted_at are preserved or reset. A snapshot restore that resurrects soft-deleted rows is a common surprise.
• Debugging: keep the emitted JSON in storage/app/ and diff two exports when an import misbehaves. Log unrecognized keys during import rather than ignoring them, so schema drift is visible.
• Pin the version exactly ("vrok/import-export": "0.x.y") and lock it in composer.lock. With no dependents, you have no community signal that a patch release is safe.
• Extension points to look for: per-model custom serializers/casters, pre/post import hooks, and the config file's key-resolution and depth settings. If none of these exist, that's your signal to keep the integration surface small enough to fork.