PHP ile kaydedilen alan grupları

Bir alan grubu düzenleyicide değil, kodda da yaşayabilir. wpmcf_register_field_group() işlevini bir tanımla çağırırsınız; eklenti grubu ve veritabanı tablosunu sizin için oluşturur (veya günceller). Bu yöntem kendi alanlarını birlikte sunan tema ve eklentiler ile her şeyi Git'te tutan siteler için uygundur.

Tanımları taşımanın diğer yollarından farkı:

Kayıtlı gruplar, gerçek tabloları olan gerçek gruplardır. Tanımlar her istekte okunmaz: kayıtlı küme değiştiğinde bir JSON dosyası gibi içe aktarılır. Değerler, sorgular, REST, kısa kodlar ve bloklar düzenleyici grupları ile aynı şekilde çalışır.

Hızlı başlangıç

<?php
// In your theme's functions.php or in a plugin.
add_action( 'wpmcf/field_groups/register', function () {
    wpmcf_register_field_group( [
        'key'      => 'book_details',
        'label'    => 'Book details',
        'fields'   => [
            [ 'key' => 'subtitle', 'label' => 'Subtitle', 'type' => 'text' ],
            [ 'key' => 'pages',    'label' => 'Pages',    'type' => 'number' ],
        ],
        'location' => [
            [ [ 'param' => 'post_type', 'operator' => 'equal', 'value' => 'post' ] ],
        ],
    ] );
} );

Yönetim panelinde WPM Fields sayfalarından herhangi birini açın. Book details grubu listede PHP rozetiyle görünür ve {prefix}wpmcf_fg_book_details tablosu oluşmuştur. Ardından değerleri her zamanki gibi okuyun:

echo esc_html( wpmcf_get_field( 'book_details', 'subtitle' ) );

İşlevi wpmcf_register_field_group() şuradan çağırabilirsiniz: wpmcf/field_groups/register eylemi (eklenti bunu init üzerinde geç bir noktada bir kez tetikler) ya da daha erken, örneğin doğrudan functions.php içinde: işlev yalnızca tanımı saklar. Aynı nedenle bu eklenti yüklenmeden önce çağırmak da sorun değildir.

İşlev, tanım kabul edilirse true döndürür; false ise yalnızca tanımda hiç key ya da fields listesi yoksa döner. Bu noktada başka hiçbir şey denetlenmez; geri kalan her şey grup içe aktarılırken doğrulanır (bkz. Hatalar).

Tanım biçimi

Bir tanım, field_groups altındaki bir girdiyle, bir dışa aktarma dosyasındaki gibi aynı biçimdedir. Başlamanın en kolay yolu grubu düzenleyicide oluşturmak, dışa aktarmak ve JSON'u PHP dizisine çevirmektir.

wpmcf_register_field_group( [
    'key'         => 'book_details',          // lowercase letters, digits, underscore; cleaned with sanitize_key()
    'label'       => 'Book details',
    'description' => 'Shown under the editor.',
    'fields'      => [
        [
            'key'          => 'subtitle',
            'label'        => 'Subtitle',
            'type'         => 'text',
            'required'     => true,
            'instructions' => 'One short line.',
            'placeholder'  => 'e.g. A story',
            'validation'   => [ 'max_length' => 80 ],
        ],
        [ 'key' => 'pages', 'label' => 'Pages', 'type' => 'number', 'default_value' => '100' ],
        [
            'key'      => 'format',
            'label'    => 'Format',
            'type'     => 'select',
            'settings' => [
                'choices' => [
                    [ 'value' => 'hc', 'label' => 'Hardcover' ],
                    [ 'value' => 'pb', 'label' => 'Paperback' ],
                ],
            ],
        ],
        [ 'key' => 'in_print', 'label' => 'In print', 'type' => 'true_false' ],
        [
            'key'        => 'chapters',
            'label'      => 'Chapters',
            'type'       => 'repeater',
            'sub_fields' => [
                [ 'key' => 'name',  'label' => 'Name',  'type' => 'text' ],
                [ 'key' => 'words', 'label' => 'Words', 'type' => 'number' ],
            ],
        ],
        [
            'key'         => 'translated_title',
            'label'       => 'Title',
            'type'        => 'text',
            'translation' => 'copy',          // WPML / Polylang mode, Business plan only
        ],
    ],
    // Outer list = OR, inner list = AND. 'operator' is 'equal' or 'not_equal'.
    'location'    => [
        [
            [ 'param' => 'post_type',   'operator' => 'equal', 'value' => 'post' ],
            [ 'param' => 'post_status', 'operator' => 'equal', 'value' => 'publish' ],
        ],
        [
            [ 'param' => 'post_type', 'operator' => 'equal', 'value' => 'page' ],
        ],
    ],
    'settings'    => [
        'style'                 => 'wpmcf',     // wpmcf | standard | seamless
        'position'              => 'side',      // high | normal | side
        'label_placement'       => 'left',      // top | left
        'instruction_placement' => 'label',     // label | field
        'order'                 => 5,
        'active'                => true,
        'rest'                  => true,        // Show in the REST API
        'graphql'               => true,        // Show in GraphQL
        'meta_bridge'           => true,        // Bridge get_post_meta() / update_post_meta()
        'searchable'            => true,        // Include in site search
    ],
] );

İsteğe bağlı olanlar:

• label, description, settings, location: atlanan değerler varsayılanları alır (ayar varsayılanları Grup ayarları bölümündekilerdir). Hiç location tanımlanmamış bir grup oluşturulur ama hiçbir yerde gösterilmez. label eksikse etiket boş olur, bu yüzden her zaman bir etiket belirleyin.
• Bir alanın type değeri varsayılan olarak text olur; bilinmeyen türler hatadır. Bir alanın settings, validation, conditional_logic, display, sql_column, default_value, indexed değerleri alan seçeneklerini izler.
• created_at ve updated_at yok sayılır.
• Anahtarlar düzenleyicinin kurallarına uymalıdır: grup anahtarı küçük harf, rakam ve alt çizgiden oluşur, harfle başlar ve en fazla 63 karakterdir. Alan anahtarı harfle başlamalı, küçük harf, rakam ve alt çizgi kullanmalı (en fazla 63) ve ayrılmış bir SQL sözcüğü olmamalıdır. sub-title, 1st veya when gibi anahtarlar grubun içe aktarılmasını başarısız kılar. Hatalı karakterler içeren bir grup anahtarı temizlenir (Bad Key! değeri badkey olur); bu yüzden her zaman temiz biçimi yazın.
• Düzenleyicideki sınırlar burada da geçerlidir: planınızda bulunmayan gelişmiş bir alan türü, içe aktarmayı the field type is not included in your plan hatasıyla başarısız kılar ve Password alanları alt alan olamaz.

Alan uid'leri: veri kaybetmeden yeniden adlandırma

Her alanın bir uid değeri vardır; eklenti, yeniden adlandırılan bir alanı bununla tanır. Tanımınızdaki bir alanın uid değeri yoksa, tanımdaki konumundan türetilir:

uid = "php-" + first 16 hex characters of md5( "{group_key}.{field_key}" )

Alt alanlar yolu uzatır ({group_key}.{field_key}.{sub_key}). Türetilen uid her istekte aynıdır, dolayısıyla bir tanım her zaman aynı sütunlara eşlenir. Bunun sonucu olarak, bir alanın key değerini uid olmadan değiştirmek yeni, boş bir sütun oluşturur: eski sütun kaldırılmış bir alanın sütunu sayılır ve verilerini korur, yeniden adlandırılmaz (bkz. Kaldırılan bir alanı yeniden eklemek).

Bir alanı yeniden adlandırıp değerlerini korumak için alana uid en baştan açıkça verin (veya yeniden adlandırma anında alanın zaten sahip olduğu uid'i kullanın) ve yalnızca anahtarı değiştirin:

// Version 1
[ 'key' => 'subtitle',  'uid' => 'book-subtitle', 'label' => 'Subtitle', 'type' => 'text' ],

// Version 2: same uid, new key. The column is renamed and the values move with it.
[ 'key' => 'sub_title', 'uid' => 'book-subtitle', 'label' => 'Subtitle', 'type' => 'text' ],

(Doğrulandı: title2 altında kaydedilen değer, yeniden adlandırmadan sonra yeni headline anahtarı altında, aynı uid sayesinde okunabildi.)

Uid vermediğiniz bir alanın uid'ini, grubu dışa aktararak (WPM Fields › Tools) ya da wp wpmcf export --items=field_groups:book_details ile okuyarak bulabilirsiniz. Uid, boş olmayan herhangi bir dizgedir; okunabilir ve başka bir alan için kullanmayacağınız bir değer seçin.

Kaldırılan bir alanı yeniden eklemek

Bir alanı koddan kaldırmak veriyi asla silmez: sütunu artık sütun olarak kalır. Daha sonra aynı anahtarla bir alanı yeniden kaydederseniz (örneğin bir anahtarı değiştirip geri aldıktan sonra ya da yanlışlıkla kaldırmanın ardından), eşitleme başarısız olmak yerine eski değerleri otomatik olarak geri alır. Kod eşitlemesi, düzenleyicinin "eski veriyle ne yapılsın?" sorusunu "geri al" diye yanıtlar. (Doğrulandı: pages = 12, alan kaldırıldı, yeniden eklendi: hâlâ 12; başka adla değiştirilip geri alındı: hâlâ 12.)

Veri içeren bir gruptaki alanları kaldırmadan veya yeniden adlandırmadan önce Bir alan grubunu güvenle değiştirme bölümünü okuyun.

Grubun oluşturulması veya güncellenmesi

Eklenti çalıştığı her istekte, init üzerinde geç bir noktada (öncelik 99) şu adımları uygular:

1. Tanımları toplar (wpmcf/field_groups/register eylemi bir kez çalışır).
2. Tüm tanımların ve eklenti sürümünün özetini (hash) hesaplar.
3. Özet, son eşitlemenin sakladığı özetle aynıysa durur. Veritabanına hiçbir şey dokunmaz (hata bildiren bir eşitleme yeniden denenir, bkz. Hatalar).
4. Farklıysa hemen eşitler veya bir arka plan işi zamanlar:

Yani yeni kodu dağıttıktan sonra herhangi bir wp-admin sayfasını ilk açan yönetici (veya Action Scheduler'ın sonraki çalışması) tabloları günceller. Bunu bilinçli olarak yapmak için, örneğin bir dağıtım betiğinde:

wp wpmcf code sync

İçe aktarma, JSON içe aktarmanın Replace existing definitions açıkken kullandığı işlemin aynısıdır: tablo olağan güvenlik kurallarıyla değiştirilir, veri asla silinmez ve grup Yerel JSON dosyalarına yansıtılmaz, çünkü kaynağı koddur.

Bundan çıkan sonuçlar:

• Her istekte aynı kümeyi kaydedin. Grupları yalnızca ön yüzde, yalnızca yönetim panelinde ya da kullanıcıya bağlı olarak kaydederseniz özet istekler arasında değişir ve eklenti sürekli ileri geri eşitleme yapar. Koşulsuz kaydedin.
• Kaydı şundan önce veya şunun üzerinde yapın: wpmcf/field_groups/register. Aynı istekte daha sonra eklenen bir tanım (örneğin wp_loaded üzerinde) o isteğin özetine dahil olmaz; gözden kaçar ya da istekler arasında özetin değişmesine yol açar.
• Eklentiyi güncellemek özeti değiştirir (sürüm özetin parçasıdır), bu yüzden güncellemeden sonra kayıtlı her grup bir kez daha içe aktarılır.
• Her eşitleme kayıtlı her grubu değiştirir, bu yüzden hiçbir şey değişmese bile wp wpmcf code sync komutu N updated bildirir. Bu normaldir.
• Bir yönetici veya WP-CLI isteği değişiklikleri zaten eşitledikten sonra çalıştırılan wp wpmcf code sync komutu 0 created, N updated gösterir (gruplar zaten mevcuttur).

Düzenleyicide

Koddan gelen bir grup göründüğü her yerde işaretlenir:

• Alan grupları (Field Groups) listesinde PHP rozeti bulunur.
• Grubu açtığınızda Registered in PHP başlıklı bir bilgi notu görünür: This field group comes from code that calls wpmcf_register_field_group(). Change it there; edits made here cannot be saved.
• Düzenleme formundaki Save changes düğmesi devre dışıdır, bu yüzden formda yaptığınız hiçbir değişiklik kaydedilemez (form yine de gösterilir). REST API üzerinden gruba yapılan PUT ve DELETE istekleri şu yanıtı döndürür: 409 durumu ve wpmcf_managed_by_code kodu, ileti: This field group is registered in PHP code. Change it in the code that registers it. GET isteği ise şunu gösterir: "managed_by": "php".
• Aynı anahtarla REST API üzerinden grup oluşturmak başarısız olur (422, anahtar zaten kullanımda).

Böyle bir grubun değerleri diğer gruplarınki gibi düzenlenir: düzenleme ekranlarında, wpmcf_update_field() ile, REST üzerinden vb.

Grubu değiştirmenin diğer yolları da reddedilir. JSON içe aktarma (Replace existing definitions açık olsa bile), Yerel JSON eşitlemesi ve REST API, kodun sahip olduğu bir grubun üzerine yazamaz; öğe This field group is registered in PHP code. Change it in the code that registers it. hatasıyla başarısız olur (JSON içe aktarma için doğrulandı; Yerel JSON aynı içe aktarma yolunu kullanır ve ayrıca test edilmedi). Grubu yalnızca kodun kendi eşitlemesi değiştirebilir.

Düzenleyicide oluşturulmuş bir grupla çakışma

Aynı anahtarlı bir grup zaten varsa ve koddan oluşturulmadıysa (düzenleyicide siz oluşturduysanız veya içe aktardıysanız), kod tanımı uygulanmaz ve mevcut grup olduğu gibi bırakılır. Eşitleme şunu bildirir:

book_details: a field group with this key was created in the editor; rename one of them.

Koddaki anahtarı yeniden adlandırın (veya düzenleyicideki grubu silin); sonraki eşitleme tanımı uygular.

Hatalar

İçe aktarılamayan bir grup (bilinmeyen alan türü, bilinmeyen konum parametresi, izin verilmeyen alan anahtarı, plan kısıtlaması, sütun çakışması) atlanır; diğer gruplar eşitlenmeye devam eder.

• Kırmızı bir uyarı, WPM Fields ekranlarında manage_options yetkisine sahip kullanıcılara görünür: Some field groups registered in PHP could not be created or updated. They are retried on the next admin page load. Ardından iletiler, her satırda bir tane olacak şekilde gelir; örneğin book_details: Field "x": the field type "nope" does not exist. veya book_details: Unknown location parameter "bogus".
• Sorun ayrıca Settings › Health altında portability.code modülü için kaydedilir.
• Başarısız eşitleme, başarılı olana kadar her yönetici isteğinde yeniden denenir (ziyaretçiler aynı başarısız işi bir daha kuyruğa almaz).
• Başarısız olan grup son geçerli tanımını korur; tablosuna dokunulmaz.

Bir grubu koddan kaldırma

Bir grubu kaydetmeyi bıraktığınızda sonraki eşitleme onu serbest bırakır:

• Grup, tablosu ve tüm veriler kalır.
• Grup artık PHP rozeti taşımaz ve düzenleyici grupları gibi düzenlenebilir hâle gelir.
• Hiçbir şey silinmez. Silmek için düzenleyicide Delete field group seçeneğini kullanın.

Eklenti hangi grupları serbest bıraktığını hatırlar. Daha sonra aynı anahtarı yeniden kaydederseniz grup geri alınır: yeniden kod tarafından yönetilir (PHP rozeti, salt okunur) ve sonraki eşitleme tanımı uygular (doğrulandı). Düzenleyicide oluşturulmuş ve hiçbir zaman koddan gelmemiş aynı anahtarlı bir grup ise yine çakışma olarak bildirilir (yukarıda).

WP-CLI

wp wpmcf code list
wp wpmcf code sync

Her iki komut da WP-CLI komutları bölümünde açıklanmıştır. Yalnızca WP-CLI'ın WordPress'i yüklediği ortamlarda çalışırlar.

Hook'lar

Sınırlamalar

• Bir tanım çalışma zamanında okunmaz, içe aktarılır. Değişiklik yalnızca bir eşitlemeden sonra geçerli olur (yukarıya bakın); çok büyük bir tabloda veritabanı değişikliği arka planda çalışır.
• Bu yolla yalnızca alan grupları kaydedilebilir. Yazı türleri, taksonomiler ve seçenek sayfaları eklentide veya JSON içe aktarma ile yönetilir.
• Kayıtlı gruplar düzenleyicide kaydedilemez veya silinemez (REST API 409 yanıtı verir) ve içe aktarmalar bunların üzerine yazamaz.
• Bir alanı koddan kaldırmak sütununu ve verisini korur (anahtarı yeniden eklemek veriyi geri getirir).
• Her eşitleme, hiçbir şey değişmese bile kayıtlı her grubu güncellenmiş sayar.