Šema konfiguracije/metapodaci

Drupal 8 uključuje podršku za jezik šeme/metapodataka koji je napravljen pomoću Kwalify (http://www.kuwata-lab.com/kwalify/) za YAML konfiguracione fajlove. Sam Kwalify je napisan u Ruby-ju, i bile su potrebne male prilagodbe formata, tako da svi detalji Kwalify-ja nisu direktno primenjivi, ali je prilično blizu.

Špargalica

Za brzo razumevanje i neke korisne primere, pogledajte ovu špargalicu, a zatim nastavite sa čitanjem ako još imate pitanja:

/sites/default/files/config-schema-cheat-sheet1.5.pdf

Uvodni primer

Sistemski modul ima dva parametra konfiguracije vezana za režim održavanja (bez obzira na to da li je sajt u offline režimu za regularne posetioce):

<?php
$config = \Drupal::config('system.maintenance');
$message = $config->get('message');
$langcode = $config->get('langcode');
?>

(Da li je održavanje uključeno, čuva se u state sistemu, a ne u konfiguraciji.)

Podrazumevane vrednosti za ovaj konfiguracioni objekat nalaze se u fajlu core/modules/system/config/install/system.maintenance.yml u obliku:

message: '@site is currently under maintenance. We should be back shortly. Thank you for your patience.'
langcode: en

Svaki modul može imati onoliko konfiguracionih objekata koliko mu treba. Sve to se opisuje u jednom ili više fajlova šema koje dolaze sa modulom. U slučaju sistemskog modula, fajlovi se nalaze u core/modules/system/config/schema. Odgovarajući deo šeme iz fajla system.schema.yml izgleda ovako:

system.maintenance:
  type: config_object
  label: 'Maintenance mode'
  mapping:
    message:
      type: text
      label: 'Message to display when in maintenance mode'

Gornji ključ ("system.maintenance") u fajlu se odnosi na osnovno ime .yml fajla ("system.maintenance.yml") i na ime konfiguracionog objekta (config('system.maintenance')). Ugnježdeni nivoi opisuju šta se nalazi u fajlu. Konfiguraciona šema definiše dva tipa konfiguracionih fajlova: config_object za globalne konfiguracione fajlove i config_entity za entitete. Tip config_object je definisan u core.data_types.schema.yml na sledeći način:

# Root of a configuration object.

_core_config_info:
  type: mapping
  mapping:
    default_config_hash:
      type: string
      label: 'Default configuration hash'

config_object:
  type: mapping
  mapping:
    langcode:
      type: string
      label: 'Language code'
    _core:
      type: _core_config_info

Mapiranje tipova je osnovni tip za parove ključ-vrednost. Koristeći tip config_object, definicija režima održavanja ponovo koristi ključeve langcode i _core i dodaje još jedan ključ za samu poruku. Vraćajući se na definiciju system.maintenance, labela šeme 'Maintenance mode' opisuje sadržaj šeme. Zatim se stvarni elementi navode pod ključem mapping gde je definisan ključ message, nasleđujući langcode i _core od osnovnog tipa. Svaki element ima tip i ključ label, koji opisuju tip podataka i daju opis podataka. Labela je obično ista ili slična labeli konfiguracione forme gde vrednost može biti uređena od strane sistemskog administratora.

U svim slučajevima podržanim od strane jezgra, gornji nivo elementa u .yml fajlu je mapiranje sa elementima opisanim u listi mapiranja ispod. Trebalo bi da koristite bilo koji od dva definisana podtipa mapiranja: config_object ili config_entity. Pojedinačni elementi u mapiranju mogu biti bilo kog tipa u zavisnosti od toga kako ste definisali podatke. Sam ključ _core i svi ključevi unutar _core su rezervisani za Drupal jezgro.

Čemu služe fajlovi šema?

1. Glavna svrha fajlova šema je omogućiti podršku za više jezika. Potreban nam je alat da identifikujemo sve prevedive stringove u isporučenoj konfiguraciji, tako da kada pošaljete svoje sopstvene postavke, kao i podrazumevane prikaze, dodatne korisničke uloge, stavke menija itd., možemo ih ponuditi za prevod kao deo vašeg modula/teme na https://localize.drupal.org. Za ovu upotrebu dovoljni su nivoi i tipovi ugnježdenja.

2. Takođe koristimo šeme da bismo pružili prave prevodilačke forme zasnovane na vašim podacima. U ovom slučaju, tipovi dobijaju veći značaj, a labela postaje presudna. Modul za prevod osnovne konfiguracije koristi šeme da kreira prevodilačke forme i čuva prevode. Dva najvažnija ugrađena tipa koja se prevode su 'label' za unos jedne linije teksta i 'text' za unos više linija teksta.

3. Koristeći informacije ugrađene u konfiguracione šeme o tome šta je smešteno u konfiguracionom objektu, podrazumevana implementacija perzistencije za konfiguracione objekte zahteva konfiguracionu šemu za konfiguracioni objekat kako bi se osiguralo pravilno eksportovanje svojstava sa odgovarajućim tipovima. Iako je najbolje da obezbedite konfiguracione šeme, ako zaista ne želite, implementirajte metodu toArray() u svojoj konfiguracionoj entiteti da ne biste morali da zahtevate šemu da biste sačuvali konfiguracione entitete svog tipa.

4. Konfiguraciona šema se takođe koristi za automatsko vezivanje vrednosti za očekivane tipove. To osigurava da, iako PHP i web forme uopšte preferiraju stringove nad ostalim tipovima, kada se konfiguracija čuva, koriste se odgovarajući tipovi. Ovo je važno da bi se prilikom implementacije konfiguracije u diff prikazivale samo stvarne promene, a ne slučajne promene tipa.

5. U PHPUnit svi izvedeni TestBase testovi podrazumevano strogo poštuju konfiguracionu šemu. Ovo će dovesti do grešaka šeme ako šema fajl nedostaje ili je nevalidan. Iako se to ne preporučuje, može se preskočiti podešavanjem u vašem testu:

protected $strictConfigSchema = FALSE;

Pogledajte https://drupal.org/project/config_inspector za modul koji pomaže u debugovanju vaših šema. Modul pomaže da se pronađu nedostajuće šeme i elementi šema sa različitim prikazima vaših podataka i šema.

Postoje i druge ideje za šeme koje moduli mogu pružiti, npr. kreiranje web servisnih interfejsa baziranih na nekima od njih. Verovatno postoje i druge upotrebe o kojima ljudi tek treba da saznaju, o kojima čak nismo ni razmišljali.

Svojstva

• type: tip vrednosti; može biti osnovni ili izvedeni tip (vidi primere ispod).
• label: UI labela za vrednost. Labela ne mora nužno biti ista kao odgovarajuća labela u konfiguracionoj formi, ali podudaranje labela poboljšava jasnoću.
• translatable: označava da li se određeni tip prevodi; Napomena: možete koristiti

type: label

kao skraćenicu za:

type: string
translatable: true

• nullable: da li vrednost može biti prazna; ako nije postavljeno, koristi se podrazumevano.
• class: koristi se samo za osnovne tipove da bi se odredila klasa koja implementira parsiranje (primeri ispod su za TypedData i konfiguracione tipove definisane u sistemu).
• Tip-specifična svojstva:

          - mapping: svojstvo za vrednost tipa mapping, koje se koristi za mapiranje osnovnih elemenata unutar mapiranja. Ključevi i tipovi vrednosti u mapiranju moraju biti opisani u šemi. Dozvoljeni su samo string ključevi u mapiranjima.
          - sequence: svojstvo za vrednost tipa sequence, koje se koristi za navođenje osnovnih elemenata u sekvenci. Ključevi mogu biti ceo broj ili stringovi, oni nisu značajni.

Tipovi podržani u fajlovima metapodataka

Kao što je pomenuto, najosnovniji tipovi i neki interesantni složeniji tipovi definisani su u core.data_types.schema.yml.

# Undefined type used by the system to assign to elements at any level where
# configuration schema is not defined. Using explicitly has the same effect as
# not defining schema, so there is no point in doing that.
undefined:
  label: 'Undefined'
  class: '\Drupal\Core\Config\Schema\Undefined'

# Explicit type to use when no data typing is possible. Instead of using this
# type, we strongly suggest you use configuration structures that can be
# described with other structural elements of schema, and describe your schema
# with those elements.
ignore:
  label: 'Ignore'
  class: '\Drupal\Core\Config\Schema\Ignore'

# Basic scalar data types from typed data.
boolean:
  label: 'Boolean'
  class: '\Drupal\Core\TypedData\Plugin\DataType\BooleanData'
email:
  label: 'Email'
  class: '\Drupal\Core\TypedData\Plugin\DataType\Email'
integer:
  label: 'Integer'
  class: '\Drupal\Core\TypedData\Plugin\DataType\IntegerData'
float:
  label: 'Float'
  class: '\Drupal\Core\TypedData\Plugin\DataType\FloatData'
string:
  label: 'String'
  class: '\Drupal\Core\TypedData\Plugin\DataType\StringData'
uri:
  label: 'Uri'
  class: '\Drupal\Core\TypedData\Plugin\DataType\Uri'

Kao što se vidi, većina osnovnih tipova podataka mapirana je na njihove ekvivalente u TypedData API-ju. Ovaj primer takođe pokazuje koliko je lako definisati sopstvene tipove. Jednostavno definišete klasu koja odgovara tipu. Dva preostala (složenija) tipa podataka su definisana na osnovu implementacija klasa:

# Container data types for lists with known and unknown keys.
mapping:
  label: Mapping
  class: '\Drupal\Core\Config\Schema\Mapping'
  definition_class: '\Drupal\Core\TypedData\MapDataDefinition'
sequence:
  label: Sequence
  class: '\Drupal\Core\Config\Schema\Sequence'
  definition_class: '\Drupal\Core\TypedData\ListDataDefinition'

Mapiranje, kao što je gore prikazano, predstavlja tip liste parova ključ-vrednost („asocijativni niz“ ili „heš“), gde svaki element može imati različit tip, dok je Sequence jednostavan indeksirani spisak („indeksirani niz“) gde su elementi svi istog tipa ili zasnovani na istom imenu dinamičkog tipa (vidi dole) i ključevi nisu bitni. Drugim rečima, ključna razlika između sekvenci i mapiranja je što sekvence ne poznaju imena ključeva i broj ključeva, dok mapiranja eksplicitno definišu sve ključeve. Sekvence mogu koristiti string ključeve.

Svi ostali tipovi definisani u konfiguracionim šemama (uključujući system.maintenance) samo nasleđuju druge tipove, npr. „label“, „path“, „text“, „date_format“ i „color_hex“ su definisani kao stringovi. Razlike ovih tipova mogu pomoći parser alatima da identifikuju tekstualne tipove za različite svrhe.

# Human readable string that must be plain text and editable with a text field.
label:
  type: string
  label: 'Label'
  translatable: true

# Internal Drupal path
path:
  type: string
  label: 'Path'

# Human readable string that can contain multiple lines of text or HTML.
text:
  type: string
  label: 'Text'
  translatable: true

# PHP Date format string that is translatable.
date_format:
  type: string
  label: 'Date format'
  translatable: true
  translation context: 'PHP date format'

# HTML color value.
color_hex:
  type: string
  label: 'Color'

Napomena: tipovi label, text i date_format su takođe označeni kao prevodivi. To znači da modul za prevod osnovnog interfejsa identifikuje elemente sa ovim tipovima i prevodi ih na osnovu prevoda unetih od strane zajednice ili administratora u bazu podataka, praveći fajlove za override prevoda. Obratite pažnju da prevodivi stringovi mogu imati kontekst prevoda, kao što je prikazano ovde za formate datuma. Tako se string tipa „Y“ dodatno kontekstualizuje kao „PHP date format“, da bi prevodioci znali da to nije skraćenica za „Yes“, već format datuma u PHP-u.

Na isti način možete definisati višekratno upotrebljive složene tipove na osnovu osnovnih tipova, koristeći format prikazan gore za režim održavanja:

# Mail text with subject and body parts.
mail:
  type: mapping
  label: 'Mail'
  mapping:
    subject:
      type: label
      label: 'Subject'
    body:
      type: text
      label: 'Body'

Ovo vam daje višekratno upotrebljivi tip „mail“ za tekstualne email postavke, gde su tema i telo predstavljeni kao mapiranje. Ovo je isto što i definicija šeme za konfiguracioni ključ, ali ste izabrali ime koje nije postojeći konfiguracioni ključ, tako da neće biti sukoba sa drugim definicijama šema. Na osnovu ove definicije „mail“ može biti korišćen kao tip na drugom mestu (kao u korisničkom modulu email podešavanja šeme u user.schema.yml):

user.mail:
 type: config_object
 label: 'Email settings'
 mapping:
  cancel_confirm:
    type: mail
    label: 'Account cancellation confirmation'
  password_reset:
    type: mail
    label: 'Password recovery'
  [....]

Na kraju, još dva važna složena tipa za definisanje konfiguracionih fajlova su definisana ovde u core.data_types.schema.yml:

config_object:
  type: mapping
  mapping:
    langcode:
      type: string
      label: 'Language code'
    _core:
      type: _core_config_info

config_entity:
  type: mapping
  mapping:
    uuid:
      type: string
      label: 'UUID'
    langcode:
      type: string
      label: 'Language code'
    status:
      type: boolean
      label: 'Status'
    dependencies:
      type: config_dependencies
      label: 'Dependencies'
    third_party_settings:
      type: sequence
      label: 'Third party settings'
      sequence:
        type: '[%parent.%parent.%type].third_party.[%key]'
    _core:
      type: _core_config_info

Dinamičke reference na tip

Kao što je prikazano gore, čak i osnovni tipovi su u suštini reference, a složeni tipovi kao što je „mail“ se često koriste za referenciranje složenih tipova. Ponekad tip vrednosti nije statičan i može zavisiti od podataka, npr. za stilove slika kojima se mogu primenjivati različiti efekti, ili prikaze koji se sastoje iz različitih plugina. Možete referencirati ključeve u podacima kao deo imena tipa da biste referencirali dinamičke tipove.

Vrednosti promenljivih u tipovima moraju biti u uglastim zagradama [] i vrednosti promenljivih mogu se kombinovati sa poznatim komponentama. Postoje tri tipa referenci:

1. Referenca na ključ elementa: npr. type:book.[%key], gde se %key zamenjuje ključem elementa.
2. Referenca na ugnježdeni ključ: npr. type: 'views.field.[table]-[field]', gde se tip izračunava na osnovu vrednosti ključeva table i field u ugnježdenoj strukturi.
3. Referenca na roditeljski ključ: npr. type: 'views.display.[%parent.display_plugin]', gde se ključ display_plugin od roditelja koristi za određivanje tipa elementa.

Postoje bogati primeri ovog u stilovima slika i prikazima koji široko koriste plugine. Primer iz stilova slika sa core/modules/image/config/install/image.style.medium.yml koji ima ovu YAML strukturu:

name: medium
label: 'Medium (220x220)'
effects:
  bddf0d06-42f9-4c75-a700-a33cafa25ea0:
    id: image_scale
    data:
      width: 220
      height: 220
      upscale: true
    weight: 0
    uuid: bddf0d06-42f9-4c75-a700-a33cafa25ea0
langcode: en

Ovde struktura ključeva podataka zavisi od tipa efekta, koji je naveden u svojstvu id efekta. Zato tip koji se koristi zavisi od podataka i ne može biti statički određen. Različito konfigurisani stilovi slika će koristiti različite efekte. Zato je potrebno ugraditi referencu na specifikaciju tipa. Odgovarajući deo šeme iz image.schema.yml izgleda ovako:

image.style.*:
  type: config_entity
  label: 'Image style'
  mapping:
    name:
      type: string
    label:
      type: label
      label: 'Label'
    effects:
      type: sequence
      sequence:
        type: mapping
        mapping:
          id:
            type: string
          data:
            type: image.effect.[%parent.id]
          weight:
            type: integer
          uuid:
            type: string

Ovo definiše metapodatke za sve stilove slika (image.style.*) kao mapu imena, labela i ključeva efekata. Efekti sami su sekvenca (može biti proizvoljan broj efekata), gde je svaki element u listi mapa sa detaljima o efektu. Ključ sekvence je uuid efekta, ali to nije bitno jer sekvence ne mare za ključeve, tako da definišemo samo tip elemenata. Zajedničke vrednosti za efekte su id, data i weight, ali sadržaj data zavisi od vrednosti id roditelja (u gornjem primeru „image_scale“ je ime efekta koji se koristi). Zato kada se ova šema primeni na podatke, image.effect.image_scale je validan referencirani tip.

Obratite pažnju da možete naići i na malo drugačiju definiciju sekvence gde je tip elemenata sekvence striktno definisan kao lista jedinstvenih elemenata. Ovaj format je zastareo i biće uklonjen u Drupalu 9:

deprecated.sequence.definition.format:
  type: sequence
  sequence:
    - type: string
      label: 'DO NOT COPY, THIS IS DEPRECATED'

Nazivi vaših fajlova šema

Vaši fajlovi šema moraju imati globalno jedinstvena imena. Ako se ime vašeg fajla poklapa sa imenom drugog ekstenzije, vaš fajl ili drugi fajl neće biti pronađen, što može dovesti do nejasnih grešaka. Zbog toga se preporučuje da prefiksujete imena šema imenom vašeg modula.

Stil koda koji se koristi za fajlove šema

Samo pratite stil koda .yml koji se koristi na drugim mestima u Drupal jezgru. Pogledajte primere gore za pristup koji treba slediti. Ključne tačke:

• Uključite komentare na vrhu koji objašnjavaju šta se nalazi u fajlu. Ako imate samo jedan fajl šema za ceo modul, dovoljan je komentar poput: # Schema for the configuration files of the Contact module.
• Izbegavajte komentare koji ne dodaju dodatnu jasnoću. Na primer, „Podešavanja komentara“ iznad dela koji definiše šemu za comment.settings su nepotrebni. U svakom slučaju, elementi šema treba da imaju labelu koja ih dobro opisuje. Dodajte komentare samo kada je potrebno.
• Nemojte koristiti dvostruke navodnike za stringove, koristite jednostruke navodnike.
• Koristite jednostruke navodnike za vrednosti labela, čak i ako je reč o jednoj reči, radi doslednosti.
• Nikada ne koristite navodnike za definicije i tipove ključeva (u Drupalu imena i tipovi ključeva su po definiciji stringovi i ne smeju sadržati razmake).
• U Drupalu, celobrojne vrednosti u YAML konfiguracionim fajlovima konvertuju se u stringove i stoga se stavljaju u jednostruke navodnike.
• Dodajte labele bar za vrednosti koje treba prevoditi (kao i za kontejnere koji ih obavijaju). Pogledajte Alat za inspekciju konfiguracije, detaljno opisan u delu o debagovanju da proverite da li se iz vaše šeme može generisati korisna forma.
• Vodite računa o nivou uvlačenja. To nije stil koda kao takav, već je bitno koristiti odgovarajuće uvlačenje u YAML-u da biste dobili željenu strukturu šeme.

Napomena: Uobičajeni stil u .yml konfiguracionim fajlovima zahteva da koristite jednostruke navodnike samo kada imate više reči, jer YAML serijalizacija to radi po difoltu, pa je ovaj standard lakši za menjanje konfiguracije. Pogledajte Standarde kodiranja za konfiguracione fajlove. Međutim, gore navedene smernice za šemu se razlikuju jer se fajlovi šema pišu ručno i za konzistentnost je bolje uvek koristiti navodnike oko vrednosti labela.

PHP API

Možete dobiti konfiguraciju povezanu sa metapodacima koristeći servis \Drupal::service('config.typed') (na primer za sistemski režim održavanja):

$definition = \Drupal::service('config.typed')->getDefinition('system.maintenance');

Struktura niza će biti sledeća:

array(5) {
  ["label"]=>
  string(16) "Maintenance mode"
  ["class"]=>
  string(34) "\Drupal\Core\Config\Schema\Mapping"
  ["definition_class"]=>
  string(40) "\Drupal\Core\TypedData\MapDataDefinition"
  ["mapping"]=>
  array(2) {
    ["langcode"]=>
    array(2) {
      ["type"]=>
      string(6) "string"
      ["label"]=>
      string(13) "Language code"
    }
    ["message"]=>
    array(2) {
      ["type"]=>
      string(4) "text"
      ["label"]=>
      string(43) "Message to display when in maintenance mode"
    }
  }
  ["type"]=>
  string(18) "system.maintenance"
}

Složeniji primer dobijanja tipiziranih podataka vezanih za podatke prvog efekta srednjeg stila slike, kao što je pomenuto u delu o referencama roditelja:

// Dobij tipiziranu konfiguraciju iz dela efekata ključa image.style.medium
// Uzmite uuid ključ prikazan gore u primeru konfiguracionog fajla
// koji odgovara prvom efektu u stilu i elementima data dece.
$effects = \Drupal::service('config.typed')->get('image.style.medium')->get('effects.bddf0d06-42f9-4c75-a700-a33cafa25ea0.data')->getDataDefinition();

Ovo će rezultirati tipom image.effect.image_scale, kao što je opisano gore, i vratiti definiciju mape, na primer:

object(Drupal\Core\TypedData\MapDataDefinition)#1061 (3) {
  ["mainPropertyName":protected]=>
  NULL
  ["propertyDefinitions":protected]=>
  NULL
  ["definition":protected]=>
  array(5) {
    ["type"]=>
    string(24) "image.effect.image_scale"
    ["label"]=>
    string(11) "Image scale"
    ["class"]=>
    string(34) "\Drupal\Core\Config\Schema\Mapping"
    ["definition_class"]=>
    string(40) "\Drupal\Core\TypedData\MapDataDefinition"
    ["mapping"]=>
    array(3) {
      ["width"]=>
      array(2) {
        ["type"]=>
        string(7) "integer"
        ["label"]=>
        string(5) "Width"
      }
      ["height"]=>
      array(2) {
        ["type"]=>
        string(7) "integer"
        ["label"]=>
        string(6) "Height"
      }
      ["upscale"]=>
      array(2) {
        ["type"]=>
        string(7) "boolean"
        ["label"]=>
        string(7) "Upscale"
      }
    }
  }
}

TypedData API se može u potpunosti koristiti za elemente. Kao što su:

// Dobij objekat sekvence efekata iz srednjeg stila slike.
$effects = \Drupal::service('config.typed')->get('image.style.medium')->get('effects');
// $effects predstavlja sekvencu sa uuid ključevima prikazanim gore u primeru roditeljskih referenci.
// Koristite getValue() metodu TypedData za dobijanje vrednosti.
$first_uuid = key($effects->getValue());
// Uzmite data ključeve za ovaj prvi efekat.
$data = $effects->get($first_uuid)->get('data');
// Proverite vrednosti i tipove za width.
$data->get('width')->getPluginId(); // vratiće 'integer'
$data->get('width')->getValue(); // vratiće 220 

Pogledajte više primera koda za navigaciju po konfiguraciji zasnovanoj na šemi, kao i za generisanje formi zasnovanih na šemi na https://drupal.org/project/config_inspector

Debugovanje vaše šeme

Config Inspector modul pruža korisnički interfejs za poređenje šema sa podacima i pregled kako generisanje i transformacija formi (ako postoje) rade sa šemom u odnosu na podatke. Ovo možete koristiti za pronalaženje problema u šemi, pogledajte https://drupal.org/node/1910624#comment-7088154 za savete o tome kako koristiti ovaj alat za debugovanje šema.

Glavni modul za prevod konfiguracije pravi pravi korisnički interfejs preko šema i omogućava ljudima da prevode konfiguraciju. Možete koristiti ovaj modul za debugovanje ako se vaša konfiguracija pravilno prevodi i da li prevodi izlaze na pravim mestima (na frontendu) i ne pojavljuju se na mestima gde ne treba (npr. na backend-u gde ljudi mogu uređivati izvornu konfiguraciju).

Još više referentnih informacija

Proverite #1866610: Predložite format šeme inspirisan Kwalify-jem za konfiguraciju i #1648930: Predložite konfiguracionu šemu i koristite je za prevod kao i stotine komentara gde su diskutovani različiti pristupi i moguća rešenja (i još više pratećih pitanja) pre nego što je došlo do ovog formata. (Takođe #1914366: Premestite sve konfiguracione fajlove u poddirektorijum schema da saznate zašto su tamo gde jesu). Takođe pogledajte #1905152: Integracija konfiguracione šeme da bi konfiguracija bila prevedena za informacije o tome kako se sistem šema integriše sa modulom za lokalizaciju. #1952394: Core Configuration Translation module je mesto gde je dodat modul za prevod u jezgro.

#1602106: Dokumentujte podrazumevane konfiguracione fajlove je početak dokumentovanja pravila za konfiguracione yml fajlove.