Mapovanie stĺpcov

Po nahratí dostane každý stĺpec navrhnuté pole. Úplný návrh — každé povinné pole, nič približné — sa použije hneď pri nahratí (stav mapped); inak relácia čaká na vás (needs_mapping).

Ako vznikajú návrhy

Hlavičky sa normalizujú: prevedú sa do ASCII a na malé písmená, koncové * / (required) / (povinné) sa vynechá a všetko ostatné okrem písmen a číslic sa zmení na _ (Inventárne č. * → inventarne_c). Každý stĺpec potom dostane najlepšiu z možností:

Postupuje sa nenásytne, každé pole raz, pri zhode vyhrá stĺpec viac vľavo.

$suggestion = $session->suggestMapping();
$suggestion->columns;            // list<SuggestedColumn>: index, header, field, confidence, source; isFuzzy()
$suggestion->unmappedRequired;   // field names
$suggestion->ignoredColumns;     // column indexes
$suggestion->savedMapping;       // the saved mapping's name, or null
$suggestion->isComplete();

$session->map($suggestion->toMapping());   // apply it as it is

Mapovanie podľa hlavičky alebo stĺpca

use RoundlyConsulting\Imports\DataTransferObjects\ColumnMapping;

$session->map(['Inventárne č.' => 'asset_tag', 3 => 'name']);   // by header text or 0-based column index (3 = column D)
$session->map(['Notes' => null]);                               // leave a column unmapped
$session->map(ColumnMapping::fromArray([2 => 'name']));         // always by 0-based column index
$session->saveMapping('ERP export');

• Celočíselné kľúče sú indexy stĺpcov od 0 — okrem prípadu, keď sa toto číslo nachádza v hlavičke (hlavička 2024 je v PHP celočíselný kľúč); vtedy sa mapuje podľa textu.
• Číslo, ktoré je hlavičkou a zároveň indexom iného stĺpca, sa odmietne, nehádá sa — namapujte ho výslovne cez ColumnMapping, ktoré je vždy podľa indexu.
• Odmietne sa výnimkou InvalidMappingException (422, chyby s kľúčmi columns.<column> / fields.<field>): neznáme pole alebo stĺpec, pole namapované dvakrát, duplicitná hlavička uvedená textom (použite jej číslo), nenamapované povinné pole.
• Zmena mapovania zahodí náhľad a zvýši preview_version; import podľa staršej verzie sa odmietne.
• Keď reláciu drží import — aj taký, ktorý sa začal o okamih skôr z inej karty alebo workera — zmena mapovania sa odmietne výnimkou ImportStateException, takže nikdy neprepíše plán bežiaceho importu.

Uložené mapovania

Mapovanie raz pomenujete a každý ďalší súbor s rovnakými hlavičkami sa namapuje sám — aj keď sú stĺpce v inom poradí. Uložíte ho z relácie alebo z textu hlavičiek:

$mappings = Imports::for($team)->by($user)->mappings('assets');

$mappings->all();                                     // list<SavedMapping>
$mappings->find('ERP export');                        // ?SavedMapping
$mappings->save('ERP export', ['Inventárne č.' => 'asset_tag', 'Názov' => 'name']);
$mappings->delete('ERP export');                      // false when there was none

• $session->saveMapping($name) (hlavičky a mapovanie relácie spolu s oddeľovačom, hárkom a riadkom hlavičky) aj mappings($importer)->save() spúšťajú SaveMappingAction, takže obe ukladajú rovnaký tvar, spúšťajú MappingSaved a fake ich zaznamenáva rovnako. Uloženie pod existujúcim názvom ho nahradí.
• Akcia kontroluje v tomto poradí: uložené mapovania sú zapnuté; ide o importér riadkov; authorize(Upload); názov s 1–60 znakmi, aspoň jeden stĺpec, každé pole známe a namapované raz; potom limity na importér a veľkosť. Odmietnutia vyhodia InvalidSavedMappingException alebo TooManySavedMappingsException (obe 422).
• Ukladajú sa pre vlastníka cez options-for-laravel (option imports.mappings, jeden riadok na vlastníka), kľúčujú sa normalizovanou hlavičkou a automaticky sa použijú pre identický riadok hlavičky — nikdy, ak sa normalizované hlavičky zrazia.
• Podpisy hlavičiek nezávisia od jazyka — vždy sa prepisujú pod en — takže mapovanie, ktoré uložil slovenský používateľ, sa rozpozná aj pre nemeckého.
• Najviac mappings.max_per_importer (20) na importér a mappings.max_bytes spolu. Zápisy sa serializujú zámkom v cache — mappings.lock_store nastavte na zdieľané úložisko.