- How does this package differ from Laravel’s built-in `insert`/`update` methods for bulk operations?
- This package preserves Eloquent’s event system (e.g., `creating`, `updated`) during bulk operations, unlike raw `insert`/`update`, which bypasses them. It also handles field alignment automatically and returns inserted rows, making it ideal for workflows relying on observers or callbacks.
- Can I use this with Laravel’s SoftDeletes trait for bulk operations?
- Yes, the package natively supports SoftDeletes. When performing bulk upserts, soft-deleted records will be handled according to Laravel’s default behavior unless explicitly configured otherwise.
- What Laravel versions are officially supported?
- The package requires Laravel 8.0+ and PHP 8.0+. It’s tested against MySQL 5.7+, PostgreSQL 9.6+, and SQLite 3.32+. Always check the [GitHub releases](https://github.com/lapaliv/laravel-bulk-upsert/releases) for version-specific notes.
- How do I handle third-party models (e.g., from spatie/laravel-permission) that don’t support the `Bulkable` trait?
- You’ll need to extend or wrap those models to include the `Bulkable` trait. For tightly coupled packages, consider creating a custom adapter or proxy model that inherits from the package’s base functionality.
- Does this package support transactions for atomic bulk operations?
- No, it doesn’t include built-in transaction support. You must manually wrap bulk operations in a `DB::transaction()` block to ensure atomicity across batches. Example: `DB::transaction(fn() => $models->bulkUpsert());`
- How does chunking work, and how do I optimize it for large datasets?
- The package uses Laravel’s `chunk()` method under the hood. For large datasets (e.g., 1M+ rows), adjust the chunk size (e.g., `->chunk(500)`) to balance memory usage and performance. Monitor memory consumption with `memory_get_usage()`.
- Will existing Eloquent observers/listeners work with the new `*Many` events (e.g., `creatingMany`)?
- Yes, but you’ll need to update them to handle bulk-specific logic. The `*Many` events fire *after* individual model events, so observers should account for both. Test edge cases like partial failures or concurrent operations.
- Can I use this for bulk deletes or restores with SoftDeletes?
- Yes, the package supports bulk deletes (`deleteMany`) and restores (`restoreMany`), including soft deletes. It triggers `deletingMany`/`deletedMany` events, mirroring Eloquent’s single-model behavior for consistency.
- How do I handle unique constraints or foreign key violations during bulk upserts?
- The package respects database constraints. For unique violations, it rolls back the current chunk and continues with the next. Foreign key errors will halt the operation unless wrapped in a transaction with error handling (e.g., `try-catch`).
- Are there alternatives for bulk upserts in Laravel that don’t require the `Bulkable` trait?
- Yes, alternatives include raw `DB::statement()` for custom SQL, or packages like `spatie/laravel-query-builder` for dynamic queries. However, none replicate Eloquent’s event system or field alignment out of the box. This package strikes a balance between performance and Laravel conventions.