NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Imports for Laravel

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

TypPrevod
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ódaVý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ódVýznam
invalid_integer · integer_overflow · invalid_number · invalid_booleanHodnotu 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_valueNepovolená hodnota; nad dĺžkou bunky importéra (predvolene limits.cell_length); nepoužiteľná hodnota.
spreadsheet_errorChybová bunka XLSX, napríklad #N/A.
extra_valuesHodnota v CSV za posledným stĺpcom hlavičky.
unknown_reference · ambiguous_referencePre odkaz v rámci vlastníka sa nenašiel žiadny záznam alebo ich je viac.
ambiguous_match · conflicting_matchDva záznamy pre jeden prirodzený kľúč; neskorší kandidát kľúča nájde iný záznam.
matches_deleted_recordKľúč 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

Odoslaní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.