---
title: "Polia a hodnoty — Imports for Laravel | Roundly"
description: "Deväť typov polí a ich prevod, popisy, aliasy, príklady, pravidlá a normalizácia, odkazy na iné záznamy a každý kód chyby bunky."
url: https://roundly-consulting.com/sk/open-source/navody/imports-for-laravel/polia
language: sk
---

[Všetky balíky](https://roundly-consulting.com/sk/open-source.md)

[Imports for Laravel](https://roundly-consulting.com/sk/open-source/navody/imports-for-laravel.md)

# 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:

```php
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

```php
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 kryptomien](https://roundly-consulting.com/sk/podporte-nas.md)

Odoslaním daru súhlasíte s našimi [podmienkami prijímania darov](https://roundly-consulting.com/sk/podmienky-darov.md).

[Podporte našu open-source prácu (otvorí sa v novej karte)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Pridajte sa k nám na Patreone (otvorí sa v novej karte)](https://www.patreon.com/cw/roundly)

## 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.

[Ponuka do 48 hodín](https://roundly-consulting.com/sk/kontakt.md) [Prezrieť všetky balíky](https://roundly-consulting.com/sk/open-source/navody/imports-for-laravel.md)