WHMCS Promotion::appliesToService Hatası Çözümü | Orphan Service Fix & Kupon Problemleri Rehberi

WHMCS’te kupon veya promosyon uygularken karşınıza çıkan `Promotion::appliesToService(): Argument #1 ($serviceId) must be of type int, null given` hatası, sistemin hizmet kimliğini okuyamadığını gösterir. WHMCS, promosyonu bir hizmete bağlamaya çalışırken ortada geçerli bir hizmet kaydı bulamaz.

Bu hata çoğunlukla veritabanındaki yetim (orphan) hizmet kayıtlarından, silinmiş ürünlere bağlı kalan kuponlardan veya üçüncü parti modüllerin eksik parametre göndermesinden kaynaklanır. Aşağıda hatanın kök nedenlerini nasıl tespit edeceğinizi, arayüz ve SQL ile nasıl düzelteceğinizi ve tekrar yaşanmaması için hangi önlemleri almanız gerektiğini bulacaksınız.

Hatanın Teknik Nedeni

`Promotion::appliesToService()` metodu, bir promosyonun belirli bir hizmete uygulanıp uygulanamayacağını kontrol eder. Bu metodun ilk parametresi olan `$serviceId`, integer türünde bir hizmet kimliği bekler. Çağrı sırasında bu değer `null` olarak gelirse PHP, tür uyuşmazlığı nedeniyle `TypeError` fırlatır.

WHMCS’in normal akışında her hizmet kaydının `tblhosting` tablosunda benzersiz bir `id` değeri vardır. Promosyon motoru bu kimliği kullanarak hizmetin hangi ürüne bağlı olduğunu, hangi fatura döneminde olduğunu ve kuponun koşullarını karşılayıp karşılamadığını değerlendirir. Kimlik null olduğunda bu değerlendirme zinciri daha ilk adımda kırılır.

Sorunun kaynağı nadiren WHMCS çekirdeğindedir. Çoğu durumda veritabanındaki tutarsız kayıtlar veya yanlış yapılandırılmış promosyonlar bu hatayı üretir. Çözüme geçmeden önce hatayı hangi senaryonun tetiklediğini anlamak gerekir.

Hatayı Tetikleyen Senaryolar

1. Orphan (Ürünsüz) Hizmetler

Orphan hizmet, `tblhosting` tablosunda kaydı bulunan ancak geçerli bir ürüne bağlı olmayan hizmettir. Bu durum genellikle şu şekilde oluşur: bir ürünü WHMCS arayüzünden silersiniz, ancak o ürüne bağlı hizmet kayıtları veritabanında kalmaya devam eder. `packageid` alanı artık var olmayan bir ürünü işaret eder veya tamamen boş kalır.

Müşteri böyle bir hizmete kupon uygulamaya çalıştığında WHMCS, hizmetin ürün bilgisini çözemez ve promosyon motoruna null kimlik iletir. Sonuç, doğrudan bu TypeError hatasıdır.

2. Kuponun “Applies To” Listesinde Geçersiz Ürünler

WHMCS’te bir promosyon oluştururken kuponun hangi ürünlere uygulanacağını seçersiniz. Seçili ürünlerden biri daha sonra silinirse, kuponun hedef listesi geçersiz bir referans içerir. Kupon çalıştırıldığında WHMCS bu geçersiz referansı çözmeye çalışır ve hizmet kimliğini null olarak alır.

Bu senaryo özellikle sezonluk kampanyalar veya geçici ürünler için oluşturulan kuponlarda sık görülür. Kampanya bittikten sonra ürün silinir, ancak kupon aktif kalmaya devam eder.

3. Üçüncü Parti Modül ve Eklentiler

Sipariş akışını, fatura oluşturmayı veya hizmet yönetimini özelleştiren modüller bazen `Promotion::appliesToService()` metodunu eksik parametreyle çağırabilir. Modül geliştiricisi, hizmet kimliğini doğru şekilde aktarmadığında veya hizmet henüz oluşturulmadan promosyon kontrolü yaptığında bu hata ortaya çıkar.

Özellikle özel sipariş formları, harici ödeme entegrasyonları ve toplu hizmet taşıma araçları bu tür sorunlara yol açabilir. Modülü geçici olarak devre dışı bırakıp hatanın devam edip etmediğini gözlemlemek, kaynağı daraltmanın etkili bir yoludur.

4. Bozulmuş Veritabanı İlişkileri

Nadir durumlarda, başarısız bir yükseltme veya manuel veritabanı müdahalesi sonucu `tblhosting` ile `tblproducts` arasındaki ilişki bozulabilir. Yabancı anahtar kısıtlamaları WHMCS’in bazı sürümlerinde tam olarak uygulanmadığı için bu tür tutarsızlıklar sessizce birikebilir.

Belirtiler

Bu hatayı yalnızca loglarda değil, arayüzde de fark edebilirsiniz. Belirtiler hatanın hangi noktada tetiklendiğine göre değişir:

• Müşteri panelinde hata mesajı: Müşteri, hizmet detay sayfasını açtığında veya kupon uygulamaya çalıştığında TypeError mesajıyla karşılaşır.
• Kupon uygulanamıyor: Geçerli görünen bir kupon, belirli hizmetlere uygulandığında sessizce başarısız olur veya hata döndürür.
• Fatura oluşturmada sorun: Cron job fatura oluşturmaya çalışırken hata loguna TypeError kaydı düşer ve fatura üretilemez.
• Ödeme sonrası hata: Müşteri ödemeyi tamamladıktan sonra hizmet aktifleştirme adımında hata oluşur.
• Yönetici panelinde yavaşlama: Hatalı kayıtların çokluğu, hizmet listesi sorgularını yavaşlatabilir.

Bu belirtilerden birini görüyorsanız, aşağıdaki teşhis adımlarını sırayla uygulayın. Sorunu erken tespit etmek, müşteri şikayetlerinin önüne geçmenizi sağlar.

Teşhis (Diagnostik) Adımları

1) Orphan Hizmetleri Bulma

Veritabanınıza erişerek aşağıdaki sorguyu çalıştırın. Bu sorgu, hiçbir ürüne bağlı olmayan veya silinmiş bir ürünü işaret eden tüm hizmet kayıtlarını listeler:

SELECT id, userid, packageid, domain, domainstatus
FROM tblhosting
WHERE packageid IS NULL
   OR packageid NOT IN (SELECT id FROM tblproducts);

Sorgu sonucunda dönen her satır, promosyon motorunun null kimlik almasına neden olabilecek potansiyel bir sorun kaynağıdır. Sonuçlardaki `domainstatus` alanına dikkat edin; “Active” durumundaki kayıtlar öncelikli olarak düzeltilmelidir çünkü bunlar müşterinin aktif olarak kullandığı hizmetlerdir.

2) Promosyon Ayarlarını İnceleme

WHMCS yönetici panelinde Configuration → System Settings → Promotions yolunu izleyin. Şüpheli kuponu açın ve “Applies To” bölümünü kontrol edin. Burada seçili ürünlerin hâlâ mevcut olup olmadığını doğrulayın.

Silinmiş bir ürün seçiliyse, kupon düzenleme sayfasında bu ürün genellikle eksik veya bozuk bir etiketle görünür. Kuponu kaydetmeden önce geçersiz ürünleri listeden çıkarın ve yalnızca aktif ürünleri seçin.

3) Log Kontrolü

Utilities → Logs → Activity Log bölümünden hatanın tam olarak hangi işlem sırasında oluştuğunu inceleyin. Log kaydındaki zaman damgası, hatayı tetikleyen müşteri kimliği ve işlem türü (örneğin kupon uygulama, fatura oluşturma) size önemli ipuçları verir.

Ayrıca PHP error log’unu da kontrol edin. TypeError mesajının tam stack trace’i, hatanın hangi modülden veya dosyadan kaynaklandığını gösterir. Stack trace içinde üçüncü parti bir modülün dosya yolu görünüyorsa, sorunun kaynağı büyük olasılıkla o modüldür.

4) Üçüncü Parti Modülleri Test Etme

Yakın zamanda bir modül yüklediyseniz veya güncellediyseniz, modülü geçici olarak devre dışı bırakıp hatanın tekrar oluşup oluşmadığını gözlemleyin. Hata kayboluyorsa, modülün geliştiricisiyle iletişime geçin veya alternatif bir çözüm arayın.

Modülleri devre dışı bırakırken canlı sipariş akışını etkilememek için bakım penceresi planlamak akıllıca olur. Test sırasında bir test müşterisiyle kupon uygulamayı deneyerek hatayı güvenle yeniden üretebilirsiniz.

Çözüm Yöntemleri

Yöntem A — WHMCS Arayüzü ile Onarım (Önerilen)

Bu yöntem, teknik bilgisi sınırlı kullanıcılar için en güvenli yoldur. Veritabanına doğrudan müdahale gerektirmez ve her adımı geri alınabilir.

1. Orphan hizmetleri düzeltin: Clients → Services sayfasında, teşhis sorgusunda bulduğunuz hizmet kayıtlarını açın. Her kaydı doğru ürüne bağlayın veya kayıt artık kullanılmıyorsa silin.
2. Promosyonu güncelleyin: Configuration → System Settings → Promotions altında ilgili kuponu açın. “Applies To” listesinden geçersiz ürünleri çıkarın ve değişiklikleri kaydedin.
3. Önbelleği temizleyin: Utilities → System → System Cleanup altından önbelleği temizleyin. Bu adım, eski verilerin hâlâ bellekte tutulmasını önler.
4. Test edin: Test müşterisiyle kuponu yeniden uygulayın. Hata mesajının kaybolduğunu ve kuponun doğru şekilde çalıştığını doğrulayın.

Yöntem B — SQL ile Toplu Düzeltme (İleri Seviye)

Orphan hizmet sayısı fazlaysa ve hepsinin aynı ürüne bağlanması gerektiğinden eminseniz, SQL ile toplu güncelleme yapabilirsiniz. Ancak bu yöntem geri alınması zor hatalara yol açabilir.

UPDATE tblhosting
SET packageid = 123
WHERE packageid IS NULL
   OR packageid NOT IN (SELECT id FROM tblproducts);

Sorgudaki `123` değerini, bu hizmetlerin bağlanmasını istediğiniz gerçek ürün kimliğiyle değiştirin. Hangi ürünün doğru olduğundan emin değilseniz, önce `tblproducts` tablosundan aktif ürünleri listeleyin:

SELECT id, name, type
FROM tblproducts
WHERE hidden = 0
ORDER BY name;

Yöntem C — Kuponu Yeniden Oluşturma

Kupon ayarlarındaki geçersiz referansları temizlemek zor geliyorsa, en pratik çözüm kuponu sıfırdan oluşturmaktır. Eski kuponu devre dışı bırakın, aynı koşullarla yeni bir kupon oluşturun ve yalnızca mevcut ürünleri hedefleyin.

Bu yöntem özellikle çok sayıda geçersiz referans içeren veya uzun süredir kullanılan kuponlarda etkilidir. Yeni kuponun kodunu müşterilerinize duyurmayı unutmayın; eski kupon kodunu kullanan müşteriler hata almaya devam edebilir.

Yöntem D — Üçüncü Parti Modülü Güncelleme veya Kaldırma

Teşhis adımında sorunun kaynağını bir modül olarak belirlediyseniz, öncelikle modülün güncel bir sürümünün olup olmadığını kontrol edin. Geliştiriciler bu tür hataları genellikle sonraki sürümlerde düzeltir.

Güncelleme yoksa veya sorun devam ediyorsa, modülü kaldırıp yerine WHMCS’in yerleşik özellikleriyle aynı işlevi sağlayan bir alternatif arayın. Modülü kaldırmadan önce, modülün oluşturduğu verilerin yedeğini almayı ihmal etmeyin.

Önleyici Tedbirler

Bu hatayı bir kez çözdükten sonra tekrar yaşamamak için şu alışkanlıkları edinin:

• Günlük veritabanı yedeği alın: Otomatik yedekleme planı oluşturun ve yedeklerin geri yüklenebilir olduğunu düzenli olarak test edin.
• WHMCS’i güncel tutun: Her güncellemeden önce sürüm notlarını okuyun ve yedek alın. Güncellemeler genellikle bu tür tutarsızlıkları önleyen veritabanı düzeltmeleri içerir.
• Ürün silmeden önce bağımlılıkları kontrol edin: Bir ürünü silmeden önce, o ürüne bağlı hizmet sayısını sorgulayın. Bağlı hizmet varsa önce bunları başka bir ürüne taşıyın veya hizmetleri sonlandırın.
• Kuponları düzenli denetleyin: Aktif kuponların “Applies To” listelerini periyodik olarak gözden geçirin. Geçersiz ürünleri temizleyin.
• Cron ve logları izleyin: Haftalık olarak Activity Log ve PHP error log’unu tarayın. TypeError hatalarını erken yakalamak, müşteri etkilenmeden müdahale etmenizi sağlar.
• Test ortamı kullanın: Büyük değişiklikleri canlı ortamda yapmadan önce staging ortamında deneyin.

Düzenli bakım rutininin parçası olarak orphan hizmet sorgusunu ayda bir çalıştırmak, sorunun sessizce büyümesini engeller. Sorgu sonucunda yeni kayıtlar beliriyorsa, bunların neden oluştuğunu araştırın; yalnızca semptomu değil, kök nedeni de çözün.

WHMCS barındıran sunucunuzun kaynak yetersizliği de benzer hatalara yol açabilir. Eğer hata loglarında yalnızca yoğun saatlerde bu TypeError görünüyorsa, linux hosting altyapınızın PHP bellek limiti ve veritabanı bağlantı havuzu ayarlarını gözden geçirin.

Sıkça Sorulan Sorular

WHMCS’te orphan hizmet kaydı nedir?

Orphan hizmet, `tblhosting` tablosunda kaydı bulunan ancak geçerli bir ürüne (`tblproducts`) bağlı olmayan hizmettir. Genellikle bir ürün silindiğinde, o ürüne bağlı hizmet kayıtlarının veritabanında kalmasıyla oluşur.

Bu hatayı düzeltmek için veritabanına doğrudan müdahale şart mı?

Hayır. Orphan hizmet sayısı azsa, WHMCS arayüzünden her hizmeti doğru ürüne bağlayarak sorunu çözebilirsiniz. SQL yalnızca çok sayıda kaydın toplu düzeltilmesi gerektiğinde kullanılmalıdır.

Kuponu sildikten sonra hata devam ederse ne yapmalıyım?

Hata devam ediyorsa sorun kuponda değil, hizmet kayıtlarındadır. Orphan hizmet sorgusunu yeniden çalıştırın ve tüm sonuçları düzelttiğinizden emin olun. Ayrıca üçüncü parti modülleri geçici olarak devre dışı bırakıp test edin.

Orphan hizmetleri silmek yerine neden düzeltmeliyim?

Orphan hizmetler genellikle müşterinin geçmiş fatura ve hizmet kayıtlarını içerir. Silmek, müşterinin geçmiş verilerini kaybetmesine neden olabilir. Hizmet hâlâ aktifse doğru ürüne bağlamak, faturalamanın kesintisiz devam etmesini sağlar.

Bu hata WHMCS’in hangi sürümlerinde görülür?

Hata, PHP 7 ve üzeri sürümlerle çalışan WHMCS sürümlerinde, özellikle tip güvenliği artırılmış sürümlerde daha sık rapor edilir. Sürümden bağımsız olarak orphan hizmet ve geçersiz promosyon hedefleri her sürümde soruna yol açabilir.