ContextHub Migrator - WordPress Plugin

WordPress içeriklerinizi ve medyalarınızı ContextHub'a güvenli ve kolay bir şekilde aktaran migration plugini.

🎯 Özellikler

• ✅ Toplu İçerik Migration: Seçtiğiniz tüm içerikleri tek seferde migrate edin
• ✅ Lexical JSON Dönüşümü: WordPress HTML içeriğini Lexical JSON formatına otomatik çevirir
• ✅ Medya Migration: Öne çıkan görselleri ve içerikteki tüm görselleri otomatik aktarır
• ✅ Kategori Eşleştirme: WordPress kategorilerinizi ContextHub kategorileri ile eşleştirin
• ✅ Batch Processing: Büyük miktarda içeriği kesintisiz migrate edin
• ✅ Migration Log: Tüm migration işlemlerini detaylı olarak takip edin
• ✅ API Token Auth: Güvenli API token kimlik doğrulaması

📋 Gereksinimler

• WordPress 6.2 veya üzeri
• PHP 7.4 veya üzeri
• ContextHub API erişimi
• ContextHub API Token (write yetkisi ile)

🚀 Kurulum

1. Plugin Dosyalarını Yükleyin

Plugin klasörünü WordPress wp-content/plugins/ dizinine kopyalayın:

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/devburak/contexthub-wp-migrator.git contexthub-migrator

veya ZIP olarak yükleyin:

• Plugins → Add New → Upload Plugin

2. Plugin'i Aktifleştirin

WordPress Admin → Plugins → ContextHub Migrator → Activate

3. API Ayarlarını Yapın

1. WordPress Admin → ContextHub → Settings
2. Gerekli bilgileri girin:
   • API URL: https://api.ctxhub.net/api
   • API Token: ContextHub'dan aldığınız token (ctx_ ile başlamalı)
   • Tenant ID: Opsiyonel override. Token tenant kapsamlıysa boş bırakabilirsiniz
   • Recovery Mode: Mevcut R2 objelerini yeniden upload etmeden eşleştirmek için açın
3. Bağlantıyı Test Et butonuna tıklayarak bağlantıyı doğrulayın
4. Ayarları Kaydet

📖 Kullanım Kılavuzu

Adım 1: Kategori Eşleştirmesi

WordPress Admin → ContextHub → ContextHub

1. Kategori Eşleştirmesi bölümünde WordPress kategorilerinizi göreceksiniz
2. Her kategori için ContextHub'daki karşılığını seçin
   • Mevcut kategorilerden birini seçebilirsiniz
   • Veya "Yeni Oluştur" seçerek otomatik oluşturabilirsiniz

Adım 2: İçerik Seçimi

1. İçerik Seçimi bölümünde migrate edilecek içerikleri seçin

2. Kolay seçim için:

   • Tümünü Seç: Tüm içerikleri seç
   • Seçimi Kaldır: Tüm seçimleri kaldır
   • Sadece Migrate Edilmemiş: Sadece henüz migrate edilmemiş içerikleri seç

3. Manuel olarak da checkbox'ları kullanarak seçim yapabilirsiniz

Adım 3: Migration Başlat

1. Görselleri de migrate et seçeneğini işaretleyin (önerilir)
2. Migration Başlat butonuna tıklayın
3. Onay dialogunda "OK" deyin

Migration İzleme

Migration başladıktan sonra:

• İlerleme çubuğu ile progress takibi
• Real-time log çıktısı
• Her içerik için başarı/hata durumu

Migration tamamlandığında sayfa otomatik yenilenir.

🔧 Teknik Detaylar

İçerik Dönüşümü

Plugin, WordPress HTML içeriğini Lexical JSON formatına çevirir:

Desteklenen HTML Elementleri:

• Paragraflar (<p>)
• Başlıklar (<h1> - <h6>)
• Listeler (<ul>, <ol>, <li>)
• Alıntılar (<blockquote>)
• Linkler (<a>)
• Görseller (<img>)
• Kod blokları (<pre>, <code>)
• Yatay çizgiler (<hr>)
• Satır sonları (<br>)

Desteklenen Formatlar:

• Bold (<strong>, <b>)
• Italic (<em>, <i>)
• Underline (<u>)
• Code (<code>)

Medya Migration

1. Featured Image: Öne çıkan görsel ContextHub'a yüklenir
2. İçerik Görselleri: İçerikteki tüm <img> taglerindeki görseller bulunur ve yüklenir
3. URL Güncelleme: Tüm görsel URL'leri otomatik olarak ContextHub URL'leri ile değiştirilir
4. Caching: Bir kez yüklenen görseller cache'lenir, tekrar yüklenmez

API İletişimi

Plugin, ContextHub API'si ile şu şekilde iletişim kurar:

POST /api/media
- Medya dosyalarını yükler
- multipart/form-data

POST /api/contents
- İçerikleri oluşturur
- JSON body:
  {
    "title": "Post başlığı",
    "slug": "post-slug",
    "content": "{lexical json}",
    "htmlContent": "<html>",
    "categories": ["category-id"],
    "featuredMedia": "media-id",
    "status": "published",
    "publishedAt": "2024-01-01T00:00:00Z",
    "metadata": {
      "wordpress_id": 123,
      "migrated_at": "..."
    }
  }

GET /api/categories
- Kategorileri listeler

POST /api/categories
- Yeni kategori oluşturur

📊 Migration Log

WordPress Admin → ContextHub → Migration Log

Bu sayfada:

• Tüm migration işlemleri listelenir
• Her post için:
  • WordPress Post ID
  • Post Başlığı
  • ContextHub ID
  • Durum (Başarılı/Hata)
  • Hata mesajı (varsa)
  • Tarih

🗄️ Veritabanı

Plugin, migration durumunu takip etmek için bir tablo oluşturur:

wp_contexthub_migration_log
- id
- post_id (WordPress post ID)
- contexthub_id (ContextHub content ID)
- status (success/error)
- error_message
- created_at
- updated_at

🛡️ Güvenlik

• ✅ API Token ile kimlik doğrulama
• ✅ WordPress nonce kontrolü
• ✅ Capability check (manage_options)
• ✅ SQL injection koruması
• ✅ XSS koruması
• ✅ CSRF koruması

🐛 Sorun Giderme

"API bağlantı hatası"

1. API URL'nin doğru olduğundan emin olun
2. ContextHub API'nizin çalıştığını kontrol edin
3. API Token'ın geçerli olduğunu kontrol edin
4. Tenant ID boşsa token'ın tenant kapsamlı olduğundan emin olun

"Media upload failed"

1. Görselin WordPress'te mevcut olduğundan emin olun
2. Dosya izinlerini kontrol edin
3. API Token'ın write yetkisine sahip olduğunu kontrol edin
4. ContextHub'da yeterli storage limitiniz olduğunu kontrol edin

"Migration çok yavaş"

1. PHP max_execution_time limitini artırın
2. Daha az içerik seçerek parça parça migration yapın
3. Sunucu kaynaklarını kontrol edin

"Görseller yüklenmiyor"

1. PHP upload_max_filesize ve post_max_size limitlerini kontrol edin
2. Görsellerin erişilebilir olduğundan emin olun
3. ContextHub API'nin media endpoint'inin çalıştığını kontrol edin

📝 Changelog

Version 2.1.2 (2026-06-30)

• ✅ "Featured Video" (tagDiv) tespiti sağlamlaştırıldı: bilinen meta anahtarlarına ek olarak tüm post meta değerleri YouTube/Vimeo URL'si için taranıyor; böylece video linki hangi meta anahtarında olursa olsun bulunuyor
• ✅ Gallery API istemci desteği eklendi; bağlı galeriler tekrar migrasyonda bulunup güvenli biçimde güncellenebiliyor
• ✅ Tekil görsel node'larında oluşan iç içe Lexical child dizisi ve uyumsuz caption nesnesi düzeltilerek editör parse hataları giderildi

Version 2.1.1 (2026-06-29)

• ✅ İçerik görselleri artık dosya adından attachment tahmini yapmadan, içerikteki tam URL'nin byte'ları WordPress'ten indirilip ContextHub'a yüklenerek migrate ediliyor; dönen URL/id içeriğe yazılıyor
• ✅ Boyutlu URL'lerin (1-673x420.jpg) alakasız dosyalarla (bg21.jpg, back-11.jpg) eşleşip yanlış görsel gömmesi sorunu giderildi
• ✅ Attachment çözümleme yalnızca tam-yol eşleşmesiyle ve indirme başarısız olursa son çare olarak kullanılıyor; LIKE %ad% tahmini kaldırıldı
• ✅ Medya sekmesindeki "Cache'i Temizle" butonu artık gerçekten çalışıyor; yanlış eşleşmiş kayıtları sıfırlayıp yeniden migrate etmeyi sağlıyor
• ✅ Lazy-load görseller (data-src/data-srcset), figcaption, link target/rel ve medya id'leri Lexical'e doğru taşınıyor
• ✅ İçerik listesinde sayfa başına 20 / 50 / 100 seçeneği eklendi
• ✅ Video post-format desteği: gövdede olmayan (tema meta'sındaki, ör. tagDiv td_post_video) YouTube/Vimeo videoları çıkarılıp ContextHub'a URL videosu olarak kaydediliyor, gövde sonuna video node olarak ekleniyor ve videoUrl / videoMediaId / videoProvider custom field'larına yazılıyor (tanımlar tenant'ta yoksa otomatik oluşturuluyor)

Version 2.0.7 (2026-04-09)

• ✅ old.kesk.org.tr, kesk.org.tr ve www.kesk.org.tr artık aynı internal uploads ailesi olarak ele alınıyor
• ✅ http://www.yeni.http://kesk.org.tr/... gibi bozuk legacy URL'ler, hedef dosya https://old.kesk.org.tr/... üstünde duruyorsa recovery akışında daha güvenli eşleşiyor

Version 2.0.6 (2026-04-09)

• ✅ Medya ekranına sadece DB recovery modu eklendi; mevcut R2 objelerini yeniden upload etmeden görünür hale getirmek için yayınlanmış içerikler taranabiliyor
• ✅ Bozuk legacy URL'ler (http://www.yeni.http://...) normalize edilip old. ve diğer alias host varyantları üzerinden yeniden deneniyor
• ✅ register-existing akışı birden fazla aday kaynak URL ile çalışarak kurtarma eşleşmesini güçlendiriyor

Version 2.0.5 (2026-04-07)

• ✅ Stale içerik recovery sırasında slug/publishAt lookup 404 dönerse artık hata sayılmıyor; güvenli create/update fallback'e devam ediliyor

Version 2.0.4 (2026-04-07)

• ✅ Eski _contexthub_id artık boşa düşmüşse migration gerçek çalışmada Content not found ile kırılmıyor
• ✅ Stale içerik ID tespit edilince plugin ID’yi temizleyip slug ve publishAt üzerinden güvenli hedefi yeniden çözüyor

Version 2.0.3 (2026-04-07)

• ✅ Kategori ekranı artık ContextHub kategorilerini flat modda çekiyor; alt kategoriler de listeleniyor
• ✅ Slug already in use for this tenant durumunda mevcut kategori bulunup eşleştirme sürdürülüyor

Version 2.0.2 (2026-04-07)

• ✅ Duplicate-safe content upsert eklendi
• ✅ Aynı slug için publishAt penceresinde güvenli eşleşme yoksa overwrite engellendi
• ✅ Tenant ID ayarı opsiyonel hale getirildi; tenant token'dan çözülebilir
• ✅ Recovery mode'da mevcut R2 objelerini register-existing ile kaydetme akışı güçlendirildi

Version 1.0.0 (2025-10-21)

• ✨ İlk sürüm
• ✅ Toplu içerik migration
• ✅ Lexical JSON dönüşümü
• ✅ Medya migration
• ✅ Kategori eşleştirme
• ✅ Batch processing
• ✅ Migration log

🤝 Destek

Sorularınız için:

• GitHub Issues
• Email: support@contexthub.com

📄 Lisans

GPL v2 or later

👨‍💻 Geliştirici Notları

Kod Yapısı

contexthub-migrator/
├── contexthub-migrator.php      # Ana plugin dosyası
├── includes/
│   ├── class-api-client.php      # API iletişimi
│   ├── class-content-transformer.php  # HTML → Lexical dönüşümü
│   ├── class-media-migrator.php  # Medya migration
│   ├── class-admin.php           # Admin interface
│   └── class-ajax-handler.php    # AJAX handlers
├── assets/
│   ├── css/
│   │   └── admin.css             # Admin styles
│   └── js/
│       └── admin.js              # Admin scripts
└── README.md

Özelleştirme

Plugin'i özelleştirmek için:

1. Yeni HTML elementi desteği eklemek: includes/class-content-transformer.php → parse_node() metodunu güncelleyin

2. API endpoint'lerini değiştirmek: includes/class-api-client.php → İlgili metodları güncelleyin

3. UI değişiklikleri: includes/class-admin.php → Render metodlarını güncelleyin assets/css/admin.css → Stilleri düzenleyin

Hooks

Plugin, özelleştirme için hooklar sunar:

// Migration öncesi
add_action('contexthub_before_migrate_post', function($post_id, $post) {
    // Custom logic
}, 10, 2);

// Migration sonrası
add_action('contexthub_after_migrate_post', function($post_id, $contexthub_id) {
    // Custom logic
}, 10, 2);

// Content data'yı filtrele
add_filter('contexthub_content_data', function($data, $post) {
    // Modify data
    return $data;
}, 10, 2);

🎉 Başarılı Migration!

Plugin'i kullandığınız için teşekkürler. İyi migration'lar! 🚀