Laravel Import Export Laravel Package

Getting Started

• Install via Composer and publish any package assets (config, migrations, stubs) as instructed by the README:

  composer require umutcangungormus/laravel-import-export
  php artisan vendor:publish --provider="UmutCanGungormus\ImportExport\ImportExportServiceProvider"
  

• Look first at:
  • README.md for quick-start examples and supported formats.
  • The package service provider for bindings, commands, and extension points.
  • config/import-export.php (or similarly named config) for disk, queue, chunk size, model mappings, and tenant-scoping defaults.
  • The tests/ directory (if shipped) for canonical usage.
• First use case: export a simple Eloquent query to CSV, then import a CSV into a model with validation. Example workflow:
  1. Define an export class or call the package’s export facade/helper with a query and column map.
  2. Store the file on a configured disk (local or S3).
  3. Define an import class with validation rules and model mapping.
  4. Run the import synchronously for small files, or queue it for larger files.
• v1.0.0 is the first stable release. The changelog calls out a fix for “tenant scoped default,” so verify how tenant scoping is configured before relying on default behavior in multi-tenant apps.

Implementation Patterns

• Use dedicated import/export classes rather than ad-hoc controller logic. Keep column mapping, validation, and persistence in one place so scheduled jobs, commands, and UI actions share the same behavior.
• Queue long-running imports/exports. Wrap them in Laravel jobs (ShouldQueue) and store files on a disk. Use chunked reads/writes (cursor(), chunk(), or package-specific chunk settings) to avoid memory exhaustion.
• Set tenant context explicitly. In multi-tenant applications, establish the tenant before invoking import/export. The v1.0.0 tenant-scoped default fix means you should confirm whether the package now applies global scopes by default; if not, apply tenant constraints to the query or model resolver yourself.
• Validate imports before writing. Use Laravel validation rules or the package’s row-level validation hooks. Collect row errors and fail the job or return a report rather than partially importing silently.
• Wrap imports in transactions when appropriate. For all-or-nothing imports, use DB::transaction(). For large imports, prefer per-chunk transactions with idempotent upserts.
• Integrate with artisan commands and scheduler. Expose common exports as commands (e.g., nightly CSV exports) and schedule them. This is often more reliable than UI-only exports.
• Use events/observers for side effects. If the package emits import/export events, hook into them for audit logs, notifications, or cache invalidation instead of modifying package code.
• Test with small fixtures. Create representative CSV/XLSX fixtures and assert both success and validation-failure paths. Include a multi-tenant fixture if you use tenant scoping.

Gotchas and Tips

• Tenant-scoping behavior changed in v1.0.0. The release fixes “tenant scoped default.” If you are upgrading from v0.1.0, review the linked PR and test imports/exports under different tenant contexts. Defaults that previously ignored tenant scopes may now apply them, or vice versa.
• Config caching. After changing package config, run php artisan config:cache in deployed environments. Stale config is a common cause of “why is it using the wrong disk/queue/chunk size?”
• Queue workers need restarts after deploys. If imports/exports are queued, restart workers so they pick up new code and config.
• Memory and time limits. Large files can exhaust memory even with chunking if you hydrate full models. Prefer cursor(), lazy(), or package-provided streaming readers. Set job timeouts appropriately.
• Disk permissions and paths. Verify the configured disk is writable by the web server and queue workers. Use absolute paths or Laravel’s Storage facade consistently.
• Global scopes and withoutGlobalScopes. If exports unexpectedly include or exclude tenant data, check global scopes on the model and whether the package’s query builder applies them. Be explicit in your export query.
• Debugging tips. Log the resolved config (Log::debug(config('import-export'))), inspect the generated SQL with DB::listen(), and test the same import/export through both HTTP and CLI to catch environment differences.
• Extension points to prefer. Custom readers/writers, column formatters, model resolvers, validation rule sets, and events are safer than forking. Check the service provider for bindings you can override in a service provider.
• Version pinning. Since v1.0.0 is the first stable release, pin to ^1.0 and review changelogs for minor releases that may alter tenant-scoping defaults or queue behavior.