WooCommerce CLI ile Ürün Görseli Toplu Güncelleme

Tarafındankomut
0 Comments

E-ticaret sitelerinde en can sıkıcı işlerden biri toplu görsel yönetimidir. Yüzlerce ürünün görselini tek tek WooCommerce arayüzünden güncellemek saatler alabilir, bazen de shared hosting panellerinin timeout süreleri bu işi tamamen imkânsız hâle getirir. WP-CLI’nin WooCommerce entegrasyonu sayesinde bu işlemi terminal üzerinden saniyeler içinde halledebilirsin. Bu yazıda gerçek dünya senaryolarıyla WooCommerce CLI komutlarını kullanarak ürün görsellerini toplu olarak nasıl güncelleyeceğini anlatacağım.

Ön Hazırlık ve Ortam Kontrolü

Başlamadan önce birkaç şeyi doğrulaman gerekiyor. WP-CLI’nin kurulu ve çalışır durumda olması, WooCommerce eklentisinin aktif olması ve WordPress medya kütüphanesine erişimin bulunması şart.

# WP-CLI sürümünü kontrol et
wp --version

# WordPress kurulum dizinine gir
cd /var/www/html/siteniz.com

# WooCommerce'in aktif olup olmadığını kontrol et
wp plugin is-active woocommerce && echo "WooCommerce aktif" || echo "WooCommerce pasif"

# Mevcut ürün sayısını öğren
wp post list --post_type=product --post_status=publish --format=count

Bu adımları geçtikten sonra asıl konuya geçebiliriz.

WooCommerce CLI ile Ürün Yönetiminin Temelleri

WP-CLI, WooCommerce REST API’sini sarmalayan wc komut grubunu sağlar. Bu komutlar sayesinde ürünleri listeleyebilir, düzenleyebilir ve görsellerini programatik olarak yönetebilirsin.

# Tüm ürünleri listele (id ve başlık)
wp wc product list --user=admin --format=table --fields=id,name,status

# Belirli bir ürünün detaylarını gör
wp wc product get 123 --user=admin --format=json

# Ürünün mevcut görsel bilgilerini kontrol et
wp wc product get 123 --user=admin --field=images

Önemli not: --user=admin parametresini her WooCommerce CLI komutunda kullanman gerekiyor. Aksi hâlde yetki hatası alırsın. Buradaki admin değerini kendi yönetici kullanıcı adınla değiştir.

Medya Kütüphanesine Görsel Yükleme

Görselleri ürünlere atamadan önce WordPress medya kütüphanesine yüklemiş olman gerekiyor. İki farklı senaryo var: görseller sunucuda zaten mevcut ya da dışarıdan URL üzerinden alınacak.

Sunucudaki Görselleri Kütüphaneye Aktarma

# Tek bir görseli medya kütüphanesine import et
wp media import /tmp/gorseller/urun-123.jpg --title="Ürün 123 Ana Görsel" --porcelain

# Bir klasördeki tüm görselleri toplu import et
for img in /tmp/gorseller/*.jpg; do
    wp media import "$img" --porcelain
done

# Import ederken doğrudan bir ürüne bağla
wp media import /tmp/gorseller/urun-123.jpg --post_id=123 --featured_image --porcelain

--porcelain parametresi sadece yüklenen medyanın ID’sini döndürür. Bu ID’yi sonraki adımlarda kullanacağız için bu parametre kritik.

URL’den Görsel Çekme

# Dışarıdan görsel URL'si ile import et
wp media import "https://kaynak-site.com/urun-gorseli.jpg" 
    --title="İthal Ürün Görseli" 
    --porcelain

Tekil Ürün Görseli Güncelleme

Mantığı kavramak için önce tek bir ürün üzerinde çalışalım.

# Adım 1: Görseli medya kütüphanesine yükle, ID'yi kaydet
IMAGE_ID=$(wp media import /tmp/gorseller/urun-456.jpg --porcelain)
echo "Yüklenen görsel ID: $IMAGE_ID"

# Adım 2: Bu görseli ürünün ana görseli olarak ata
wp wc product update 456 
    --user=admin 
    --images='[{"id":'"$IMAGE_ID"',"position":0}]'

# Güncellemenin başarılı olduğunu doğrula
wp wc product get 456 --user=admin --field=images

Buradaki JSON formatına dikkat et. WooCommerce görsel API’si images alanını bir dizi olarak bekliyor. position:0 ana görseli, diğer pozisyonlar ise galeri görsellerini temsil ediyor.

Gerçek Dünya Senaryosu 1: CSV Dosyasından Toplu Güncelleme

En yaygın senaryo budur. Elinde bir ürün listesi ve her ürüne karşılık gelen görsel dosya adları var. Bunu bir CSV ile yönetebilirsin.

Önce CSV dosyası formatı şu şekilde olmalı:

  • product_id: WooCommerce ürün ID’si
  • image_path: Sunucudaki görsel dosya yolu
  • image_alt: Görselin alt metni
#!/bin/bash
# toplu_gorsel_guncelle.sh
# Kullanım: bash toplu_gorsel_guncelle.sh urunler.csv

CSV_FILE=$1
WP_PATH="/var/www/html/siteniz.com"
WP_USER="admin"
LOG_FILE="/tmp/gorsel_guncelleme_$(date +%Y%m%d_%H%M%S).log"

echo "İşlem başlıyor: $(date)" | tee -a $LOG_FILE

# CSV'nin ilk satırını (başlık) atla, geri kalanı işle
tail -n +2 "$CSV_FILE" | while IFS=',' read -r product_id image_path image_alt; do
    
    # Dosya var mı kontrol et
    if [ ! -f "$image_path" ]; then
        echo "HATA: Dosya bulunamadı - $image_path (Ürün ID: $product_id)" | tee -a $LOG_FILE
        continue
    fi
    
    # Görseli medya kütüphanesine yükle
    IMAGE_ID=$(wp media import "$image_path" 
        --path="$WP_PATH" 
        --porcelain 2>/dev/null)
    
    if [ -z "$IMAGE_ID" ]; then
        echo "HATA: Görsel yüklenemedi - $image_path" | tee -a $LOG_FILE
        continue
    fi
    
    # Ürünü güncelle
    wp wc product update "$product_id" 
        --user="$WP_USER" 
        --path="$WP_PATH" 
        --images='[{"id":'"$IMAGE_ID"',"alt":"'"$image_alt"'","position":0}]' 2>/dev/null
    
    if [ $? -eq 0 ]; then
        echo "BAŞARILI: Ürün $product_id - Görsel ID: $IMAGE_ID" | tee -a $LOG_FILE
    else
        echo "HATA: Ürün $product_id güncellenemedi" | tee -a $LOG_FILE
    fi
    
    # Sunucuyu yormamak için kısa bekleme
    sleep 0.5
    
done

echo "İşlem tamamlandı: $(date)" | tee -a $LOG_FILE
echo "Log dosyası: $LOG_FILE"

Bu scripti çalıştırmadan önce CSV dosyasını şu şekilde hazırla:

# urunler.csv örnek içerik oluştur
cat > /tmp/urunler.csv << 'EOF'
product_id,image_path,image_alt
123,/tmp/gorseller/urun-123.jpg,Kırmızı Polo Tişört
456,/tmp/gorseller/urun-456.jpg,Mavi Kot Pantolon
789,/tmp/gorseller/urun-789.jpg,Beyaz Spor Ayakkabı
EOF

# Scripti çalıştır
bash toplu_gorsel_guncelle.sh /tmp/urunler.csv

Gerçek Dünya Senaryosu 2: Ürün SKU’ya Göre Eşleştirme

Çoğu e-ticaret senaryosunda görsel dosyaları ürün ID’si yerine SKU kodu ile adlandırılmıştır. Örneğin SKU-TR-1234.jpg gibi. Bu durumda önce SKU’dan ID’ye dönüşüm yapman gerekiyor.

#!/bin/bash
# sku_bazli_gorsel_guncelle.sh

GORSEL_DIZIN="/tmp/sku_gorseller"
WP_USER="admin"
LOG_FILE="/tmp/sku_gorsel_log_$(date +%Y%m%d).log"

echo "SKU bazlı görsel güncelleme başlıyor..." | tee -a $LOG_FILE

for img_file in "$GORSEL_DIZIN"/*.jpg "$GORSEL_DIZIN"/*.png; do
    
    # Dosya yoksa atla
    [ -f "$img_file" ] || continue
    
    # Dosya adından SKU'yu çıkar (uzantıyı kaldır)
    filename=$(basename "$img_file")
    SKU="${filename%.*}"
    
    # SKU ile ürün ID'sini bul
    PRODUCT_ID=$(wp post list 
        --post_type=product 
        --meta_key=_sku 
        --meta_value="$SKU" 
        --format=ids 2>/dev/null)
    
    if [ -z "$PRODUCT_ID" ]; then
        echo "UYARI: '$SKU' SKU'su için ürün bulunamadı" | tee -a $LOG_FILE
        continue
    fi
    
    # Görseli yükle
    IMAGE_ID=$(wp media import "$img_file" --porcelain 2>/dev/null)
    
    # Ürünü güncelle
    wp wc product update "$PRODUCT_ID" 
        --user="$WP_USER" 
        --images='[{"id":'"$IMAGE_ID"',"position":0}]'
    
    echo "OK: SKU=$SKU | Ürün ID=$PRODUCT_ID | Görsel ID=$IMAGE_ID" | tee -a $LOG_FILE
    
done

Ürün Galeri Görsellerini Güncelleme

Bazen ana görsele ek olarak birden fazla galeri görseli de eklemon gerekir. WooCommerce API’sinde position değeri bunu yönetir.

# Birden fazla görsel ekle: ilki ana görsel, diğerleri galeri
wp wc product update 123 
    --user=admin 
    --images='[
        {"id":501,"position":0,"alt":"Ana Ürün Görseli"},
        {"id":502,"position":1,"alt":"Ürün Yan Görünüm"},
        {"id":503,"position":2,"alt":"Ürün Detay"},
        {"id":504,"position":3,"alt":"Ürün Ambalaj"}
    ]'

Mevcut Galeri Görsellerine Yeni Görsel Ekleme

Var olan görselleri silmeden üstüne yeni görsel eklemek istiyorsan önce mevcut görselleri çekip listeye eklemelisin.

#!/bin/bash
# Mevcut görselleri koru, yeni görsel ekle

PRODUCT_ID=123
NEW_IMAGE="/tmp/yeni-gorsel.jpg"
WP_USER="admin"

# Yeni görseli yükle
NEW_IMAGE_ID=$(wp media import "$NEW_IMAGE" --porcelain)

# Mevcut görsellerin ID'lerini al
EXISTING_IMAGES=$(wp wc product get $PRODUCT_ID 
    --user=$WP_USER 
    --field=images 
    --format=json | python3 -c "
import sys, json
images = json.load(sys.stdin)
ids = [str(img['id']) for img in images]
print(','.join(ids))
")

echo "Mevcut görsel ID'leri: $EXISTING_IMAGES"
echo "Yeni görsel ID: $NEW_IMAGE_ID"

# Yeni JSON oluştur (python ile)
python3 << PYEOF
import subprocess, json

existing_ids = "$EXISTING_IMAGES".split(',')
new_id = "$NEW_IMAGE_ID"

images = []
for i, img_id in enumerate(existing_ids):
    if img_id:
        images.append({"id": int(img_id), "position": i})

images.append({"id": int(new_id), "position": len(images)})

images_json = json.dumps(images)
cmd = f"wp wc product update $PRODUCT_ID --user=$WP_USER --images='{images_json}'"
print(f"Çalıştırılan komut: {cmd}")
subprocess.run(cmd, shell=True)
PYEOF

Gerçek Dünya Senaryosu 3: Görseli Olmayan Ürünleri Tespit Etme

Yüzlerce ürünlük bir katalogda hangi ürünlerin görseli eksik, bunu tespit etmek toplu güncelleme öncesinde yapman gereken ilk adım olmalı.

#!/bin/bash
# Görseli olmayan ürünleri tespit et

WP_USER="admin"
OUTPUT_FILE="/tmp/gorselsiz_urunler.txt"

echo "Görseli olmayan ürünler taranıyor..."
echo "product_id,product_name,sku" > $OUTPUT_FILE

# Tüm yayınlanmış ürün ID'lerini al
PRODUCT_IDS=$(wp post list 
    --post_type=product 
    --post_status=publish 
    --format=ids)

TOTAL=$(echo $PRODUCT_IDS | wc -w)
COUNT=0

for pid in $PRODUCT_IDS; do
    COUNT=$((COUNT + 1))
    printf "rİşleniyor: $COUNT / $TOTAL"
    
    # Ürünün thumbnail ID'sini kontrol et
    THUMB_ID=$(wp post meta get $pid _thumbnail_id 2>/dev/null)
    
    if [ -z "$THUMB_ID" ]; then
        PRODUCT_NAME=$(wp post get $pid --field=post_title)
        SKU=$(wp post meta get $pid _sku 2>/dev/null)
        echo "$pid,$PRODUCT_NAME,$SKU" >> $OUTPUT_FILE
    fi
done

echo ""
echo "Tarama tamamlandı!"
MISSING=$(tail -n +2 $OUTPUT_FILE | wc -l)
echo "Görseli olmayan ürün sayısı: $MISSING"
echo "Liste kaydedildi: $OUTPUT_FILE"

Hata Yönetimi ve Doğrulama

Toplu işlemlerde bir şeyler ters gidebilir. Güncelleme sonrası doğrulama yapmak iyi pratiktir.

#!/bin/bash
# Güncelleme sonrası doğrulama scripti

WP_USER="admin"
GUNCELLENEN_URUNLER="123 456 789 1011"

echo "Doğrulama başlıyor..."

for pid in $GUNCELLENEN_URUNLER; do
    
    # Ürünün görsel sayısını kontrol et
    IMAGE_COUNT=$(wp wc product get $pid 
        --user=$WP_USER 
        --field=images 
        --format=json 2>/dev/null | python3 -c "
import sys, json
try:
    images = json.load(sys.stdin)
    print(len(images))
except:
    print(0)
")
    
    if [ "$IMAGE_COUNT" -gt 0 ]; then
        echo "OK: Ürün $pid - $IMAGE_COUNT görsel mevcut"
    else
        echo "UYARI: Ürün $pid - Görsel bulunamadı!"
    fi
    
done

Thumbnail Önbelleğini Yenileme

Görselleri güncelledikten sonra WordPress’in farklı boyutlarda ürettiği thumbnail’lerin yenilenmesi gerekebilir. Özellikle eski ürün görsellerini değiştirdiysen bu adımı atlama.

# Tüm görsel boyutlarını yeniden oluştur (dikkatli kullan, yavaş çalışır)
wp media regenerate --yes

# Sadece belirli bir görseli yenile
wp media regenerate 501 --yes

# Son 100 yüklenen medyayı yenile
wp media regenerate $(wp post list --post_type=attachment --format=ids --posts_per_page=100)

# Toplu thumbnail yenilemeyi arka planda çalıştır
nohup wp media regenerate --yes > /tmp/regenerate_log.txt 2>&1 &
echo "Arka plan işlem PID: $!"

Performans İpuçları

Büyük kataloglarda çalışırken birkaç şeye dikkat etmek gerekiyor.

WP-CLI cache kullan: Her sorgu WordPress’i tam olarak boot ettiğinden dolayı ardışık işlemlerde --skip-plugins ve --skip-themes parametreleriyle hızlanabilirsin ancak bu durum WooCommerce komutlarında her zaman çalışmaz, test et.

Batch işlem yap: Bin ürünü tek seferde işlemek yerine 100’lük gruplar hâlinde işle ve her grup arasında birkaç saniyelik bekleme ekle.

Screen veya tmux kullan: Uzun süren işlemleri SSH bağlantısı kesilmesinden korumak için her zaman screen veya tmux içinde çalıştır.

# Screen ile uzun işlem başlat
screen -S gorsel-guncelleme
bash toplu_gorsel_guncelle.sh urunler.csv

# Detach et (Ctrl+A, D)
# Sonra tekrar bağlan
screen -r gorsel-guncelleme

MySQL sorgu sayısını izle: Toplu işlemler sırasında veritabanı yükü artabilir. mytop veya innotop ile izleyebilirsin.

Memory limit: WP-CLI varsayılan memory limitini zaman zaman aşabilir. wp --max-memory=512M şeklinde artırabilirsin.

Sık Karşılaşılan Hatalar ve Çözümleri

“Error: Sorry, you are not allowed to do this.” hatası: Bu hata --user parametresini vermediğinde veya yanlış kullanıcı belirttiğinde çıkar. Kullanıcının yönetici rolünde olduğundan emin ol.

“Cannot create a post with an empty title.” hatası: wp media import komutunda --title parametresi boş geçilmiş olabilir. Dosya adını title olarak kullanabilirsin.

JSON parse hatası: Görsel güncelleme komutundaki JSON’da Türkçe karakter veya tırnak işareti varsa sorun çıkabilir. Alt metinleri kaçış karakterleriyle yaz ya da ayrı bir JSON dosyasından oku.

Görsel yüklendi ama ürüne atanmadı: Bu genellikle WooCommerce REST API izin sorunudur. WordPress güzel URL’lerinin (permalinks) aktif olduğunu ve en az bir kez kaydedildiğini kontrol et.

# Permalink'leri yenile (bu komutu çalıştırmak genellikle API sorunlarını çözer)
wp rewrite flush --hard

Sonuç

WooCommerce CLI ile ürün görsel yönetimi, manuel işlemlere kıyasla hem zaman hem de hata riski açısından çok daha verimli bir yaklaşım sunuyor. Yüzlerce ürünün görselini tek tek admin panelinden güncellemek yerine iyi yazılmış bir bash scriptiyle bu işi dakikalar içinde bitirebilirsin.

En önemli noktalar şunlar: her işlemden önce yedek al, scripti küçük bir veri setiyle test et, log tutmayı ihmal etme ve toplu işlem sonrası mutlaka doğrulama yap. SKU bazlı eşleştirme, CSV okuma ve eksik görsel tespiti gibi gerçek dünya senaryoları bir araya getirildiğinde bu araçlar oldukça güçlü bir ürün yönetim sistemi oluşturuyor.

Farklı görsel yönetim senaryolarında takıldığın noktalar olursa yorum olarak bırakabilirsin. WooCommerce CLI’nin product variation görselleri gibi daha ileri konuları da ilerleyen yazılarda ele alacağım.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir