NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
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ľúčEnvPredvolenéÚčel
importers—[]Triedy, ktoré rozširujú Importer alebo FileImporter. Ďalšie pridáte za behu cez Imports::register().
key_typeIMPORTS_KEY_TYPEbigintbigint, 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_typeIMPORTS_RECORD_KEY_TYPEblank = key_typeMorph importovaného záznamu — typ kľúča každého modelu importéra.
primary_key_typeIMPORTS_PRIMARY_KEY_TYPEbigintVlastné id tabuliek balíka. Čítajú ho migrácie — nastavte ho pred migráciou.
models.session / batch / row_result / record—ImportSession / ImportBatch / ImportRowResult / ImportedRecordModel 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::classTrieda 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ľúčEnvPredvolenéÚčel
storage.diskIMPORTS_DISKlocalKam sa ukladajú nahraté súbory. Nikdy nie verejný disk — imports:doctor ho nahlási ako chybu.
storage.path—importsSúbory idú do <path>/<owner digest>/<session id>/.
storage.retentionIMPORTS_RETENTIONP30DZdrojové súbory, pracovné kópie a výsledky riadkov po tejto dobe zmaže imports:prune.
storage.tmp_pathIMPORTS_TMP_PATHblank = sys_get_temp_dir()/roundly-importsDočasné súbory — súbor z nelokálneho disku sa sem skopíruje, keď je potrebný náhodný prístup.
storage.tmp_ttl—PT6HOsirotené dočasné adresáre staršie než táto doba odstráni imports:sweep.
history.retentionIMPORTS_HISTORY_RETENTIONblank = keep foreverRelá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ľúčEnvPredvolenéÚčel
limits.file_sizeIMPORTS_MAX_FILE_SIZE10240KB, 1 … 2 097 152 — kontroluje sa pred čítaním súboru.
limits.rowsIMPORTS_MAX_ROWS10000Dátové riadky, 1 … 100 000.
limits.columnsIMPORTS_MAX_COLUMNS1001 … 16 384; len neprázdne bunky, takže formátované prázdne stĺpce sa nerátajú.
limits.cell_length—32767Znaky v bunke, 1 … 1 048 576. Importér ho prepíše cez limits()->withCellLength().

Čítanie CSV a XLSX

KľúčEnvPredvolenéÚčel
csv.delimiters—[',', ';']Jednoznakoví kandidáti na rozpoznanie oddeľovača.
csv.sniff_bytes—655361 024 … 1 048 576 bajtov prečítaných na rozpoznanie oddeľovača.
csv.unescape_formula_prefix—trueOdstráni ', ktorý vlastný CSV zapisovač balíka pridá pred bunky podobné vzorcom.
xlsx.max_entries—10001 … 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—falsePrijíma zošity .xlsm — makrá sa nikdy nespustia.

Hlavičky a hodnoty

KľúčEnvPredvolenéÚč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—trueNavrhuje podobné zápisy — označené, nikdy sa nepoužijú bez kontroly.
headers.fuzzy_threshold—0.850,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.timezoneIdentifiká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ľúčEnvPredvolenéÚčel
preview.sync_thresholdIMPORTS_SYNC_THRESHOLD5000 … 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—5001 … 10 000 riadkov v jednom okne overovania.
preview.progress_every—2501 … 100 000 riadkov medzi udalosťami ImportPreviewProgressed.
commit.chunk_size—2501 … 10 000 riadkov v jednej časti.
commit.max_chunks—1001 … 1 000 — veľkosť časti sa prispôsobí.
commit.tries—31 … 100 pokusov na úlohu jednej časti.
commit.backoff—[10, 60, 300]Nezáporné sekundy medzi pokusmi.
commit.timeout—6001 … 86 400 sekúnd — retry_after frontu držte nad touto hodnotou (doctor to kontroluje).
undo.windowIMPORTS_UNDO_WINDOWP7DAko dlho sa dá dokončený import vrátiť.
sessions.expire_after—P2DNepotvrdené relácie expirujú (imports:sweep).
sessions.stale_after—PT30MBez priebehu takto dlho a bez živej úlohy → zlyhaná.
sessions.abandon_after—PT6HBez aktivity takto dlho → zlyhaná v každom prípade.

Front

KľúčEnvPredvolenéÚčel
queue.enabledIMPORTS_QUEUE_ENABLEDtrueVypnuté: náhľady sa overujú v požiadavke a dávky bežia na spojení sync.
queue.connectionIMPORTS_QUEUE_CONNECTIONblank = defaultSpojenie pre náhľady, importy a vrátenia.
queue.queueIMPORTS_QUEUE_NAMEblank = defaultNázov frontu.

Dávky súborov

KľúčEnvPredvolenéÚčel
files.max_files—5001 … 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—1001 … 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—51200KB — predvolený limit na súbor, ak FileRules žiadny nenastaví.
files.max_archive_size—1048576KB na archív.
files.ignore—['__MACOSX/*', '*.DS_Store', 'Thumbs.db', 'desktop.ini']Preskakované položky.

Šablóny

KľúčEnvPredvolenéÚčel
templates.default_format—xlsxxlsx alebo csv.
templates.example_row—trueZapíše vzorový riadok.
templates.hint_row.csv / .xlsx—true / falseZapíše riadok s nápovedou (povinné, povolené hodnoty, formáty).
templates.data_validation—trueRozbaľ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—trueCSV šablóny začínajú UTF-8 BOM.

Uložené mapovania

KľúčEnvPredvolenéÚčel
mappings.enabled—trueVypnuté: tabuľka options nie je potrebná a uloženie vyhodí InvalidSavedMappingException::disabled().
mappings.max_per_importer—201 … 1 000 pre vlastníka a importér.
mappings.max_bytes—600001 024 … 16 000 000 — stĺpec hodnoty v options je text (64 KB na MySQL).
mappings.lock_storeIMPORTS_LOCK_STOREblank = default cache storeSerializuje ukladanie — použite zdieľané úložisko (redis, database).

HTTP

KľúčEnvPredvolenéÚčel
resources.owner / actor / record—ImportOwnerResource / ImportActorResource / ImportRecordResourceInštanciovateľná podtrieda JsonResource pre každý odkaz (pozrite JSON API).
routes.enabledIMPORTS_ROUTESoffJSON API — on/off (akákoľvek logická hodnota).
routes.prefix—api/importsPrefix URL.
routes.middleware—['api', 'auth']Middleware ciest.
routes.upload_limitIMPORTS_UPLOAD_LIMIT100 … 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 userTrieda 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=10

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.