Composer ile Magento 2 Eklenti Kurulumu: Adım Adım Rehber
Composer ile Magento 2 eklenti kurulumu için pratik bir rehber: özel depolar, auth.json, setup:upgrade, production modu adımları, güncellemeler, kaldırma ve sık karşılaşılan…

Bu yazıda
Composer ile Magento 2 eklenti kurulumu için tedarikçinin deposunu (özel bir depoysa kimlik bilgileriyle birlikte) eklersiniz, composer require komutunu çalıştırırsınız, modülü etkinleştirirsiniz, bin/magento setup:upgrade komutunu çalıştırırsınız, mağaza production modundaysa derleme yapıp statik içeriği deploy edersiniz ve önbelleği temizlersiniz. Yalnızca birkaç komut; ancak sıralama ve deploy modu önemlidir.
Bu rehber, ücretsiz Conviro for Magento eklentisini örnek alarak tüm adımları sırasıyla anlatıyor; ardından güncellemeyi, kaldırmayı ve en sık karşılaşacağınız hataları ele alıyor.
Öne çıkanlar
- Her komutu yedek aldıktan sonra, Magento kök dizininden ve dosya sistemi sahibi kullanıcıyla çalıştırın; önce staging ortamında deneyin.
- Developer modunda setup:upgrade ve önbellek temizliği yeterlidir; production modunda ayrıca derleme ve statik içerik deploy'u gerekir.
- Kaldırma işlemini ters sırayla yapın: önce entegrasyonu temizleyin, ardından devre dışı bırakın, kaldırın ve upgrade çalıştırın.
Başlamadan önce: Ön koşullar
Canlı ortama dokunmadan önce şunları kontrol edin:
- Sunucuda SSH erişimi ve Composer. Composer tabanlı bir kurulum yönetici panelinden yapılamaz.
- Kodun ve veritabanının güncel bir yedeği ve tercihen test için bir staging kopyası.
- Doğru kullanıcı. Komutları root olarak değil, dosya sistemi sahibi kullanıcıyla çalıştırın; aksi halde izin sorunları yaratırsınız.
- Deploy modunuz.
bin/magento deploy:mode:showile kontrol edin. - Canlı ortam için bir bakım penceresi: öncesinde
bin/magento maintenance:enable, sonrasındabin/magento maintenance:disable.
Conviro eklentisi için ayrıca Magento Open Source 2.4.4 veya üzeri ile PHP 7.4 ya da 8.1–8.4, HTTPS kullanan bir mağaza URL'si, çalışan bir Magento cron'u ve api.conviro.io adresine giden (outbound) HTTPS bağlantısı gerekir. Eklentinin (bu yazı yazıldığı sırada 1.4.1 sürümü) kurulum testi şu ortamlarda yapıldı:
| Magento | PHP | Tema |
|---|---|---|
| 2.4.4-p13 | 8.1 | Luma |
| 2.4.7-p4 | 8.3 | Luma |
| 2.4.9 | 8.4 | Luma ve Hyvä 1.5.2 |
Adobe Commerce aynı framework üzerinde çalışır ancak henüz test edilmedi; Hyvä Checkout test edilmedi ve 2.4.0–2.4.3 kullanan mağazalar eklentinin 1.3.5 sürümünde kalır.
Composer ile Magento 2 eklenti kurulumu adım adım nasıl yapılır?
1. adım: Composer deposunu ve kimlik bilgilerini ekleyin
Özel (private) eklentiler, tedarikçinin kendi Composer deposundan sunulur. Magento kök dizininde:
composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <CONVIRO_API_KEY>
İlk komut depoyu composer.json dosyasına ekler. İkincisi kimlik bilgilerini hemen yanındaki auth.json dosyasına kaydeder. Conviro için kullanıcı adı api, parola ise Conviro panelindeki Developers → API Keys bölümünden alınan bir API anahtarıdır. Conviro'nun API'si hakkında daha fazla bilgi geliştiriciler sayfasında yer alıyor.
auth.json dosyasını sürüm kontrolünün dışında tutun. repo.magento.com anahtarlarınız da genellikle aynı dosyada bulunur.
2. adım: composer require ve setup:upgrade komutlarını çalıştırın
composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade
Bu üç komut, her Magento 2 modül kurulumunun temelidir:
composer requirepaketivendor/dizinine indirir vecomposer.jsonilecomposer.lockdosyalarına kaydeder. Her ortamın aynı sürümü kurması için iki dosyayı da commit'leyin.module:enablemodülüapp/etc/config.phpdosyasına kaydeder.setup:upgrademodülün veritabanı şeması ve veri yamalarını (data patch) uygular ve modül kaydını günceller.
3. adım: Derleyin, deploy edin ve önbelleği temizleyin
Production modunda üretilen kod ve statik dosyalar talep anında oluşturulmaz; bu nedenle şunları çalıştırın:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
Developer modunda ikisini de atlayın. Her iki modda da şu komutla bitirin:
bin/magento cache:flush
Ardından modülün etkin olduğunu doğrulayın ve bakım modundan çıkın:
bin/magento module:status Conviro_AiChat
bin/magento maintenance:disable
4. adım: Eklentiyi yönetici panelinden bağlayın
Çoğu eklenti kurulumdan sonra yapılandırma gerektirir. Conviro için Stores › Settings › Conviro Setup sayfasını açın. 7 adımlı bir sihirbaz ortam kontrolü yapar; ardından Connect to Conviro'ya tıklar, mağazayı Conviro panelinde onaylar ve Magento'ya geri dönersiniz. Magento'ya hiçbir API anahtarı veya token kopyalanmaz.
Sihirbaz en az yetkiyle çalışan bir Magento entegrasyonu (OAuth 1.0a) oluşturur; mağaza görünümlerini, neyin senkronize edileceğini ve hangi yapay zekâ işlemlerine izin verileceğini seçmenizi sağlar ve her şeyi bir test olayıyla doğrular. Sonrasında Stores › Configuration › Conviro › AI Chat altındaki Integration Health kartı bağlantıyı, kimlik doğrulamayı, webhook'ları, kataloğu, siparişleri, cron'u, sürümü ve ortamı kontrol eder ve düzeltme talimatları verir. Her adım kurulum sayfasında ve kurulum dokümantasyonunda anlatılıyor. Bağlantı için API erişimi olan bir Conviro planı, yani Pro veya üzeri bir plan gerekir (fiyatlandırma sayfasına bakın).
Magento 2 modülünü güncelleme ve kaldırma
Güncelleme
composer update conviro/module-aichat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
Önceki gibi, derleme ve deploy adımlarını yalnızca production modunda çalıştırın. Yeni bir sürüm yayımlandığında Magento yönetici paneli tam komutu içeren bir bildirim gösterir; yapılandırmanız, API anahtarınız ve entegrasyonunuz korunur.
Kaldırma
Sıralama önemlidir: Bağlantıyı kesme işlemi kurulum sihirbazında yapılır ve modül kaldırıldığında sihirbaz da ortadan kalkar.
- Conviro kurulum sihirbazında bağlantıyı kesin.
- Modülü devre dışı bırakın:
bin/magento module:disable Conviro_AiChat - Paketi kaldırın:
composer remove conviro/module-aichat bin/magento setup:upgradekomutunu çalıştırın.
Production modunda her zamanki gibi yeniden derleyin, statik içeriği yeniden deploy edin ve önbelleği temizleyin. Conviro, mağazanın verilerini bağlantı kesildikten 30 gün sonra, isterseniz hemen siler. Tüm adımlar kaldırma dokümantasyonunda listelenir.
Sık karşılaşılan hatalar ve çözümleri
| Belirti | Olası neden | Çözüm |
|---|---|---|
| Composer sırasında "Allowed memory size exhausted" | PHP bellek sınırı | COMPOSER_MEMORY_LIMIT=-1 composer require ... komutunu çalıştırın |
| Derleme sırasında bellek yetmiyor | CLI bellek sınırı | php -d memory_limit=2G bin/magento setup:di:compile komutunu çalıştırın |
| Depodan 401 hatası veya kimlik bilgisi istemi | Yanlış anahtar veya kullanıcı adı | http-basic komutunu yeniden çalıştırın; kullanıcı adı api |
generated/, var/ veya pub/static/ içinde "Permission denied" |
Komutlar root olarak veya yanlış kullanıcıyla çalıştırılmış | Dosya sahipliğini düzeltin, ardından dosya sistemi sahibi kullanıcıyla yeniden çalıştırın |
| "Please upgrade your database" | setup:upgrade çalıştırılmamış | bin/magento setup:upgrade komutunu çalıştırın |
| Veri senkronizasyonu duruyor, sağlık kartı cron'u işaretliyor | Cron çalışmıyor | bin/magento cron:install komutunu çalıştırın ve crontab -l ile kontrol edin |
Cron göründüğünden daha önemlidir. Conviro; ödeme, müşteri kaydı ve ürün kaydetme olaylarını, Magento cron'unun arka planda ilettiği yerel bir kuyruğa yazar. Eklenti ayrıca mağaza sayfaları Conviro'yu PHP'den çağırmayacak ve Conviro'ya ulaşılamasa bile siparişler işlenmeye devam edecek şekilde tasarlandı. Tüm akışı önce staging ortamında test edin; kurulumdan sonra yapay zekâ chatbot test kontrol listemiz işinize yarayacaktır.
Sıkça Sorulan Sorular
Developer modunda setup:di:compile çalıştırmam gerekir mi?
Hayır. Developer modu kodu talep anında üretir; bu yüzden bir modül kurduktan sonra setup:upgrade ve cache:flush yeterlidir. Production modunda setup:di:compile ve setup:static-content:deploy komutlarını da çalıştırın; aksi halde üretilen kod ve statik dosyalar eksik olacağından mağaza vitrini ve yönetici paneli bozulabilir.
Composer, özel bir deponun kimlik bilgilerini nerede saklar?
composer config http-basic.<host> <user> <password> komutu bunları proje kök dizininizde, composer.json dosyasının yanındaki auth.json dosyasına yazar. Bunun yerine kullanıcınızın Composer home dizininde saklamak için --global ekleyin. Her iki durumda da anahtarların sızmaması için auth.json dosyasını sürüm kontrolünün dışında tutun.
Magento 2 modülünün etkin olup olmadığı nasıl kontrol edilir?
Etkin ve devre dışı modülleri listelemek için bin/magento module:status komutunu çalıştırın ya da modül adını ekleyin; örneğin bin/magento module:status Conviro_AiChat. Modül devre dışı olarak listeleniyorsa module:enable, ardından setup:upgrade ve önbellek temizliği çalıştırın.
SSH erişimi olmadan Magento eklentisi kurulabilir mi?
Composer ile kurulamaz. Conviro eklentisi, sunucuda SSH veya CLI erişimi ve Composer gerektirir. Barındırma sağlayıcınız bunları sunmuyorsa kurulumu hosting firmanızdan veya ajansınızdan isteyin. Enterprise planında eklentiyi Conviro ekibi ek ücret almadan kurar.
Sonraki adımlar
Kurulumu staging ortamında yapın, kurulum sihirbazını tamamlayın ve canlı ortamda tekrarlamadan önce Integration Health kartını kontrol edin. Eklentinin bağlandıktan sonra neler yaptığını ayrıntılı görmek için Magento 2 yapay zekâ chat eklentisine genel bakış yazımızı okuyun. Bağlanmaya hazır mısınız? Conviro hesabınızı oluşturun.
Yayınlayan
Conviro
Yapay zekâ destekli müşteri desteği, chatbot otomasyonu ve SaaS büyüme stratejileri hakkında içgörüler paylaşıyoruz.
Conviro ile geliştirin
Konuşma iş akışlarını teknoloji altyapınıza bağlayın
Uygulamayı tasarlamadan önce geliştirici kaynaklarını ve entegrasyon kalıplarını inceleyin.


