Getting Started

Minimal Setup

Install the package:
```
composer require askdkc/livewire-csv
```
Run the setup command (publishes migrations, config, and prompts for migration execution):
```
php artisan livecsv-setup
```

Add HasCsvImports trait to your target model (e.g., User.php):

use Askdkc\LivewireCsv\Concerns\HasCsvImports;

class User extends Authenticatable {
    use HasCsvImports;
}

First Use Case: Basic CSV Import

Embed the csv-importer component in a Blade view with minimal props:

<livewire:csv-importer
    :model="App\Models\User::class"
    :columns-to-map="['id', 'name', 'email']"
    :required-columns="['name', 'email']"
    :column-labels="['name' => 'Full Name', 'email' => 'Email']"
/>

Implementation Patterns

Core Workflow

Define Model Requirements:
- Map CSV columns to model fields via :columns-to-map.
- Specify required columns for validation (:required-columns).
- Use :column-labels for user-friendly field names.
Upsert Logic:
- Defaults to id for upserting. Override with :upsert-columns (requires a unique/index constraint on those columns).
- Example migration for custom upsert:
```
$table->unique(['email', 'name']); // For :upsert-columns="['email', 'name']"
```
Queue-Based Processing:
- Large files (>100MB default) are processed asynchronously via queues.
- Ensure queue workers are running:
```
php artisan queue:work
```

Integration Tips

TALL Stack Projects: Publish views and compile assets:

php artisan vendor:publish --tag="csv-views"
npm run dev

Non-TALL Projects: Include directives in <head> and <footer>:
```
@csvStyles
@csvScripts
```
Custom Delimiters: Configure in config/livewire-csv.php:
```
'set_delimiter' => ';', // For TSV files
```

Button Component

Use Alpine.js-powered buttons for imports:

<x-csv-button class="bg-blue-500 text-white px-4 py-2 rounded">
    Import CSV
</x-csv-button>

Gotchas and Tips

Pitfalls

Queue Dependencies:
- Forgetting to run php artisan queue:batches-table and php artisan migrate will break async imports.
- Fix: Run the setup command (livecsv-setup) or manually execute:
```
php artisan queue:table
php artisan queue:batches-table
php artisan migrate
```
Upsert Constraints:
- :upsert-columns requires a unique/index constraint. Missing this causes silent failures.
- Debug: Check Laravel logs for SQLSTATE[23000] errors (duplicate key violations).
File Size Limits:
- Default max upload size is 100MB (configurable in file_upload_size).
- Workaround: For larger files, use chunked processing or external storage (e.g., S3).
Delimiter Mismatches:
- Hardcoded delimiters (e.g., ,) may fail for TSV files (;).
- Solution: Set 'set_delimiter' => ';' in config and ensure files match.

Debugging

Queue Failures: Check failed_jobs table or logs for exceptions. Retry with:
```
php artisan queue:retry all
```
Validation Errors: Livewire logs validation messages to the browser console. Use :validation-errors prop to display them:
```
<livewire:csv-importer ... :validation-errors="$errors" />
```

Extension Points

Custom Validation: Override validateRow() in your model’s HasCsvImports trait:

public function validateRow(array $row): void {
    $this->validate($row, [
        'email' => 'required|email|unique:users,email,'.$this->id,
    ]);
}

Pre/Post-Import Hooks: Use model events (creating, updating) or queue listeners to extend logic.

Custom Views: Publish and override default views:

php artisan vendor:publish --tag="livewire-csv-views" --force

Performance Tips

Batch Processing: For very large datasets, implement chunked imports via chunk() in your model’s import() method.
Index Optimization: Ensure :upsert-columns are indexed to speed up lookups:
```
$table->index(['email', 'name']);
```

Livewire Csv Laravel Package