Magento 2 Özel Plugin (Interceptor) Geliştirme: Kapsamlı ve Detaylı Rehber

Gemini_Generated_Image_3olhke3olhke3olh (3)

admin tarafındanKategoriler: Genel1 yorum

Toplam görüntülenme: 48Günlük görüntülenme: 3

Magento 2, dünyanın en esnek ve güçlü e-ticaret platformlarından biridir. Bu esnekliğin temelinde, geliştiricilerin çekirdek (core) dosyaları değiştirmeden sistemin davranışını özelleştirmesine olanak tanıyan güçlü bir eklenti mimarisi yatar. Bu mimarinin en önemli parçalarından biri “Plugin” (Eklenti) sistemidir.

Plugin’ler, teknik olarak “Interceptor” (Araya Girici) olarak bilinir. Magento’da public olarak tanımlanmış herhangi bir metot çağrılmadan önce, çağrıldıktan sonra veya çağrılma işleminin çevresinde kendi kodumuzu çalıştırmamıza izin vererek, Magento’nun iş mantığını değiştirmemizi sağlarlar.

Bu rehberde, sıfırdan bir Magento 2 modülü içinde özel bir plugin’i nasıl oluşturacağınızı, before, after ve around metodlarını nasıl kullanacağınızı, bu metodların inceliklerini ve en iyi uygulamaları (best practices) kod örnekleriyle detaylı bir şekilde öğreneceksiniz.

Plugin Kullanmanın Avantajları Nelerdir?

Neden doğrudan Magento’nun çekirdek kodunu (vendor/magento altındaki dosyaları) düzenlememelisiniz?

Yükseltme Güvenliği (Upgrade-Proof): Magento’nun çekirdek dosyalarını düzenlerseniz, composer update ile yapacağınız bir sonraki güncellemede tüm değişiklikleriniz ezilerek kaybolacaktır. Plugin’ler kendi modülünüz (app/code/Vendor/Module) içinde yaşadığı için güncellemelerden etkilenmez.
Çakışmaların Yönetimi (Conflict Management): Plugin’ler, di.xml dosyasında tanımlanan sortOrder (sıralama) parametresi sayesinde birbiriyle çakışmadan çalışabilir. Birden fazla modül aynı metodu değiştirmeye çalışsa bile, bu sıralama sayesinde hangi plugin’in önce çalışacağı kontrol edilebilir. Düşük sortOrder değerine sahip plugin’ler önce çalışır.
Temiz Kod Yapısı ve Bakım Kolaylığı: Değişiklikleriniz, ilgili olduğu işlevsellikle mantıksal olarak kendi modülünüz altında gruplanır. Bu, kodun bakımını, okunabilirliğini ve devre dışı bırakılmasını (bin/magento module:disable) son derece kolaylaştırır.
Hedefe Yönelik Değişiklikler: Plugin’ler, sadece belirli bir sınıfın belirli bir metodunu hedefler. Bu, Observer (Gözlemci) sistemine göre çok daha spesifik ve hedefe yönelik değişiklikler yapmanızı sağlar.

Plugin Türleri: Before, After ve Around

Bir metodu özelleştirmek için üç farklı plugin metodumuz vardır:

1. `before` (Önce) Plugin’leri

Orijinal metot çalıştırılmadan hemen önce çalışır.
Ana Kullanım Amacı: Orijinal metoda gönderilen argümanları (parametreleri) değiştirmek veya metot çalışmadan önce bir kayıt (log) işlemi yapmaktır.
İsimlendirme: before + Orijinal Metot Adı (İlk harf büyük). Örn: beforeSave, beforeSetName.
Dönüş Değeri (Return Value): Argümanları değiştirdiyseniz, argümanların yeni değerlerini içeren bir dizi (array) döndürmelisiniz. Değiştirmediyseniz null döndürmelisiniz.

2. `after` (Sonra) Plugin’leri

Orijinal metot çalıştırıldıktan hemen sonra çalışır.
Ana Kullanım Amacı: Orijinal metodun döndürdüğü sonucu (return value) değiştirmek veya metot çalıştıktan sonra bir işlem yapmaktır.
İsimlendirme: after + Orijinal Metot Adı (İlk harf büyük). Örn: afterSave, afterGetName.
Dönüş Değeri: Mutlaka değiştirilmiş sonucu döndürmelidir.

3. `around` (Çevresinde) Plugin’leri

En güçlü ama aynı zamanda en riskli plugin türüdür.
Orijinal metodun çalışmasını tamamen çevreler.
Ana Kullanım Amacı: Orijinal metodun çalışıp çalışmayacağına karar vermek veya metodun hem öncesinde hem de sonrasında işlem yapmak (örn: performans ölçümü).
İsimlendirme: around + Orijinal Metot Adı (İlk harf büyük). Örn: aroundSave, aroundGetName.
RİSKLER: Performans açısından daha yavaştır ve orijinal metodun çağrılmasını ($proceed() fonksiyonu) unutursanız sitenizde ciddi hatalara yol açabilir. Bir işi before veya after ile yapabiliyorsanız, asla around kullanmayın.

Adım Adım Örnek Plugin Geliştirme

Bu rehberde, “Ürün adına [PROMO] etiketi ekleyen” basit ama etkili bir after plugin’i oluşturacağız.

Ön Gereksinim: Bir Modül Oluşturmak

Plugin’ler bir modül içinde yaşamalıdır. app/code/YilmazSoft/CustomPlugin adında bir modül oluşturalım.

1. app/code/YilmazSoft/CustomPlugin/registration.php Bu dosya, modülünüzü Magento’ya kaydeder.

<?php
/**
 * YilmazSoft CustomPlugin
 * Copyright © Yılmaz Soft. All rights reserved.
 */

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'YilmazSoft_CustomPlugin',
    __DIR__
);

<?php
/**
 * YilmazSoft CustomPlugin
 * Copyright © Yılmaz Soft. All rights reserved.
 */

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'YilmazSoft_CustomPlugin',
    __DIR__
);

2. app/code/YilmazSoft/CustomPlugin/etc/module.xml Bu dosya, modülünüzün adını, versiyonunu ve bağımlılıklarını tanımlar.

<?xml version="1.0"?>
<!--
/**
 * YilmazSoft CustomPlugin
 * Copyright © Yılmaz Soft. All rights reserved.
 */
-->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="YilmazSoft_CustomPlugin">
        <sequence>
            <!-- 
            Bu modülün, Katalog modülünden sonra yüklenmesini garanti eder.
            Plugin'imiz Magento_Catalog'a bağımlı olduğu için bu önemlidir.
            -->
            <module name="Magento_Catalog"/>
        </sequence>
    </module>
</config>

<?xml version="1.0"?>
<!--
/**
 * YilmazSoft CustomPlugin
 * Copyright © Yılmaz Soft. All rights reserved.
 */
-->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="YilmazSoft_CustomPlugin">
        <sequence>
            <!-- 
            Bu modülün, Katalog modülünden sonra yüklenmesini garanti eder.
            Plugin'imiz Magento_Catalog'a bağımlı olduğu için bu önemlidir.
            -->
            <module name="Magento_Catalog"/>
        </sequence>
    </module>
</config>

Modülü oluşturduktan sonra, Magento kurulumunuzun kök dizininde şu komutu çalıştırarak modülü aktif edin:

bin/magento setup:upgrade

bin/magento setup:upgrade

Adım 1: Hedef Metodu Belirleme

Amacımız ürün adını değiştirmek. Ürün adını getiren public metot, Magento\Catalog\Model\Product sınıfı içindeki getName() metodudur.

Hedef Sınıf (Type): Magento\Catalog\Model\Product
Hedef Metot: getName()

Adım 2: `di.xml` Dosyasını Oluşturma

Magento’ya hangi sınıfın hangi metoduna müdahale edeceğimizi di.xml (Dependency Injection) dosyası ile bildiririz.

Dosya Yolu: app/code/YilmazSoft/CustomPlugin/etc/di.xml (Plugin’in sadece önyüzde çalışmasını istiyorsanız etc/frontend/di.xml kullanmak daha performanslıdır.)

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Hedef sınıfı (type) belirtiyoruz -->
    <type name="Magento\Catalog\Model\Product">
        <!--
        Plugin'imizi tanımlıyoruz.
        name: Plugin'e verdiğimiz benzersiz bir isim.
        type: Plugin'imizin (PHP sınıfımızın) tam yolu.
        sortOrder: Plugin'lerin çalışma sırası. Düşük numara önce çalışır.
        -->
        <plugin name="YilmazSoft_CustomPlugin_AddPromoToProductName"
                type="YilmazSoft\CustomPlugin\Plugin\Catalog\ProductPlugin"
                sortOrder="10"
                disabled="false"/>
    </type>

</config>

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Hedef sınıfı (type) belirtiyoruz -->
    <type name="Magento\Catalog\Model\Product">
        <!--
        Plugin'imizi tanımlıyoruz.
        name: Plugin'e verdiğimiz benzersiz bir isim.
        type: Plugin'imizin (PHP sınıfımızın) tam yolu.
        sortOrder: Plugin'lerin çalışma sırası. Düşük numara önce çalışır.
        -->
        <plugin name="YilmazSoft_CustomPlugin_AddPromoToProductName"
                type="YilmazSoft\CustomPlugin\Plugin\Catalog\ProductPlugin"
                sortOrder="10"
                disabled="false"/>
    </type>

</config>

Adım 3: Plugin Sınıfını (PHP) Oluşturma

Şimdi di.xml dosyasında belirttiğimiz ProductPlugin sınıfını oluşturalım.

Dosya Yolu: app/code/YilmazSoft/CustomPlugin/Plugin/Catalog/ProductPlugin.php

<?php
/**
 * YilmazSoft CustomPlugin
 * Copyright © Yılmaz Soft. All rights reserved.
 */
namespace YilmazSoft\CustomPlugin\Plugin\Catalog;

// Müdahale edeceğimiz sınıf
use Magento\Catalog\Model\Product;
// Loglama yapmak için
use Psr\Log\LoggerInterface;

class ProductPlugin
{
    /**
     * @var LoggerInterface
     */
    protected $logger;

    /**
     * Constructor (Dependency Injection)
     * @param LoggerInterface $logger
     */
    public function __construct(
        LoggerInterface $logger
    ) {
        $this->logger = $logger;
    }

    /**
     * Örnek: afterGetName
     *
     * Bu metot, Product::getName() metodu çalıştıktan SONRA devreye girer.
     *
     * @param Product $subject Orijinal sınıfın (Product) örneği
     * @param mixed $result Orijinal getName() metodunun döndürdüğü sonuç (ürün adı)
     * @return string Değiştirilmiş sonuç
     */
    public function afterGetName(Product $subject, $result)
    {
        // Orijinal sonuca [PROMO] ekliyoruz
        $modifiedResult = $result . ' [PROMO]';

        // Geliştirme aşamasında loglama yapmak iyi bir pratiktir
        $this->logger->debug('YilmazSoft Plugin çalıştı: ' . $subject->getSku());

        return $modifiedResult;
    }

    /**
     * Örnek: beforeSetName (Referans için)
     *
     * @param Product $subject
     * @param string $name Orijinal metoda gönderilen $name argümanı
     * @return array Değiştirilmiş argümanlar
     */
    public function beforeSetName(Product $subject, $name)
    {
        $modifiedName = 'YılmazSoft-' . $name;
        // Argümanı bir dizi içinde döndürmelisiniz
        return [$modifiedName];
    }

    /**
     * Örnek: aroundGetPrice (Referans için)
     *
     * @param Product $subject
     * @param \Closure $proceed Orijinal getPrice() metodunu temsil eder
     * @return mixed
     */
    public function aroundGetPrice(Product $subject, \Closure $proceed)
    {
        // 1. Orijinal metot ÖNCESİ kod
        // ...

        // 2. Orijinal metodu çalıştırma
        $originalPrice = $proceed(); 

        // 3. Orijinal metot SONRASI kod
        $modifiedPrice = $originalPrice * 1.10; // Fiyata %10 ekle

        return $modifiedPrice;
    }
}

<?php
/**
 * YilmazSoft CustomPlugin
 * Copyright © Yılmaz Soft. All rights reserved.
 */
namespace YilmazSoft\CustomPlugin\Plugin\Catalog;

// Müdahale edeceğimiz sınıf
use Magento\Catalog\Model\Product;
// Loglama yapmak için
use Psr\Log\LoggerInterface;

class ProductPlugin
{
    /**
     * @var LoggerInterface
     */
    protected $logger;

    /**
     * Constructor (Dependency Injection)
     * @param LoggerInterface $logger
     */
    public function __construct(
        LoggerInterface $logger
    ) {
        $this->logger = $logger;
    }

    /**
     * Örnek: afterGetName
     *
     * Bu metot, Product::getName() metodu çalıştıktan SONRA devreye girer.
     *
     * @param Product $subject Orijinal sınıfın (Product) örneği
     * @param mixed $result Orijinal getName() metodunun döndürdüğü sonuç (ürün adı)
     * @return string Değiştirilmiş sonuç
     */
    public function afterGetName(Product $subject, $result)
    {
        // Orijinal sonuca [PROMO] ekliyoruz
        $modifiedResult = $result . ' [PROMO]';

        // Geliştirme aşamasında loglama yapmak iyi bir pratiktir
        $this->logger->debug('YilmazSoft Plugin çalıştı: ' . $subject->getSku());

        return $modifiedResult;
    }

    /**
     * Örnek: beforeSetName (Referans için)
     *
     * @param Product $subject
     * @param string $name Orijinal metoda gönderilen $name argümanı
     * @return array Değiştirilmiş argümanlar
     */
    public function beforeSetName(Product $subject, $name)
    {
        $modifiedName = 'YılmazSoft-' . $name;
        // Argümanı bir dizi içinde döndürmelisiniz
        return [$modifiedName];
    }

    /**
     * Örnek: aroundGetPrice (Referans için)
     *
     * @param Product $subject
     * @param \Closure $proceed Orijinal getPrice() metodunu temsil eder
     * @return mixed
     */
    public function aroundGetPrice(Product $subject, \Closure $proceed)
    {
        // 1. Orijinal metot ÖNCESİ kod
        // ...

        // 2. Orijinal metodu çalıştırma
        $originalPrice = $proceed(); 

        // 3. Orijinal metot SONRASI kod
        $modifiedPrice = $originalPrice * 1.10; // Fiyata %10 ekle

        return $modifiedPrice;
    }
}

Adım 4: Değişiklikleri Aktif Etme ve Test

Magento’nun yeni plugin’inizi tanıması için “Dependency Injection” (DI) yapılandırmasını ve önbelleği temizlemeniz gerekir.

# Geliştirici (developer) modundaysanız:
bin/magento cache:clean config full_page
bin/magento cache:flush

# Üretim (production) modundaysanız:
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

# Geliştirici (developer) modundaysanız:
bin/magento cache:clean config full_page
bin/magento cache:flush

# Üretim (production) modundaysanız:
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

Şimdi mağazanızın ön yüzüne gidin. Tüm ürün adlarının sonunda “[PROMO]” eklentisini göreceksiniz!

Plugin Sınırlamaları (Ne Zaman KULLANILAMAZ?)

Plugin’ler her yerde kullanılamazlar:

final olarak işaretlenmiş sınıflar ve metotlar.
private veya protected metotlar (Sadece public metotlarda çalışır).
static metotlar.
__construct (constructor) metodu.

Plugin vs. Observer: Ne Zaman Hangisini Kullanmalı?

Observer (Gözlemci) Kullanın: Belirli bir olay (event) gerçekleştiğinde bir eylem tetiklemek istediğinizde. (Örn: “Sipariş sonrası müşteriye e-posta gönder.”)
Plugin (Eklenti) Kullanın: Belirli bir metodun davranışını (girdisini veya çıktısını) değiştirmek istediğinizde. (Örn: “Sepete ekleme metodunun sonucunu değiştir.”)

Profesyonel Destek ve Gelişmiş Çözümler

Magento 2 geliştirme; plugin’ler, observer’lar, dependency injection ve performans optimizasyonu gibi konularla dolu derin bir okyanustur. Özellikle karmaşık iş mantıkları ve yüksek trafikli siteler söz konusu olduğunda, yapılacak yanlış bir mimari seçim, sitenizin performansını ve güvenliğini ciddi şekilde etkileyebilir.

Eğer siz de e-ticaret siteniz için özel bir işlevselliğe ihtiyaç duyuyor, mevcut bir modülü özelleştirmek istiyor veya Magento 2 altyapısıyla ilgili profesyonel bir desteğe ihtiyaç duyuyorsanız, Yılmaz Soft olarak size yardımcı olmaktan mutluluk duyarız.

Deneyimli ve sertifikalı Magento 2 geliştirici ekibimizle, projenizin ihtiyaçlarına en uygun, performanslı ve yükseltme garantili (upgrade-proof) çözümler sunuyoruz. Daha fazla bilgi almak veya projenizi görüşmek için bizimle iletişime geçmekten çekinmeyin.