458 lines
15 KiB
Markdown
458 lines
15 KiB
Markdown
# File Upload mit Livewire Volt + Flux UI
|
||
|
||
Vollständige Referenz für den Bild-Upload, wie er in `resources/views/livewire/products/form-teaser.blade.php` implementiert ist.
|
||
|
||
---
|
||
|
||
## Überblick
|
||
|
||
Der Upload nutzt:
|
||
- **Livewire `WithFileUploads`** – verwaltet temporäre Uploads via signierter URL
|
||
- **Flux UI `flux:file-upload`** – UI-Komponente (Dropzone + Vorschau)
|
||
- **Laravel `Storage::disk('public')`** – Permanente Speicherung
|
||
- **Polymorphe `media`-Tabelle** – Zuordnung von Dateien zu beliebigen Models
|
||
- **Alpine.js** – Drag-&-Drop-Sortierung der vorhandenen Bilder
|
||
|
||
---
|
||
|
||
## 1. PHP / Livewire Volt – Komponentenlogik
|
||
|
||
### Trait einbinden
|
||
|
||
```php
|
||
use Livewire\WithFileUploads;
|
||
|
||
new class extends Component {
|
||
use WithFileUploads;
|
||
|
||
/** @var array<\Livewire\Features\SupportFileUploads\TemporaryUploadedFile> */
|
||
public array $mainImages = [];
|
||
```
|
||
|
||
`WithFileUploads` muss zwingend eingebunden sein. Ohne ihn reagiert `wire:model` nicht auf Datei-Inputs.
|
||
|
||
### Validierung
|
||
|
||
```php
|
||
'mainImages' => 'nullable|array|min:0|max:10',
|
||
'mainImages.*' => 'mimes:jpeg,jpg,png|max:10240',
|
||
```
|
||
|
||
- `mainImages` ist ein **Array** (wegen `multiple`-Upload)
|
||
- `mainImages.*` validiert jede einzelne Datei
|
||
- `max:10240` = 10 MB in Kilobyte
|
||
- Livewire hat intern ein Default-Limit von 12 MB – das greift, bevor die eigene Validierung läuft (Achtung: Wert muss ≤ 12288 KB sein oder `livewire.temporary_file_upload.rules` anpassen)
|
||
|
||
### Einzelnes Bild entfernen (Vorschauliste)
|
||
|
||
```php
|
||
public function removePhoto(int $index): void
|
||
{
|
||
if (isset($this->mainImages[$index])) {
|
||
unset($this->mainImages[$index]);
|
||
$this->mainImages = array_values($this->mainImages);
|
||
}
|
||
}
|
||
```
|
||
|
||
Nach `unset()` unbedingt `array_values()` aufrufen, damit die Array-Indizes wieder bei 0 beginnen – sonst bricht `@foreach` mit `$index` im Template.
|
||
|
||
### Vorhandenes Bild aus der DB löschen
|
||
|
||
```php
|
||
public function removeExistingMedia(int $mediaId): void
|
||
{
|
||
$media = $this->product->media()->find($mediaId);
|
||
if ($media) {
|
||
Storage::disk('public')->delete($media->file_path);
|
||
$media->delete();
|
||
$this->existingMedia = collect($this->existingMedia)
|
||
->reject(fn ($m) => $m['id'] === $mediaId)
|
||
->values()
|
||
->toArray();
|
||
}
|
||
}
|
||
```
|
||
|
||
Immer erst die **Datei** vom Disk löschen, dann den **DB-Eintrag**. Anschließend `$this->existingMedia` synchronisieren, damit Livewire den State neu rendert.
|
||
|
||
### Reihenfolge aktualisieren (Drag & Drop)
|
||
|
||
```php
|
||
public function updateMediaOrder(array $orderedIds): void
|
||
{
|
||
foreach ($orderedIds as $position => $mediaId) {
|
||
$this->product->media()
|
||
->where('id', $mediaId)
|
||
->update(['order_column' => $position + 1]);
|
||
}
|
||
|
||
// Lokalen State synchronisieren
|
||
$this->existingMedia = collect($orderedIds)
|
||
->map(fn ($id, $index) => collect($this->existingMedia)->firstWhere('id', $id)
|
||
? array_merge(collect($this->existingMedia)->firstWhere('id', $id), ['order_column' => $index + 1])
|
||
: null
|
||
)
|
||
->filter()
|
||
->values()
|
||
->toArray();
|
||
}
|
||
```
|
||
|
||
### Bilder permanent speichern (Neu-Anlage)
|
||
|
||
```php
|
||
$index = 1;
|
||
foreach ($this->mainImages as $image) {
|
||
$path = $image->store('products/' . $product->id, 'public');
|
||
$product->media()->create([
|
||
'file_path' => $path,
|
||
'type' => 'image',
|
||
'alt_text' => $this->name,
|
||
'order_column' => $index++,
|
||
]);
|
||
}
|
||
```
|
||
|
||
`$image->store(...)` verschiebt die temporäre Livewire-Datei in den endgültigen Pfad auf dem `public`-Disk.
|
||
|
||
### Bilder permanent speichern (Bearbeiten – neue Bilder hinzufügen)
|
||
|
||
```php
|
||
$maxOrder = $this->product->media()->max('order_column') ?? 0;
|
||
$index = $maxOrder + 1;
|
||
foreach ($this->mainImages as $image) {
|
||
$path = $image->store('products/' . $this->product->id, 'public');
|
||
$this->product->media()->create([
|
||
'file_path' => $path,
|
||
'type' => 'image',
|
||
'alt_text' => $this->name,
|
||
'order_column' => $index++,
|
||
]);
|
||
}
|
||
```
|
||
|
||
`order_column` an bestehenden Max-Wert anhängen, nicht von 1 neu beginnen.
|
||
|
||
### Nach dem Speichern zurücksetzen
|
||
|
||
```php
|
||
// Neue Bilder leeren
|
||
$this->mainImages = [];
|
||
|
||
// Vorhandene Bilder aus DB neu laden (mit sortBy)
|
||
$this->existingMedia = $this->product->fresh()->media
|
||
->sortBy('order_column')
|
||
->values()
|
||
->map(fn ($m) => [
|
||
'id' => $m->id,
|
||
'file_path' => $m->file_path,
|
||
'alt_text' => $m->alt_text,
|
||
'order_column' => $m->order_column,
|
||
])
|
||
->toArray();
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Blade / Flux UI – Template
|
||
|
||
### Upload-Dropzone
|
||
|
||
```blade
|
||
<flux:file-upload wire:model="mainImages" label="Upload files" multiple
|
||
accept="image/jpeg,image/png,.jpg,.jpeg,.png">
|
||
<flux:file-upload.dropzone
|
||
heading="Bilder hochladen"
|
||
text="Nur JPEG oder PNG – max. 10 MB"
|
||
with-progress />
|
||
</flux:file-upload>
|
||
```
|
||
|
||
- `wire:model="mainImages"` – bindet an das Array-Property
|
||
- `multiple` – erlaubt Mehrfachauswahl
|
||
- `accept` – schränkt den Browser-Dateidialog ein (kein serverseitiger Schutz!)
|
||
- `with-progress` – zeigt Upload-Fortschrittsbalken
|
||
|
||
### Vorschauliste der neu hinzugefügten Bilder
|
||
|
||
```blade
|
||
@if (isset($mainImages) && count($mainImages) > 0)
|
||
<div class="mt-4 flex flex-wrap items-center gap-3">
|
||
@foreach ($mainImages as $index => $image)
|
||
<flux:file-item
|
||
:heading="$image->getClientOriginalName()"
|
||
:image="(str_starts_with($image->getMimeType() ?? '', 'image/') && $image->isPreviewable())
|
||
? $image->temporaryUrl()
|
||
: null"
|
||
:size="$image->getSize()">
|
||
<x-slot name="actions">
|
||
<flux:file-item.remove
|
||
wire:click="removePhoto({{ $index }})"
|
||
aria-label="{{ 'Remove file: ' . $image->getClientOriginalName() }}" />
|
||
</x-slot>
|
||
</flux:file-item>
|
||
@endforeach
|
||
</div>
|
||
@endif
|
||
```
|
||
|
||
**Wichtig bei `temporaryUrl()`:**
|
||
Die Methode gibt nur dann eine URL zurück, wenn die Datei auch vorschaubar ist (`isPreviewable()` prüft die MIME-Type-Whitelist in `config/livewire.php`). Immer beide Bedingungen prüfen, sonst Fehler.
|
||
|
||
### Fehleranzeige
|
||
|
||
```blade
|
||
<flux:error name="mainImages" />
|
||
```
|
||
|
||
Zeigt Validierungsfehler für das gesamte Array an (z. B. „Maximal 10 Bilder erlaubt.").
|
||
Für Fehler auf einzelnen Dateien würde `name="mainImages.0"` etc. verwendet.
|
||
|
||
### Drag-&-Drop-Sortierung vorhandener Bilder
|
||
|
||
```blade
|
||
<div x-data="{
|
||
dragging: null,
|
||
dragOver: null,
|
||
items: @js(collect($existingMedia)->pluck('id')->toArray()),
|
||
onDragStart(e, id) {
|
||
this.dragging = id;
|
||
e.dataTransfer.effectAllowed = 'move';
|
||
e.dataTransfer.setData('text/plain', id);
|
||
},
|
||
onDragOver(e, id) {
|
||
e.preventDefault();
|
||
e.dataTransfer.dropEffect = 'move';
|
||
this.dragOver = id;
|
||
},
|
||
onDrop(e, targetId) {
|
||
e.preventDefault();
|
||
if (this.dragging === targetId) { this.dragOver = null; return; }
|
||
const fromIdx = this.items.indexOf(this.dragging);
|
||
const toIdx = this.items.indexOf(targetId);
|
||
this.items.splice(fromIdx, 1);
|
||
this.items.splice(toIdx, 0, this.dragging);
|
||
this.dragging = null;
|
||
this.dragOver = null;
|
||
$wire.updateMediaOrder(this.items);
|
||
},
|
||
onDragEnd() {
|
||
this.dragging = null;
|
||
this.dragOver = null;
|
||
}
|
||
}" class="flex flex-wrap items-start gap-3">
|
||
|
||
@foreach ($existingMedia as $mediaIndex => $media)
|
||
<div wire:key="existing-media-{{ $media['id'] }}"
|
||
draggable="true"
|
||
x-on:dragstart="onDragStart($event, {{ $media['id'] }})"
|
||
x-on:dragover="onDragOver($event, {{ $media['id'] }})"
|
||
x-on:drop="onDrop($event, {{ $media['id'] }})"
|
||
x-on:dragend="onDragEnd()"
|
||
:class="{
|
||
'opacity-50 scale-95': dragging === {{ $media['id'] }},
|
||
'ring-2 ring-blue-400 ring-offset-2': dragOver === {{ $media['id'] }} && dragging !== {{ $media['id'] }}
|
||
}"
|
||
class="group relative cursor-grab active:cursor-grabbing transition-all duration-150">
|
||
|
||
@if ($mediaIndex === 0)
|
||
<div class="absolute -top-1 -left-1 z-10 bg-blue-600 text-white text-[10px] font-bold px-1.5 py-0.5 rounded-md shadow">
|
||
Standard
|
||
</div>
|
||
@endif
|
||
|
||
<img src="{{ Storage::url($media['file_path']) }}"
|
||
alt="{{ $media['alt_text'] ?? '' }}"
|
||
class="h-24 w-24 rounded-lg object-cover border border-zinc-200 dark:border-zinc-700
|
||
{{ $mediaIndex === 0 ? 'ring-2 ring-blue-500' : '' }}" />
|
||
|
||
<flux:button
|
||
wire:click="removeExistingMedia({{ $media['id'] }})"
|
||
wire:confirm="Bild wirklich löschen?"
|
||
variant="filled" size="xs" icon="trash"
|
||
class="absolute -top-2 -right-2 !bg-red-500 !text-white hover:!bg-red-600" />
|
||
</div>
|
||
@endforeach
|
||
</div>
|
||
```
|
||
|
||
**Wichtig:** `wire:key="existing-media-{{ $media['id'] }}"` ist zwingend, damit Livewire beim Re-Render die DOM-Elemente korrekt zuordnet.
|
||
|
||
---
|
||
|
||
## 3. Datenbank – Media-Tabelle
|
||
|
||
```php
|
||
// Migration: database/migrations/xxxx_create_media_table.php
|
||
|
||
Schema::create('media', function (Blueprint $table) {
|
||
$table->id();
|
||
$table->string('model_type'); // z. B. "App\Models\Product"
|
||
$table->unsignedBigInteger('model_id');
|
||
$table->string('file_path'); // relativer Pfad auf dem public-Disk
|
||
$table->string('type')->default('image'); // 'image', 'video', 'pdf', '3d_model'
|
||
$table->string('alt_text')->nullable();
|
||
$table->integer('order_column')->default(0);
|
||
$table->timestamps();
|
||
|
||
$table->index(['model_type', 'model_id']);
|
||
});
|
||
```
|
||
|
||
### Media-Model (`app/Models/Media.php`)
|
||
|
||
```php
|
||
class Media extends Model
|
||
{
|
||
use HasFactory;
|
||
|
||
protected $fillable = [
|
||
'model_type', 'model_id', 'file_path', 'type', 'alt_text', 'order_column',
|
||
];
|
||
|
||
protected function casts(): array
|
||
{
|
||
return ['order_column' => 'integer'];
|
||
}
|
||
|
||
/** Polymorphe Beziehung zum Eltern-Model */
|
||
public function model(): MorphTo
|
||
{
|
||
return $this->morphTo();
|
||
}
|
||
}
|
||
```
|
||
|
||
### Beziehung im Parent-Model (`app/Models/Product.php`)
|
||
|
||
```php
|
||
use Illuminate\Database\Eloquent\Relations\MorphMany;
|
||
|
||
public function media(): MorphMany
|
||
{
|
||
return $this->morphMany(Media::class, 'model');
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Filesystem-Konfiguration (`config/filesystems.php`)
|
||
|
||
```php
|
||
'public' => [
|
||
'driver' => 'local',
|
||
'root' => storage_path('app/public'),
|
||
'url' => env('APP_URL') . '/storage',
|
||
'visibility' => 'public',
|
||
'throw' => false,
|
||
],
|
||
```
|
||
|
||
### Symlink anlegen
|
||
|
||
```bash
|
||
php artisan storage:link
|
||
```
|
||
|
||
Erstellt `public/storage` → `storage/app/public`. **Ohne diesen Symlink sind hochgeladene Bilder nicht über den Browser erreichbar.**
|
||
|
||
---
|
||
|
||
## 5. Kritische System-Anpassungen
|
||
|
||
### 5a. `bootstrap/app.php` – Reverse-Proxy / HTTPS
|
||
|
||
```php
|
||
->withMiddleware(function (Middleware $middleware) {
|
||
// Traefik/nginx Proxy: X-Forwarded-Proto-Header vertrauen
|
||
// ZWINGEND für korrekte signierte Upload-URLs hinter einem HTTPS-Proxy
|
||
$middleware->trustProxies(at: '*');
|
||
})
|
||
```
|
||
|
||
**Warum?**
|
||
Livewire generiert für temporäre Uploads **signierte URLs**. Wenn die App hinter einem Reverse-Proxy (Traefik, nginx, Load Balancer) läuft und der Proxy HTTPS terminiert, glaubt Laravel intern, es sei HTTP. Die signierte URL wird dann mit `http://` generiert, der Browser sendet aber `https://` – die Signatur stimmt nicht, Upload schlägt fehl mit `403`.
|
||
|
||
### 5b. `app/Providers/AppServiceProvider.php` – Schema erzwingen
|
||
|
||
```php
|
||
public function boot(): void
|
||
{
|
||
// X-Forwarded-Proto auswerten und Schema erzwingen
|
||
// Nötig für Livewire Upload-URLs hinter Traefik
|
||
$scheme = request()->header('X-Forwarded-Proto')
|
||
?? request()->server('HTTP_X_FORWARDED_PROTO')
|
||
?? (request()->secure() ? 'https' : 'http');
|
||
|
||
if ($scheme === 'https') {
|
||
URL::forceScheme('https');
|
||
}
|
||
}
|
||
```
|
||
|
||
**Warum zusätzlich zum `trustProxies`?**
|
||
`trustProxies` reicht in manchen Proxy-Setups nicht aus, wenn der Header-Name variiert. `URL::forceScheme('https')` ist die sichere Ergänzung, die sicherstellt, dass alle generierten URLs das korrekte Schema haben.
|
||
|
||
**Ohne diese beiden Maßnahmen** scheitert der Upload mit einer `403 Signature mismatch`-Fehlermeldung in der Browser-Console – besonders frustrierend, weil kein PHP-Fehler erscheint.
|
||
|
||
---
|
||
|
||
## 6. Livewire-Konfiguration (`config/livewire.php`)
|
||
|
||
```php
|
||
'temporary_file_upload' => [
|
||
'disk' => null, // null = default-Disk (meist 'local')
|
||
'rules' => null, // null = ['required', 'file', 'max:12288'] (12 MB Default)
|
||
'directory' => null, // null = 'livewire-tmp'
|
||
'middleware' => null, // null = 'throttle:60,1'
|
||
'preview_mimes' => [ // Diese MIME-Types erlauben temporaryUrl()
|
||
'png', 'jpg', 'jpeg', 'gif', 'bmp', 'svg', 'webp',
|
||
'pdf', 'mp4', 'mov', 'avi', 'wmv', 'mp3', ...
|
||
],
|
||
'max_upload_time' => 5, // Minuten bis Upload ungültig wird
|
||
'cleanup' => true, // Tmp-Dateien > 24h automatisch löschen
|
||
],
|
||
```
|
||
|
||
**Wichtig:** Das interne Default-Limit ist **12 MB** (`max:12288`). Eigene Validierungsregeln wie `max:10240` müssen immer unter diesem Wert liegen. Soll das Limit erhöht werden, muss `rules` hier überschrieben werden.
|
||
|
||
---
|
||
|
||
## 7. Checkliste für ein neues Projekt
|
||
|
||
| Schritt | Was | Wo |
|
||
|---------|-----|----|
|
||
| ✅ | `use WithFileUploads` im Volt/Livewire-Component | Komponentenklasse |
|
||
| ✅ | `public array $images = []` Property anlegen | Komponentenklasse |
|
||
| ✅ | `'images.*' => 'mimes:jpeg,png\|max:10240'` Validierung | `save()`-Methode |
|
||
| ✅ | `$image->store('pfad', 'public')` beim Speichern | `save()`-Methode |
|
||
| ✅ | `$this->images = []` nach dem Speichern leeren | `save()`-Methode |
|
||
| ✅ | `php artisan storage:link` ausführen | Terminal / Deploy |
|
||
| ✅ | `$middleware->trustProxies(at: '*')` | `bootstrap/app.php` |
|
||
| ✅ | `URL::forceScheme('https')` bei HTTPS-Proxy | `AppServiceProvider.php` |
|
||
| ✅ | `wire:key` in Foreach-Schleifen | Blade-Template |
|
||
| ✅ | `array_values()` nach `unset()` auf dem Array | `removePhoto()` |
|
||
| ✅ | `isPreviewable()` vor `temporaryUrl()` prüfen | Blade-Template |
|
||
|
||
---
|
||
|
||
## 8. Häufige Fallstricke
|
||
|
||
### Upload schlägt fehl mit 403 (Signature mismatch)
|
||
→ Reverse-Proxy-Problem. Siehe Punkt 5a und 5b.
|
||
|
||
### Vorschau-Thumbnail zeigt nichts an
|
||
→ `isPreviewable()` gibt `false` zurück, wenn der MIME-Type nicht in `preview_mimes` steht. In der Livewire-Config prüfen.
|
||
|
||
### Nach `removePhoto()` stimmen die Indizes nicht
|
||
→ `array_values()` vergessen. Livewire sendet den Index als Parameter – ohne Reindizierung kommt es zu Off-by-One-Fehlern.
|
||
|
||
### Upload-Limit-Fehler vor der Validierung
|
||
→ PHP `upload_max_filesize` und `post_max_size` in `php.ini` überprüfen. Auch Livewires internes `max:12288`-Limit beachten.
|
||
|
||
### `temporaryUrl()` wirft eine Exception
|
||
→ Bei lokalen Disks ohne `serve: true` in `filesystems.php` funktioniert `temporaryUrl()` nicht. Entweder `serve: true` setzen oder S3 verwenden. Im Template immer mit `isPreviewable()` absichern.
|
||
|
||
### Bilder nach Deploy nicht sichtbar
|
||
→ `php artisan storage:link` auf dem Produktionssystem ausführen. Im Docker-Container nach jedem `down/up` prüfen, ob der Symlink noch existiert.
|