Polia a hodnoty
Definition\Field je fluentné a nemenné — každé volanie vráti kópiu, takže spoločnú definíciu poľa môžete bezpečne upraviť pre každý importér:
use App\Enums\AssetStatus;
use RoundlyConsulting\Imports\Definition\Field;
Field::text('asset_tag')->label('app.asset.tag')->aliases('tag', 'inventory no')->example('AST-0042');
Field::integer('quantity')->min(1);
Field::decimal('price', 2);
Field::boolean('insured')->trueValues('ja')->falseValues('nein');
Field::date('purchased_on')->formats('m/d/Y'); // US dates are opt-in
Field::datetime('seen_at');
Field::email('email')->required();
Field::choice('status')->options(AssetStatus::class)->default('active');
Field::reference('vendor')->to(Vendor::class)->by('vat_id', 'name')->caseInsensitive();Typy a prevod
| Typ | Prevod |
|---|---|
Field::text($name) | Čísla si ponechajú číslice (5, nie 5.0; vedecký zápis sa rozpíše do exponentu ±400, nad ním zostane tak, ako je napísaný); dátumy sa zmenia na Y-m-d; logické hodnoty na TRUE/FALSE; najviac dĺžka bunky z limits() importéra (predvolene limits.cell_length). |
Field::integer($name) | Číselná bunka alebo text s oddeľovačmi tisícov; 5.0 je v poriadku, 5.5 a pretečenie sú chyby; vedecký zápis s exponentom nad ±400 je invalid_integer. |
Field::decimal($name, $scale = 2) | Číselný reťazec, nikdy float: text v jazyku relácie (1 299,50 v sk), pri oboch oddeľovačoch platí posledný, zaokrúhlenie half-up v reťazcovej aritmetike (0.30000000000000004 → 0.30); vedecký zápis s exponentom nad ±400 (1e999999999) je invalid_number. |
Field::boolean($name) | Vždy angličtina aj slovenčina — 1 true yes y x ✓ áno ano a pravda / 0 false no n nie nepravda — plus trueValues() a falseValues(). |
Field::date($name) · Field::datetime($name) | Dátumy XLSX (miestny čas vrátane dní so zmenou času); sériové čísla Excelu 1 … 2958465 v systéme 1900 alebo 1904 zošita (CSV je 1900); text podľa values.date_formats / datetime_formats, potom formats(), s kontrolou spätného prevodu — 31.02.2026 sa odmietne, 01/02/2026 sa nikdy nehádá. Časy zo súboru sa čítajú v časovom pásme relácie (values.timezone); DateTime sa potom importéru odovzdá ako ten istý okamih v app.timezone (2026-01-15 09:30 v Europe/Bratislava → 08:30 UTC), čo Eloquent aj uloží. Date zostane kalendárnym dňom, bez prevodu. |
Field::email($name) | Prevedené na malé písmená a overené cez email:rfc. |
Field::choice($name) | Hodnota alebo popis v ktoromkoľvek nastavenom jazyku, bez ohľadu na veľkosť písmen → kanonická hodnota. Bunka sa najprv porovná tak, ako je zadaná (01 a 1.50 sú samostatné kódy), potom ako číslo (1.0 → možnosť 1); exponent nad ±400 je invalid_choice. |
Field::reference($name) | Vyhľadané v dávkach v rámci vlastníka → nájdený model, ako $row->reference('vendor'). |
Nastavenia poľa
Field::text('name')
->label(['en' => 'Name', 'sk' => 'Názov']) // a translation key, text or locale map
->help(['en' => 'As on the invoice', 'sk' => 'Ako na faktúre'])
->aliases(['sk' => ['nazov zariadenia']]) // plain or per locale
->required()
->max(120)
->rules('regex:/^[A-Z0-9 -]+$/i') // any Laravel rule — not exists:/unique:
->normalizeUsing(fn ($value, ?Cell $cell) => is_string($value) ? Str::squish($value) : $value);
Field::choice('status')->options(['active' => 'Active', 'retired' => ['en' => 'Retired', 'sk' => 'Vyradený']]);
Field::choice('gender')->options([1 => 'Male', 2 => 'Female']); // numeric codes: stored values 1 and 2
Field::text('internal_note')->excludeFromTemplate();
Field::reference('vendor')
->to(Vendor::class)
->by('vat_id', 'name') // lookup columns, tried in order
->ownedBy(Ownership::global()) // vendors are shared — default: the importer's rule
->storeAs('vendor_id'); // attributes() and changes() carry the key here
Field::reference('maker')->to(Vendor::class)->by('name')->default('Lenovo'); // unmapped: every row gets Lenovo| Metóda | Význam |
|---|---|
label() · help() | Prekladový kľúč, text alebo mapa jazykov — hlavičky, tipy v šablóne a správy. |
required() · nullable() | nullable je predvolené. |
default($value) · example($value) | Hodnota pre prázdnu bunku; vzorová hodnota v šablóne. |
aliases(...) | Ďalšie hlavičky, ktoré sa priradia k poľu — jednoducho alebo ['sk' => [...]]. |
rules(...) | Validačné pravidlá Laravelu. exists: a unique: (reťazce aj objekty Rule) sa pri registrácii odmietnu — obchádzajú scope vlastníka. Použite reference() a naturalKey(). |
normalizeUsing(fn ($value, ?Cell $cell) => …) | Vaše čistenie po orezaní a pred prevodom typu. |
max() · min() | Dĺžka pri texte, hodnota pri číslach. |
excludeFromTemplate() | Stĺpec sa nezaradí do šablón. |
formats(...) | Date / DateTime: ďalšie formáty createFromFormat, skúšané po values.date_formats. |
trueValues(...) · falseValues(...) | Boolean: vlastné slová. |
options(...) | Choice: hodnota => popis (popisy môžu byť mapy jazykov), zoznam alebo backed enum (popisy z label() z enums-for-laravel). Číselné kódy si ponechajú hodnoty ([1 => 'Male', 2 => 'Female'] → 1 a 2); len skutočný zoznam (kľúče 0, 1, 2, …) sa číta ako hodnoty bez popisov, preto mapu začínajúcu nulou zapíšte ako zoznam alebo s reťazcovými kľúčmi. |
to() · by() · ownedBy() · caseInsensitive() · storeAs() | Reference: model, stĺpce na vyhľadanie skúšané v poradí, vlastné Ownership (predvolene Ownership::inherit() — pravidlo importéra), porovnanie bez ohľadu na veľkosť písmen a stĺpec, do ktorého attributes() a changes() dajú kľúč odkazu (bez neho sa odkaz v oboch vynechá). Nenamapovaný odkaz s default() sa pre každý riadok vyhľadá podľa predvolenej hodnoty; bez zhody je v náhľade unknown_reference. |
labelIn() · helpIn() · aliasesIn() · optionLabel() · exampleValue() | Pomocníci na čítanie pre UI alebo vlastnú šablónu; každé nastavenie je aj verejná vlastnosť len na čítanie (name, type, required, options, target, lookup, storeAs, …). |
Spracovanie hodnoty
Každá bunka prejde rovnakými krokmi v tomto poradí:
- 1. Orezanie — aj nedeliteľných medzier, U+202F a znakov nulovej šírky; prázdna bunka sa zmení na null.
- 2. normalizeUsing().
- 3. Prevod typu — neúspech je chyba bunky, nikdy výnimka.
- 4. default(), ak je hodnota null.
- 5. Overenie: required, vlastné pravidlá typu (max: / min: — dĺžka pri texte, hodnota pri číslach; email:rfc) a rules(), s popismi polí ako názvami atribútov a správami v jazyku relácie.
- 6. Vyhľadanie odkazu — v dávkach, v rámci vlastníka.
Odkazy
Field::reference() prepojí riadok s iným záznamom — dodávateľa podľa IČ DPH, potom podľa názvu. Vyhľadávanie beží v dávkach a v rámci vlastníka: predvolene odkaz zdedí Ownership importéra, ->ownedBy() mu dá vlastné (Ownership::global() pre zdieľané záznamy). Nájdený model je $row->reference('vendor'); storeAs('vendor_id') zabezpečí, že attributes() a changes() ponesú jeho kľúč. Žiadna zhoda je unknown_reference, viac zhôd ambiguous_reference. Odkaz s default(), ku ktorému nie je namapovaný žiadny stĺpec, sa pre každý riadok vyhľadá podľa predvolenej hodnoty (default('Lenovo') → dodávateľ Lenovo); ak nič nenájde, každý riadok v náhľade zlyhá s unknown_reference.
Kódy chýb buniek
| Kód | Význam |
|---|---|
invalid_integer · integer_overflow · invalid_number · invalid_boolean | Hodnotu sa nepodarilo previesť na typ poľa — aj vedecký zápis s exponentom nad ±400. |
invalid_date · invalid_datetime | Žiadny nastavený formát nesedí alebo dátum neexistuje. |
invalid_choice · too_long · invalid_value | Nepovolená hodnota; nad dĺžkou bunky importéra (predvolene limits.cell_length); nepoužiteľná hodnota. |
spreadsheet_error | Chybová bunka XLSX, napríklad #N/A. |
extra_values | Hodnota v CSV za posledným stĺpcom hlavičky. |
unknown_reference · ambiguous_reference | Pre odkaz v rámci vlastníka sa nenašiel žiadny záznam alebo ich je viac. |
ambiguous_match · conflicting_match | Dva záznamy pre jeden prirodzený kľúč; neskorší kandidát kľúča nájde iný záznam. |
matches_deleted_record | Kľúč má len soft-deleted záznam — obnovte ho alebo zmeňte identifikátor. |
required, max, email, … | Názvy pravidiel Laravelu, s popismi polí ako názvami atribútov a správami v jazyku relácie. |
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.