# Modül Yapılandırması

https://dev.wisecp.com/tr/modul-yapilandirmasi

Operatörün değiştirebileceği ayarlar: modülle gelen dizi, forma dönüşen alan tanımları ve yanıtları kaydeden yazma.

## Genel Bakış

Bir modülün yapılandırması, bir dizi döndüren tek bir PHP dosyasıdır. Hem varsayılanları hem operatörün yanıtlarını tutar, çünkü kaydetmek aynı dosyayı yeniden yazar. Ayar tablosu da göç adımı da yoktur: durum dosyanın kendisidir.

Buradaki hataların çoğu dosyanın iki özelliğinden doğar: derlenir ve okunabilir kaynaktır.

## Ön Koşullar

- Zaten yüklenen bir modül. Yoksa [İlk Modülünüz](https://dev.wisecp.com/tr/ilk-modulunuz) ile başlayın.
- Web sunucusu kullanıcısının modül dizininde yazma izni; bu olmadan her kayıt dosya katmanında sessizce düşer.
- Bir form alanının adı nasıl istek anahtarına dönüşür; [Admin Form Oluşturucu](https://dev.wisecp.com/tr/admin-form-olusturucu).

## Yapı

### Dosyanın Biçimi

Üst düzey, platformun okuduğu bir avuç anahtar dışında sizindir; o anahtarlar birebir yazılmak zorundadır.

| Anahtar | Kim okur | Ne taşır |
| --- | --- | --- |
| `meta.name` | Modül listesi | Dil dosyasında ad yoksa kullanılan görünen ad |
| `meta.version` | Siz ve güncelleme düzeneği | Kendi sürüm dizeniz |
| `meta.logo` | Logo çözümlemesi | Modül dizinindeki bir dosya adı ya da mutlak bir adres |
| `settings` | Kodunuz ve ayar kaydetme yolu | Operatörün yanıtları; bildirilen her alan kendi anahtarıyla buraya iner |
| `status` | Duruma göre süzülen yüklemelerde kayıt defteri | Modülün etkin olup olmadığı; bunu burada tutan dört tip için |
| `fields` | Sunucu modülleri, ürün ve hizmet ekranlarında | Ürün yapılandırma formunda görünen alan tanımları |
| `access_ps` | Eklenti ayarları ekranı | Ayarlarla birlikte kaydedilen yetki seçimi |
| `show_on_adminArea`, `show_on_clientArea` | Eklenti sayfa yönlendiricisi | Eklentinin panel sayfası mı, müşteri sayfası mı, ikisi mi açacağı |

```php
return [
    'meta' => [
        'name'    => 'AcmeDomains',
        'version' => '1.0',
        'logo'    => 'logo.png',
    ],

    // Kodunuzun okuduğu her anahtarı güvenli bir varsayılanla gönderin. Yalnız ilk kayıttan
    // sonra beliren bir anahtar, kodunuzun her okumada korumak zorunda olduğu anahtardır.
    'settings' => [
        'username'      => '',
        'apiKey'        => '',
        'test-mode'     => 0,
        'nameservers'   => ['ns1.example.com', 'ns2.example.com'],
        'cost-currency' => 4,
    ],
];
```

### Ayar Alanlarını Bildirme

Formu siz yazmazsınız: bir tanım dizisi döndürürsünüz, admin form oluşturucu onu forma çevirir. Dizi anahtarı alan adı, içindeki `name` ise etikettir — en sık ters karıştırılan çift budur.

Hangi metodu bildireceğiniz ve size bir şey geçilip geçilmeyeceği tipe bağlıdır.

| Tip | Bildirdiğiniz metot | Ekranın geçtiği şey | Saklanan değerin kaynağı |
| --- | --- | --- | --- |
| Registrars | `config_fields($settings = [])` | Geçerli yapılandırmanın settings bloğu | Argüman |
| Payment | `config_fields()` | Hiçbir şey | `$this->config['settings']` |
| Addons | `fields()` | Hiçbir şey | `$this->config['settings']` |

```php
// Servis sağlayıcı formu. Ekran bunu saklanan ayar bloğuyla çağırır, yani
// $data doludur. Ödeme geçidinde ya da eklentide aynı metot ARGÜMANSIZ çağrılır
// ve $data sessizce boş kalır: orada özelliği okuyun.
public function config_fields($data = []): array
{
    return [
        // ANAHTAR alan adıdır. 'name' ise ETİKETTİR.
        'username' => [
            'name'        => $this->lang['username'] ?? 'Username',
            'description' => $this->lang['username-desc'] ?? '',
            'type'        => 'text',
            'value'       => $data['username'] ?? '',
            'placeholder' => 'api-user',
        ],

        'apiKey' => [
            'name'  => $this->lang['api-key'] ?? 'API Key',
            'type'  => 'password',
            'value' => $data['apiKey'] ?? '',
        ],

        // Onay kutusu. 'checked' mevcut durumdur, gönderilen değer değil.
        'test-mode' => [
            'name'    => $this->lang['test-mode'] ?? 'Test Mode',
            'type'    => 'approval',
            'checked' => (bool) ($data['test-mode'] ?? false),
        ],

        // Yalnız yukarıdaki kutu işaretliyken gösterilir.
        'test-endpoint' => [
            'name'         => $this->lang['test-endpoint'] ?? 'Test Endpoint',
            'type'         => 'text',
            'value'        => $data['test-endpoint'] ?? '',
            'parent'       => 'test-mode',
            'parentEffect' => 'hide',
        ],

        'mode' => [
            'name'    => $this->lang['mode'] ?? 'Mode',
            'type'    => 'dropdown',
            'value'   => $data['mode'] ?? 'live',
            'options' => ['live' => 'Live', 'sandbox' => 'Sandbox'],
        ],
    ];
}
```

## Adım Adım

### Varsayılanları Gönderin

1. `config.php` dosyasını bir `meta` ve bir `settings` bloğu döndürecek şekilde oluşturun.
2. Kodunuzun okuduğu her anahtarı, boş ya da zararsız bir varsayılanla `settings` içine koyun. Oraya asla gerçek kimlik bilgisi yazmayın.
3. Modül listesini yenileyin; ayar ekranının artık gösterecek bir şeyi vardır.

### Formu Bildirin

1. Sınıfınıza `config_fields($data = [])`, eklentide `fields()` ekleyin.
2. Ayar başına bir tanım döndürün, ayar adıyla anahtarlayın ve mevcut değeri tipinizin sunduğu kaynaktan okuyun.
3. Modülün ayar sayfasını açın. Genel şablon metodunuzu bulur ve formu oluşturur; gönder butonu ile eylem adresi zaten bağlıdır.
4. Bir değer değiştirip kaydedin. Yanıtlar tek istek anahtarında, `fields` içinde, alan adlarınızla gelir.

### Geri Yazın

1. Gönderilen değerleri yüklü diziyle birleştirin, yerine koymayın: yazma tam dosya yazmasıdır, düşürdüğünüz her şey gider.
2. Sırları girerken şifreleyin ve alan maskeli ya da boş geldiğinde saklanan değeri koruyun.
3. Derlenmiş kopyayı geçersiz kılan dosya yöneticisi üzerinden yazın.
4. Sayfayı yenileyin. Eski değeri geri okuyorsanız yazma gerçekleşmiş ama derlenmiş kopya yenilenmemiştir.

## Referans

### Dosyayı Yazma

```php
// Ortak trait; sunucu, servis sağlayıcı, ürün ve sosyal giriş modüllerinin kullandığı.
// $auto_status = true, dizi boş olmayan bir ayar bloğu taşıdığında modülü açar.
protected function save_config($data = [], $auto_status = true);

// Sunucu modülleri bunu daraltır: otomatik durum bayrağı yok, dönüş kesin boolean.
public function save_config($data = []): bool;

// Eklentiler de aynı şekilde daraltır ve ayrıca diziyi $this->config değerine atar.
public function save_config($data = []): bool;

// Hepsinin altta çağırdığı şey. Hedef .php ise derlenmiş kopyayı geçersiz kılar.
public static function file_write($file, $data = null, $mode = 'w', $flags = 0);

// Diziden kaynak koda. ['pwith' => true] onu eksiksiz bir PHP dosyası olarak sarar.
public static function array_export($array = [], $options = []);

// Platform yapılandırması, modül yapılandırması değil. Yapılandırma dizinindeki
// dosyalara eğik çizgili yollarla erişilir.
public static function get($arg = null);
public static function set($key, $values, $merge = false): array|false;
public static function save($name = '', $data = []): bool;

// Veritabanında tutulan ayarlar, ada göre anahtarlanmış. Modülün admin alanı
// kendi dosyası yerine bunları kullanır.
public static function getd($name = '');
public static function setd($name = '', $content = '');
```

### Alan Tanımı Anahtarları

- **type**: Şunlardan biri: `text` (varsayılan), `password`, `textarea`, `dropdown`, `radio`, `switch`, `approval`, `file`, `output` ve `javascript`. Bir output alanı serbest işaretleme gösterir, kaydedilmez.
- **name**: Alanın yanında gösterilen etiket. Alan adı değildir: o, dizi anahtarıdır.
- **value**: Metin benzeri ve açılır alanlarda mevcut değer, anahtarda (switch) gönderilen değer. Onay kutuları durumu `checked` ile taşır.
- **options**: Açılır liste ya da radyo grubu için `değer => etiket` haritası. Virgülle ayrılmış bir dize, anahtarı etiketine eşit bir haritaya açılır.
- **description · description_pos · is_tooltip**: Yardım metni; varsayılan olarak sağda, `'L'` ile etiketin yanında. `is_tooltip` ile bir soru işareti simgesine büzülür.
- **parent · parentEffect · parentValue**: Bu alanı bir başkasına göre göster ya da devre dışı bırak. Etki `hide`, `disable` ya da `collapse`; radyo ebeveynde `parentValue` hangi seçeneklerin onu açtığını sayar. Ebeveyn çocuktan önce bildirilmelidir.
- **width · wrap_width**: Girdinin kendisi ve satırı için yüzdeler. Yüz olan bir satır genişliği tanımsız sayılır.
- **advanced_selector · multiple · rows · disabled**: Aranabilir açılır liste, çok değerli alan, metin kutusunun yüksekliği ve değiştirilemez alan. Aranabilir açılır liste, seçeneklerini sizin metotlarınızdan yükleyebilir.
- **fieldOptions · rowOptions**: O alan ve satırı için doğrudan form oluşturucuya geçer; tanımın karşılığı olmayan öznitelikler için kaçış kapısı.

## Örnek

Turun tamamı: gelen, yazılan ve geri okunan. Kaydetme yarısı, birleştirme görünsün diye ayar controller'ını geçersiz kılar.

```php
public function controller_settings($extraFields = []): array
{
    // Formun gönderdiği her şey, tek anahtar altında, sizin tanım anahtarlarınızın adıyla.
    $fields = \Filter::POST("fields") ?: [];

    // Diskte zaten duranla başlayın: aşağıdaki yazma dosyanın tamamını değiştirir.
    $config = $this->config;

    $config['settings']['username']  = \Filter::html_clear((string) ($fields['username'] ?? ''));
    $config['settings']['mode']      = in_array($fields['mode'] ?? '', ['live', 'sandbox'], true)
        ? $fields['mode'] : 'live';

    // İşaretsiz bir kutu gönderide HİÇ YOKTUR, yani yokluk "kapalı" değeridir.
    $config['settings']['test-mode'] = (int) ($fields['test-mode'] ?? 0) === 1 ? 1 : 0;

    // Sırlar: girerken şifreleyin ve alan maskeli ya da boş geldiğinde saklanan değeri
    // koruyun; ekran değişmemiş bir sır için tam olarak bunu gönderir.
    $posted = (string) ($fields['apiKey'] ?? '');
    if ($posted !== '' && !str_starts_with($posted, '*'))
        $config['settings']['apiKey'] = $this->encode_str($posted);

    // Tam dosya yazması; derlenmiş kopyayı geçersiz kılan yönetici üzerinden.
    \FileManager::file_write($this->dir . 'config.php', \Utility::array_export($config, ['pwith' => true]));

    return ['status' => "successful", 'message' => \Language::gc("admin/ac-settings/successful1")];
}
```

```php
private function credentials(): array
{
    $settings = $this->config['settings'] ?? [];

    return [
        // Her okumada null güvenli: modülünüzün eski bir sürümünden yükseltilmiş
        // bir sistemde anahtar eksik olabilir.
        'username' => (string) ($settings['username'] ?? ''),
        'apiKey'   => $this->decode_str((string) ($settings['apiKey'] ?? '')),
        'sandbox'  => (int) ($settings['test-mode'] ?? 0) === 1,
    ];
}
```

Ve aynı değerlerin modülü hiç kurmadan okunması; bir listeleme ekranının ya da bir kancanın yaptığı şey budur:

```php
// Config() yalnız statik önbelleği okur, bu yüzden önce yükleme yapılmalıdır.
// Üçüncü argüman sınıf dosyasını işin dışında tutar.
$record = Modules::Load("Registrars", "AcmeDomains", true);

$mode = $record["config"]["settings"]["mode"] ?? 'live';

// Sır buradan okunamaz: çözme, örnek üzerindeki bir metottur.
// Açık değere ihtiyacınız varsa modülü kurun ve ona sorun.
```

## Tuzaklar

> **Yapılandırma dosyası derlenmiş PHP'dir**
> 
> Geri okuması bir include iledir; derlenmiş kopya geçersiz kılınana kadar servis edilir. Dosya yöneticisi bunu yapar, ham yazma ya da yeniden adlandırma yapmaz. Operatör kaydeder, yeniler, eski değeri görür; hiçbir kayıt açıklamaz.

> **Kaydetmek dosyanın tamamını değiştirir**
> 
> Yeni diziyi yüklü olandan kurun, kendi anahtarlarınızı değiştirin, gerisine dokunmayın. Yalnız ayar bloğunu geçmek künyeyi, durumu ve her şeyi tek kayıtta siler.

> **Gönderilmemiş bir alan false olarak yazılabilir**
> 
> Eklenti ayar yolu bildirdiğiniz alanları gezer ve gönderide olmayan her biri için `false` saklar. İşaretsiz bir kutu hiçbir şey göndermez: bu, onay kutuları için doğru, koşullu gösterilen her şey için yanlıştır. Bildirdiğiniz alanları elle yazılmış listeden değil, okuduğunuz kaynaktan türetin.

> **Sırları şifreleyin ve asla elle yapıştırmayın**
> 
> Bir API anahtarı diziye modülün kendi yardımcısıyla şifreli girmelidir; böylece bu sisteme bağlı alt anahtar kullanılır. Doğrudan dosyaya yazılan değer çözülemez ve çöp okunur; onu ayar ekranından girin.

> **Modül yapılandırması ile platform yapılandırması ayrı şeylerdir**
> 
> Modül dosyası sizindir ve modülle taşınır. Platform dosyaları sistem geneli ayarları tutar; tek seçimli her tipin etkin modülü de oradadır. Bir modül yalnız kendi dosyasına yazar, platform dosyalarını okur.

## İlgili Makaleler

- [Modül Anatomisi](https://dev.wisecp.com/tr/modul-anatomisi)
- [Modül Dil Dosyaları](https://dev.wisecp.com/tr/modul-dil-dosyalari)
- [Yapılandırma Okuma ve Yazma](https://dev.wisecp.com/tr/yapilandirma-okuma-ve-yazma)
- [Admin Form Oluşturucu](https://dev.wisecp.com/tr/admin-form-olusturucu)
- [Modül Yaşam Döngüsü](https://dev.wisecp.com/tr/modul-yasam-dongusu)
- [Kullanıcı Girdisini Filtreleme](https://dev.wisecp.com/tr/kullanici-girdisini-filtreleme)