Všetky balíky
Imports for Laravel
Konfigurácia
Balík funguje bez akejkoľvek konfigurácie. config/imports.php publikujte, len ak chcete niečo zmeniť:
php artisan vendor:publish --tag="imports-config"Každá hodnota sa číta prísne: hodnota nesprávneho typu alebo mimo rozsahu vyhodí InvalidImportsConfigurationException s názvom kľúča a prázdna premenná prostredia (KEY=) znamená predvolenú hodnotu.
- Trvania sú v ISO-8601 (P7D, PT30M) a musia byť kladné.
- Prepínače prijímajú akúkoľvek logickú hodnotu vrátane on a off.
- Celé čísla musia byť v rozsahu uvedenom v riadku; hodnota mimo neho vyhodí výnimku, neoreže sa.
- Kľúče s triedami (scope vlastníka, resources, resolver vlastníka) musia uvádzať triedu správneho druhu; čokoľvek iné vyhodí výnimku s názvom kľúča.
Konfiguračný súbor
use RoundlyConsulting\Imports\Http\Resources\ImportActorResource;
use RoundlyConsulting\Imports\Http\Resources\ImportOwnerResource;
use RoundlyConsulting\Imports\Http\Resources\ImportRecordResource;
use RoundlyConsulting\Imports\Models\ImportBatch;
use RoundlyConsulting\Imports\Models\ImportedRecord;
use RoundlyConsulting\Imports\Models\ImportRowResult;
use RoundlyConsulting\Imports\Models\ImportSession;
use RoundlyConsulting\Imports\Scoping\ExplicitOwnerScope;
return [
'importers' => [],
'key_type' => env('IMPORTS_KEY_TYPE', 'bigint'),
'record_key_type' => env('IMPORTS_RECORD_KEY_TYPE'),
'primary_key_type' => env('IMPORTS_PRIMARY_KEY_TYPE', 'bigint'),
'models' => [
'session' => ImportSession::class,
'batch' => ImportBatch::class,
'row_result' => ImportRowResult::class,
'record' => ImportedRecord::class,
],
'tables' => [
'sessions' => 'import_sessions',
'batches' => 'import_batches',
'row_results' => 'import_row_results',
'records' => 'imported_records',
],
'owner_scope' => ExplicitOwnerScope::class,
'storage' => [
'disk' => env('IMPORTS_DISK', 'local'), // never a public disk
'path' => 'imports',
'retention' => env('IMPORTS_RETENTION', 'P30D'),
'tmp_path' => env('IMPORTS_TMP_PATH'), // blank = sys_get_temp_dir()/roundly-imports
'tmp_ttl' => 'PT6H',
],
'history' => [
'retention' => env('IMPORTS_HISTORY_RETENTION'), // blank = keep forever
],
'limits' => [
'file_size' => env('IMPORTS_MAX_FILE_SIZE', 10240), // KB
'rows' => env('IMPORTS_MAX_ROWS', 10000), // hard ceiling 100,000
'columns' => env('IMPORTS_MAX_COLUMNS', 100), // hard ceiling 16,384
'cell_length' => 32767,
],
'csv' => [
'delimiters' => [',', ';'],
'sniff_bytes' => 65536,
'unescape_formula_prefix' => true,
],
'xlsx' => [
'max_entries' => 1000,
'max_part_size' => 268435456,
'max_inflated' => 536870912,
'max_blank_rows' => 10000,
'shared_strings_memory' => 2097152,
'allow_macro_enabled' => false,
],
'headers' => [
'locales' => ['en', 'sk'],
'fuzzy' => true,
'fuzzy_threshold' => 0.85,
],
'values' => [
'date_formats' => ['Y-m-d', 'd.m.Y', 'j.n.Y', 'j. n. Y'],
'datetime_formats' => ['Y-m-d H:i:s', 'Y-m-d H:i', 'd.m.Y H:i', 'j.n.Y H:i'],
'timezone' => null, // blank = the application timezone
],
'preview' => [
'sync_threshold' => env('IMPORTS_SYNC_THRESHOLD', 500),
'window' => 500,
'progress_every' => 250,
],
'commit' => [
'chunk_size' => 250,
'max_chunks' => 100,
'tries' => 3,
'backoff' => [10, 60, 300],
'timeout' => 600,
],
'undo' => [
'window' => env('IMPORTS_UNDO_WINDOW', 'P7D'),
],
'sessions' => [
'expire_after' => 'P2D',
'stale_after' => 'PT30M',
'abandon_after' => 'PT6H',
],
'queue' => [
'enabled' => env('IMPORTS_QUEUE_ENABLED', true),
'connection' => env('IMPORTS_QUEUE_CONNECTION'),
'queue' => env('IMPORTS_QUEUE_NAME'),
],
'files' => [
'max_files' => 500,
'max_uncompressed' => 1073741824,
'max_ratio' => 100,
'ratio_min_size' => 1048576,
'max_file_size' => 51200, // KB
'max_archive_size' => 1048576, // KB
'ignore' => ['__MACOSX/*', '*.DS_Store', 'Thumbs.db', 'desktop.ini'],
],
'templates' => [
'default_format' => 'xlsx',
'example_row' => true,
'hint_row' => ['csv' => true, 'xlsx' => false],
'data_validation' => true,
'csv_delimiter' => ['default' => ',', 'sk' => ';'],
'csv_bom' => true,
],
'mappings' => [
'enabled' => true,
'max_per_importer' => 20,
'max_bytes' => 60000,
'lock_store' => env('IMPORTS_LOCK_STORE'),
],
'resources' => [
'owner' => ImportOwnerResource::class,
'actor' => ImportActorResource::class,
'record' => ImportRecordResource::class,
],
'routes' => [
'enabled' => env('IMPORTS_ROUTES') ?: 'off',
'prefix' => 'api/imports',
'middleware' => ['api', 'auth'],
'upload_limit' => env('IMPORTS_UPLOAD_LIMIT', 10),
'owner_resolver' => null,
],
];Importéry, typy kľúčov, modely a tabuľky
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
importers | — | [] | Triedy, ktoré rozširujú Importer alebo FileImporter. Ďalšie pridáte za behu cez Imports::register(). |
key_type | IMPORTS_KEY_TYPE | bigint | bigint, uuid alebo ulid — morph vzťahy vlastníka a aktéra. Musí sa zhodovať s options.key_type: uložené mapovania sú options viazané na vlastníka. |
record_key_type | IMPORTS_RECORD_KEY_TYPE | blank = key_type | Morph importovaného záznamu — typ kľúča každého modelu importéra. |
primary_key_type | IMPORTS_PRIMARY_KEY_TYPE | bigint | Vlastné id tabuliek balíka. Čítajú ho migrácie — nastavte ho pred migráciou. |
models.session / batch / row_result / record | — | ImportSession / ImportBatch / ImportRowResult / ImportedRecord | Model vymeníte tak, že rozšírite triedu z balíka a uvediete tu podtriedu. |
tables.sessions / batches / row_results / records | — | import_sessions / import_batches / import_row_results / imported_records | ^[a-z_][a-z0-9_]{0,29}$ — najviac 30 znakov, aby odvodené názvy indexov zostali pod limitom MySQL 64. |
owner_scope | — | ExplicitOwnerScope::class | Trieda Contracts\OwnerScope — drží každé vyhľadávanie aj zápis v rámci vlastníka (pozrite Vlastníci a oprávnenia). |
Úložisko a uchovávanie
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
storage.disk | IMPORTS_DISK | local | Kam sa ukladajú nahraté súbory. Nikdy nie verejný disk — imports:doctor ho nahlási ako chybu. |
storage.path | — | imports | Súbory idú do <path>/<owner digest>/<session id>/. |
storage.retention | IMPORTS_RETENTION | P30D | Zdrojové súbory, pracovné kópie a výsledky riadkov po tejto dobe zmaže imports:prune. |
storage.tmp_path | IMPORTS_TMP_PATH | blank = sys_get_temp_dir()/roundly-imports | Dočasné súbory — súbor z nelokálneho disku sa sem skopíruje, keď je potrebný náhodný prístup. |
storage.tmp_ttl | — | PT6H | Osirotené dočasné adresáre staršie než táto doba odstráni imports:sweep. |
history.retention | IMPORTS_HISTORY_RETENTION | blank = keep forever | Relácie, dávky a riadky evidencie staršie než táto doba a po uplynutí okna na vrátenie zmaže imports:prune. |
Limity
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
limits.file_size | IMPORTS_MAX_FILE_SIZE | 10240 | KB, 1 … 2 097 152 — kontroluje sa pred čítaním súboru. |
limits.rows | IMPORTS_MAX_ROWS | 10000 | Dátové riadky, 1 … 100 000. |
limits.columns | IMPORTS_MAX_COLUMNS | 100 | 1 … 16 384; len neprázdne bunky, takže formátované prázdne stĺpce sa nerátajú. |
limits.cell_length | — | 32767 | Znaky v bunke, 1 … 1 048 576. Importér ho prepíše cez limits()->withCellLength(). |
Čítanie CSV a XLSX
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
csv.delimiters | — | [',', ';'] | Jednoznakoví kandidáti na rozpoznanie oddeľovača. |
csv.sniff_bytes | — | 65536 | 1 024 … 1 048 576 bajtov prečítaných na rozpoznanie oddeľovača. |
csv.unescape_formula_prefix | — | true | Odstráni ', ktorý vlastný CSV zapisovač balíka pridá pred bunky podobné vzorcom. |
xlsx.max_entries | — | 1000 | 1 … 100 000 položiek ZIP v zošite. |
xlsx.max_part_size | — | 268435456 | ≥ 1 024 bajtov na časť, rátané počas rozbaľovania (256 MB). |
xlsx.max_inflated | — | 536870912 | ≥ 1 024 bajtov počas jedného čítania (512 MB). |
xlsx.max_blank_rows | — | 10000 | ≥ 1 — najdlhší úsek prázdnych riadkov medzi dvoma riadkami s dátami. Dáta pod dlhšou medzerou súbor odmietnu (data_after_blank_rows); formátovaný prázdny koniec bez dát pod ním sa ignoruje. |
xlsx.shared_strings_memory | — | 2097152 | ≥ 1 024 bajtov zdieľaných reťazcov v pamäti, potom sa presunú na disk (2 MB). |
xlsx.allow_macro_enabled | — | false | Prijíma zošity .xlsm — makrá sa nikdy nespustia. |
Hlavičky a hodnoty
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
headers.locales | — | ['en', 'sk'] | Jazyky, ktorých popisy sa porovnávajú s hlavičkami, plus aktuálny a záložný jazyk. |
headers.fuzzy | — | true | Navrhuje podobné zápisy — označené, nikdy sa nepoužijú bez kontroly. |
headers.fuzzy_threshold | — | 0.85 | 0,5 … 1,0. |
values.date_formats | — | ['Y-m-d', 'd.m.Y', 'j.n.Y', 'j. n. Y'] | Formáty PHP createFromFormat pre text dátumu; pole pridá vlastné cez formats(). |
values.datetime_formats | — | ['Y-m-d H:i:s', 'Y-m-d H:i', 'd.m.Y H:i', 'j.n.Y H:i'] | To isté pre dátum s časom. |
values.timezone | — | blank = app.timezone | Identifikátor časového pásma — čas, v ktorom sa čítajú dátumy a časy zo súboru. Hodnoty DateTime sa potom pred odovzdaním importéru prevedú do app.timezone; hodnoty Date nie. |
Náhľad, import, vrátenie a relácie
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
preview.sync_threshold | IMPORTS_SYNC_THRESHOLD | 500 | 0 … 100 000 — toľko dátových riadkov sa overí priamo v požiadavke, viac vo fronte. Aj hranica pre vrátenie bez frontu. |
preview.window | — | 500 | 1 … 10 000 riadkov v jednom okne overovania. |
preview.progress_every | — | 250 | 1 … 100 000 riadkov medzi udalosťami ImportPreviewProgressed. |
commit.chunk_size | — | 250 | 1 … 10 000 riadkov v jednej časti. |
commit.max_chunks | — | 100 | 1 … 1 000 — veľkosť časti sa prispôsobí. |
commit.tries | — | 3 | 1 … 100 pokusov na úlohu jednej časti. |
commit.backoff | — | [10, 60, 300] | Nezáporné sekundy medzi pokusmi. |
commit.timeout | — | 600 | 1 … 86 400 sekúnd — retry_after frontu držte nad touto hodnotou (doctor to kontroluje). |
undo.window | IMPORTS_UNDO_WINDOW | P7D | Ako dlho sa dá dokončený import vrátiť. |
sessions.expire_after | — | P2D | Nepotvrdené relácie expirujú (imports:sweep). |
sessions.stale_after | — | PT30M | Bez priebehu takto dlho a bez živej úlohy → zlyhaná. |
sessions.abandon_after | — | PT6H | Bez aktivity takto dlho → zlyhaná v každom prípade. |
Front
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
queue.enabled | IMPORTS_QUEUE_ENABLED | true | Vypnuté: náhľady sa overujú v požiadavke a dávky bežia na spojení sync. |
queue.connection | IMPORTS_QUEUE_CONNECTION | blank = default | Spojenie pre náhľady, importy a vrátenia. |
queue.queue | IMPORTS_QUEUE_NAME | blank = default | Názov frontu. |
Dávky súborov
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
files.max_files | — | 500 | 1 … 100 000 súborov alebo položiek ZIP v dávke. |
files.max_uncompressed | — | 1073741824 | ≥ 1 024 bajtov — deklarovaný celkový objem archívu (1 GB). |
files.max_ratio | — | 100 | 1 … 100 000 — povolený kompresný pomer. |
files.ratio_min_size | — | 1048576 | ≥ 0 bajtov — pomer platí nad touto veľkosťou (1 MB). |
files.max_file_size | — | 51200 | KB — predvolený limit na súbor, ak FileRules žiadny nenastaví. |
files.max_archive_size | — | 1048576 | KB na archív. |
files.ignore | — | ['__MACOSX/*', '*.DS_Store', 'Thumbs.db', 'desktop.ini'] | Preskakované položky. |
Šablóny
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
templates.default_format | — | xlsx | xlsx alebo csv. |
templates.example_row | — | true | Zapíše vzorový riadok. |
templates.hint_row.csv / .xlsx | — | true / false | Zapíše riadok s nápovedou (povinné, povolené hodnoty, formáty). |
templates.data_validation | — | true | Rozbaľovacie zoznamy v XLSX pre stĺpce s výberom a áno/nie. |
templates.csv_delimiter | — | ['default' => ',', 'sk' => ';'] | Pre každý jazyk; default je povinný. |
templates.csv_bom | — | true | CSV šablóny začínajú UTF-8 BOM. |
Uložené mapovania
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
mappings.enabled | — | true | Vypnuté: tabuľka options nie je potrebná a uloženie vyhodí InvalidSavedMappingException::disabled(). |
mappings.max_per_importer | — | 20 | 1 … 1 000 pre vlastníka a importér. |
mappings.max_bytes | — | 60000 | 1 024 … 16 000 000 — stĺpec hodnoty v options je text (64 KB na MySQL). |
mappings.lock_store | IMPORTS_LOCK_STORE | blank = default cache store | Serializuje ukladanie — použite zdieľané úložisko (redis, database). |
HTTP
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
resources.owner / actor / record | — | ImportOwnerResource / ImportActorResource / ImportRecordResource | Inštanciovateľná podtrieda JsonResource pre každý odkaz (pozrite JSON API). |
routes.enabled | IMPORTS_ROUTES | off | JSON API — on/off (akákoľvek logická hodnota). |
routes.prefix | — | api/imports | Prefix URL. |
routes.middleware | — | ['api', 'auth'] | Middleware ciest. |
routes.upload_limit | IMPORTS_UPLOAD_LIMIT | 10 | 0 … 10 000 nahratí za minútu na prihláseného používateľa (na IP pre hostí), oba endpointy nahrávania; 0 = bez limitu. |
routes.owner_resolver | — | null = the authenticated user | Trieda Contracts\ResolvesImportOwner. |
Prostredie
IMPORTS_KEY_TYPE=bigint
IMPORTS_RECORD_KEY_TYPE=
IMPORTS_PRIMARY_KEY_TYPE=bigint
IMPORTS_DISK=local
IMPORTS_RETENTION=P30D
IMPORTS_TMP_PATH=
IMPORTS_HISTORY_RETENTION=
IMPORTS_MAX_FILE_SIZE=10240
IMPORTS_MAX_ROWS=10000
IMPORTS_MAX_COLUMNS=100
IMPORTS_SYNC_THRESHOLD=500
IMPORTS_UNDO_WINDOW=P7D
IMPORTS_QUEUE_ENABLED=true
IMPORTS_QUEUE_CONNECTION=
IMPORTS_QUEUE_NAME=
IMPORTS_LOCK_STORE=redis
IMPORTS_ROUTES=off
IMPORTS_UPLOAD_LIMIT=10Prejavte 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.