Wir bereiten die neuesten Anleitungen, Releases und Feature-Updates vor.
Anleitungen werden geladen
Wir bereiten die passenden Inhalte der Wissensdatenbank für diese Plattform vor.
Einen eigenen Cloud-Storage-Handler implementieren | Chamevo Support Center
Einen eigenen Cloud-Storage-Handler implementieren
Verwenden Sie den Filter chamevo_storage_handler, um Kunden-Uploads und druckfertige Dateien über die Implementierung von StorageHandlerInterface an einen beliebigen Cloud-Storage-Anbieter weiterzuleiten.
Aktualisiert am 9. Mai 20265 Min. Lesezeit
Standardmäßig speichert Chamevo alle Dateien im lokalen WordPress-Dateisystem unter wp-content/uploads/chamevo/. Mit dem Filter chamevo_storage_handler können Sie zwei Ordnertypen — Kunden-Uploads und generierte druckfertige Dateien — an einen externen Storage-Anbieter weiterleiten: Amazon S3, Hetzner Object Storage, Google Cloud Storage, Dropbox (programmatisch) oder jeden anderen Dienst mit einem PHP SDK.
Die integrierten Dropbox- und AWS S3-Lieferungseinstellungen decken die häufigsten Anwendungsfälle ohne Code ab. Verwenden Sie diese API, wenn Sie einen nicht integrierten Anbieter benötigen oder wenn Sie unterschiedliche Buckets, CDN-Konfigurationen oder eigene Geschäftslogik pro Ordnertyp brauchen.
Geltungsbereich
Nur zwei Ordnertypen können zu Cloud Storage weitergeleitet werden:
Ordnertyp
Inhalt
Standard-lokaler Pfad
uploads
Vom Kunden hochgeladene Dateien aus dem Frontend-Customizer (Bilder, PDFs, SVGs)
Dateien werden immer zuerst lokal verarbeitet, unabhängig davon, welcher Storage-Handler aktiv ist:
Die Datei wird empfangen und in das lokale Dateisystem geschrieben.
Chamevo führt die lokale Verarbeitung durch: Validierung, EXIF-Rotation, SVG-Bereinigung, Imagick-Filter.
putFromLocal() wird am aktiven Handler aufgerufen. Beim Standard-LocalStorageHandler ist dies ein No-op.
URLs, die an das Frontend, E-Mails und Drittanbieter zurückgegeben werden, stammen aus der url()-Methode des Handlers.
Das bedeutet: Ihr Handler empfängt niemals eine unverarbeitete Datei.
Einen Handler registrieren
Verwenden Sie den Filter chamevo_storage_handler, um Ihre Handler-Instanz zurückzugeben. Der Filter empfängt zwei Argumente: den aktuellen Handler (standardmäßig null) und den Ordnertyp-String.
add_filter('chamevo_storage_handler', function ($handler, $folderType) {
if ($folderType === 'uploads') {
return new My_S3_Handler([
'bucket' => 'customer-uploads',
'region' => 'eu-central-1',
'cdn_url' => 'https://uploads-cdn.example.com',
]);
}
if ($folderType === 'print_files') {
return new My_S3_Handler([
'bucket' => 'print-files',
'region' => 'eu-central-1',
'cdn_url' => 'https://print-cdn.example.com',
]);
}
return $handler; // return null to keep local storage for this folder type
}, 10, 2);
Jeder Ordnertyp wird unabhängig aufgelöst. Sie können unterschiedliche Buckets, unterschiedliche Anbieter verwenden oder nur einen Ordnertyp weiterleiten, während der andere lokal bleibt.
StorageHandlerInterface implementieren
Ihre Handler-Klasse muss alle 7 Methoden von Radykal\Chamevo\Storage\StorageHandlerInterface implementieren:
use Radykal\Chamevo\Storage\StorageHandlerInterface;
class My_S3_Handler implements StorageHandlerInterface
{
public function put(string $relativePath, string $contents): bool {}
public function putFromLocal(string $relativePath, string $localAbsolutePath): bool {}
public function get(string $relativePath): ?string {}
public function delete(string $relativePath): bool {}
public function deleteDirectory(string $relativePath): bool {}
public function exists(string $relativePath): bool {}
public function url(string $relativePath): string {}
}
Nach jedem Kunden-Upload und jeder druckfertigen Dateigenerierung
Häufigster Schreibpfad. Empfängt den absoluten lokalen Pfad der bereits verarbeiteten Datei.
put(string $relativePath, string $contents): bool
Beim direkten Schreiben von Inhalten, nicht aus einer lokalen Datei
Weniger häufig. Stellen Sie sicher, dass übergeordnete „Verzeichnisse" in Ihrem Storage vorhanden sind, falls nötig.
get(string $relativePath): ?string
Wenn E-Mail-Anhänge eine lokale Kopie einer cloud-gespeicherten druckfertigen Datei benötigen
wp_mail() erfordert einen lokalen Pfad, daher lädt Chamevo die Datei vor dem Anhängen in _temp/ herunter. Geben Sie null zurück, wenn die Datei nicht vorhanden ist.
url(string $relativePath): string
Immer wenn eine Datei-URL benötigt wird — Frontend-Antwort, E-Mail-Links, Printful API
Muss eine öffentlich zugängliche URL zurückgeben. Für die Printful-Integration muss die URL von Printfuls Servern erreichbar sein.
delete(string $relativePath): bool
Wenn einzelne Dateien bereinigt werden
Sollte idempotent sein — geben Sie true zurück, wenn die Datei nicht existiert.
Ein leerer String bedeutet alles löschen. Chamevo leert das lokale Verzeichnis separat ebenfalls.
exists(string $relativePath): bool
Vor dem Bereitstellen oder Verarbeiten einer Datei
Wird verwendet, um die Dateiverfügbarkeit vor Operationen zu prüfen.
Relative Pfade
Alle $relativePath-Werte sind relativ zum Ordner-Stammverzeichnis — niemals absolute Dateisystempfade. Ordnen Sie diese einer beliebigen Bucket-Prefix-Struktur zu.
uploads-Beispiele:
2026/04/15/abc123def456.jpeg # date-organized customer upload
2026/04/15/abc123def456_1.png # PDF page converted to PNG
print_files-Beispiele:
1713182400a1b2c3d4e5f6g7h8/12345_456.pdf # order export
1713182400a1b2c3d4e5f6g7h8/12345_456_1.png # extracted PNG page
Lokale Dateien nach Cloud-Push löschen
Standardmäßig werden lokale Dateien nach dem Push in den Cloud Storage behalten. Verwenden Sie chamevo_storage_delete_local_after_push, um Speicherplatz freizugeben:
// Delete local uploads after push, keep print_files locally
add_filter('chamevo_storage_delete_local_after_push', function ($delete, $folderType) {
return $folderType === 'uploads';
}, 10, 2);
// Delete both folder types after push
add_filter('chamevo_storage_delete_local_after_push', '__return_true');
Die lokale Datei wird nach Abschluss der gesamten Verarbeitung gelöscht. Die Cloud-Kopie und ihre URL sind davon nicht betroffen.
Ordnertyp
Empfehlung
Grund
uploads
Sicher zu aktivieren
Nach dem Cloud-Push wird nur noch die URL benötigt.
print_files
Mit Vorsicht verwenden
Printful liest lokale Dateien für die ZIP-Extraktion. E-Mail-Anhänge werden bei Cloud Storage von _temp/ heruntergeladen, was zu Latenz führt. Nur aktivieren, wenn Sie Printful nicht verwenden und die E-Mail-Latenz akzeptieren.
Dieser Filter hat keine Auswirkung, wenn lokaler Storage verwendet wird (kein Cloud-Handler registriert). Der Standardwert ist false und muss explizit aktiviert werden. Das Verzeichnis _temp/ ist nie betroffen.
StorageManager API
Für erweiterte Anwendungsfälle können Sie direkt über Radykal\Chamevo\Storage\StorageManager mit der Storage-Schicht interagieren:
use Radykal\Chamevo\Storage\StorageManager;
// Get the active handler for a folder type
$handler = StorageManager::handler('uploads');
// Get a public URL
$url = StorageManager::url('uploads', '2026/04/15/abc123.png');
// Check if a file exists
$exists = StorageManager::handler('print_files')->exists('170abc.../order.pdf');
// Write content directly
StorageManager::handler('uploads')->put('path/to/file.png', $binaryContent);
// Delete a file
StorageManager::handler('print_files')->delete('170abc.../order.pdf');
Besonderheiten
Downloads von druckfertigen Dateien
Wenn ein Besucher oder Administrator eine druckfertige Datei herunterlädt:
Lokaler Storage: Die Datei wird direkt von der Festplatte gestreamt.
Cloud Storage: Chamevo gibt eine 302-Weiterleitung zur Cloud-URL aus. Der Browser lädt direkt von Ihrem CDN oder Bucket herunter — kein Proxying über den WordPress-Server.
E-Mail-Anhänge
wp_mail() erfordert einen lokalen Dateisystempfad für Anhänge. Wenn Cloud Storage für print_files aktiv ist:
Chamevo ruft $handler->get($relativePath) auf, um den Dateiinhalt abzurufen.
Der Inhalt wird in _temp/ geschrieben.
Der temporäre Pfad wird an wp_mail() übergeben.
Dies führt zu einer geringen Latenz bei cloud-gespeicherten druckfertigen Dateien beim Versenden von Bestellmails.
Datenbankkompatibilität
Druckjob-Datensätze speichern den relativen Dateipfad (zum Beispiel 170abc.../order_123.pdf). Dies funktioniert identisch für lokalen und Cloud Storage. Bestehende Datensätze mit veralteten absoluten Pfaden werden automatisch verarbeitet — eine Migration ist nicht erforderlich.
Filterreferenz
Filter
Argumente
Standard
Beschreibung
chamevo_storage_handler
$handler (null), $folderType (string)
null
Geben Sie eine StorageHandlerInterface-Instanz zurück, um den Storage für den angegebenen Ordnertyp zu überschreiben. Geben Sie null oder den ursprünglichen $handler zurück, um lokalen Storage beizubehalten.
chamevo_storage_delete_local_after_push
$delete (bool), $folderType (string)
false
Geben Sie true zurück, um die lokale Datei nach einem erfolgreichen Cloud-Push zu löschen. Nur wirksam, wenn ein Cloud-Handler aktiv ist.
Handler testen
Upload-Test — Laden Sie ein Bild im Frontend-Customizer hoch. Überprüfen Sie, ob die Datei in Ihrem Cloud Storage erscheint und die zurückgegebene URL korrekt auflöst.
Druckdatei-Test — Lösen Sie eine Druckdateigenerierung über einen Bestellexport aus. Überprüfen Sie, ob die Datei in der Cloud gespeichert ist und der Download-Link korrekt weiterleitet.
E-Mail-Test — Platzieren Sie eine WooCommerce-Bestellung, die eine Bestellmail mit druckfertigem Dateianhang auslöst. Überprüfen Sie, ob der Anhang enthalten ist.
Printful-Test (falls zutreffend) — Platzieren Sie eine Bestellung mit Printful-Integration. Überprüfen Sie, ob Printful die korrekte Cloud-URL empfängt und abrufen kann.
Bereinigungstest — Verwenden Sie die Admin-Wartungsaktion unter Utilities, um das druckfertige Verzeichnis zu leeren. Überprüfen Sie, ob Dateien aus dem Cloud Storage gelöscht werden.
FAQ
F: Kann ich für Uploads und druckfertige Dateien unterschiedliche Anbieter verwenden?
A: Ja. Der Filter chamevo_storage_handler empfängt $folderType als zweites Argument. Geben Sie für jeden Typ eine andere Handler-Instanz zurück.
F: Werden lokale Dateien nach dem Cloud-Push automatisch gelöscht?
A: Nein, nicht standardmäßig. Fügen Sie den Filter chamevo_storage_delete_local_after_push hinzu und geben Sie true zurück, um die Bereinigung zu aktivieren. Seien Sie bei print_files vorsichtig, wenn Sie Printful verwenden oder schnelle E-Mail-Anhänge benötigen.
F: Was passiert, wenn putFromLocal() false zurückgibt?
A: Der Upload in den Cloud Storage ist fehlgeschlagen. Die Datei bleibt im lokalen Dateisystem und ist weiterhin zugänglich. Chamevo versucht es nicht automatisch erneut — behandeln Sie Fehler und Logging innerhalb Ihres Handlers.
F: Muss die von url() zurückgegebene URL öffentlich zugänglich sein?
A: Ja. Die URL wird an den Browser gesendet, in Bestellmails eingefügt und an Drittanbieter wie Printful weitergegeben. Signierte oder ablaufende URLs brechen diese Integrationen — verwenden Sie eine öffentliche CDN-URL oder eine dauerhaft zugängliche Bucket-URL.
