{"id":16790333,"url":"https://github.com/alfonsobries/laravel-spreadsheet-importer","last_synced_at":"2025-07-14T18:32:25.351Z","repository":{"id":53424903,"uuid":"194753618","full_name":"alfonsobries/laravel-spreadsheet-importer","owner":"alfonsobries","description":"Super fast spreadsheet importer for Laravel apps powered by node","archived":false,"fork":false,"pushed_at":"2021-03-30T19:52:06.000Z","size":4982,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-04T17:52:45.347Z","etag":null,"topics":["laravel","spreadsheet"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alfonsobries.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-01T23:01:52.000Z","updated_at":"2021-03-10T23:46:29.000Z","dependencies_parsed_at":"2022-08-27T15:22:12.058Z","dependency_job_id":null,"html_url":"https://github.com/alfonsobries/laravel-spreadsheet-importer","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/alfonsobries/laravel-spreadsheet-importer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfonsobries%2Flaravel-spreadsheet-importer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfonsobries%2Flaravel-spreadsheet-importer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfonsobries%2Flaravel-spreadsheet-importer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfonsobries%2Flaravel-spreadsheet-importer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alfonsobries","download_url":"https://codeload.github.com/alfonsobries/laravel-spreadsheet-importer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alfonsobries%2Flaravel-spreadsheet-importer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265251860,"owners_count":23735047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","spreadsheet"],"created_at":"2024-10-13T08:29:30.537Z","updated_at":"2025-07-14T18:32:25.043Z","avatar_url":"https://github.com/alfonsobries.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel Faster Spreadsheet Importer\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/alfonsobries/laravel-spreadsheet-importer.svg?style=flat-square)](https://packagist.org/packages/alfonsobries/laravel-spreadsheet-importer)\n\nThis package works together with the [xlsx-laravel-spreadsheet-importer](https://github.com/alfonsobries/xlsx-laravel-spreadsheet-importer) CLI tool to quickly import spreadsheets from xlsx files an other [compatible formats](https://www.npmjs.com/package/xlsx#file-formats) and then store the values into temporal database tables that are way easier to work with.\n\nBecause we use Node instead of PHP we can import larger xlsx files in just a few seconds, and because we will work with a SQL table the operations with the data are **considerably** faster.\n\n- Includes a command that expect the data according to the cli tool and trigger an observable event with the progress of the import.\n- Adds a Trait that add the ability to your model to work with the temporal data as easy as any Eloquent relationship.\n- Once the import is finished triggers another observable event so you can know when you can continue with the following operations related with your import.\n- Manages multiple files format, see (https://www.npmjs.com/package/xlsx#file-formats)\n- Compatible with PostgreSQL as MySQL\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require alfonsobries/laravel-spreadsheet-importer\n```\n\nYou also will need the npm package ([check alfonsobries/xlsx-laravel-spreadsheet-importer for more info](https://github.com/alfonsobries/xlsx-laravel-spreadsheet-importer))\n\n``` bash\nnpm install @alfonsobries/xlsx-laravel-spreadsheet-importer --save\n```\n\nOptionally publish the config files by running:\n```bash\nphp artisan vendor:publish --provider=\"Alfonsobries\\LaravelSpreadsheetImporter\\LaravelSpreadsheetImporterServiceProvider\" --tag=\"config\"\n``` \n\n## Configure your model\n\nThe files that you will import usually will be associated to one Model, also your Model will be used to store the progress of the import.\n\nStart by adding the `InteractsWithImporter` trait and the `Importable` contract to the Model.\n\nYou will also need to define the methods in the `Importable` contract\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Alfonsobries\\LaravelSpreadsheetImporter\\Traits\\InteractsWithImporter;\nuse Alfonsobries\\LaravelSpreadsheetImporter\\Contracts\\Importable;\nuse Illuminate\\Database\\Eloquent\\Model;\n\nclass MyModel extends Model implements Importable\n{\n    use InteractsWithImporter;\n\n    /**\n     * Return the full path of the file that will be imported\n     * @return string\n     */\n    public function getFileToImportPath() {\n        // Notice that this line should be adapted to your application, this is an example for\n        // a path that comes from a file that was stored using the spatie media library package\n        return $this-\u003egetFirstMedia('file')-\u003egetPath();\n    }\n\n    /**\n     * Return the temporaly table name that will be used to store the spreadsheet contents\n     *\n     * @return string\n     */\n    public function getTemporalTableName() {\n        // This is an example you should adapt this line to your own application\n        // You should create a method that always return the same value for the same model\n        return sprintf('file_%s', $this-\u003eid);\n    }\n```\n\n### Add the neccesary columns to the `Importable` Model\n\nYour Model will need a few columns to store the progress and status of the import, to add those columns you can create a migration like the following (just change the table name for your model table name):\n``` php\n\u003c?php\n\nuse Illuminate\\Support\\Facades\\Schema;\nuse Illuminate\\Database\\Schema\\Blueprint;\nuse Illuminate\\Database\\Migrations\\Migration;\n\nclass AddImportableColumnsToModel extends Migration\n{\n    /**\n     * Run the migrations.\n     *\n     * @return void\n     */\n    public function up()\n    {\n        Schema::table('my_model_table', function (Blueprint $table) {\n            $table-\u003estring('importable_process_id')-\u003enullable();\n            $table-\u003estring('importable_table_name')-\u003enullable();\n            $table-\u003estring('importable_total_rows')-\u003enullable();\n            $table-\u003estring('importable_processed')-\u003enullable();\n            $table-\u003estring('importable_status')-\u003edefault('new');\n            $table-\u003emediumText('importable_output')-\u003enullable();\n            $table-\u003emediumText('importable_feedback')-\u003enullable();\n        });\n    }\n\n    /**\n     * Reverse the migrations.\n     *\n     * @return void\n     */\n    public function down()\n    {\n        Schema::table('my_model_table', function (Blueprint $table) {\n            $table-\u003edropColumn('importable_process_id');\n            $table-\u003edropColumn('importable_table_name');\n            $table-\u003edropColumn('importable_total_rows');\n            $table-\u003edropColumn('importable_processed');\n            $table-\u003edropColumn('importable_status');\n            $table-\u003edropColumn('importable_output');\n            $table-\u003edropColumn('importable_feedback');\n        });\n    }\n}\n``` \n\nOnce the Model is configured and you import a spreadsheet you can interact with the data stored in the temporal table using the `tempData()` relationship.\n\nFor example lets say that your spreadsheet has a sales column and you want the total:\n\n```php\n$totalSales = $myModel-\u003etempData()-\u003esum('sales');\n``` \n\n## Import a file\n\nFor importing a file you will need to call the `xlsx-laravel-spreadsheet-importer` command using the instructions [here](https://github.com/alfonsobries/xlsx-laravel-spreadsheet-importer) but to make your work easy this package includes a `StartImport` Job that will build the command for you (dont forget to add the neccesary columns to store the progres to your model).\n\nYou can dispatch the job at any moment, it receive the `importable` Model as a param.\n\nFor example, you can call the job once you save your model in a `store` method in a controller (assuming that your model is associating a file and will return a valid file_path in the `getFileToImportPath()` method):\n\n``` php \npublic function store(Request $request, MyModel $model)\n{\n    $model-\u003eaddFile($request-\u003efile);\n\n    \\Alfonsobries\\LaravelSpreadsheetImporter\\Jobs\\StartImport::dispatch($model);\n\n    // ...The rest of the code\n}\n```\n\nThat job will create and trigger the Node command, then the Node command will call the `ReportImporterProgress` artisan command every time has some progress to inform, finally the artisan command will trigger a `ImporterProgressEvent` that you can listen with your custom event listener or by adding `ImporterProgressEventListener` that comes in this package, that listener is responsible to store the progress of your import into your Model:\n\nTo configure the event listener add the following lines into your `app/Providers/EventServiceProvider.php`:\n\n``` php \nclass EventServiceProvider extends ServiceProvider\n{\n    /**\n     * The event listener mappings for the application.\n     *\n     * @var array\n     */\n    protected $listen = [\n        // Every time the importer has some progress\n        \\Alfonsobries\\LaravelSpreadsheetImporter\\Events\\ImporterProgressEvent =\u003e [\n            // (Or use your own event listener)\n            \\Alfonsobries\\LaravelSpreadsheetImporter\\Listeners\\ImporterProgressEventListener::class,\n        ],\n\n        // The `ImporterProgressEventListener` also creates the following observable events:\n        // When the import finished\n        \\Alfonsobries\\LaravelSpreadsheetImporter\\Events\\ImporterProgressFinishedEvent =\u003e [\n            // In this case you will need to define your own event listener \n        ],\n\n        // When the import reports an error:\n        \\Alfonsobries\\LaravelSpreadsheetImporter\\Events\\ImporterProgressErrorEvent =\u003e [\n            // In this case you will need to define your own event listener \n        ],\n    ];\n    // ...\n``` \n\n## Testing\n\nFor running the tests you will need to install the dependencies and have a valid testing database\n\n+ Install the composer packages `composer install`\n+ Because this package interacts with a database you will need to define a `.env` with a valid mysql or postgresql database data (use `env.example` as an example)\n+ Also you need to install the npm dependency `npm install`\n\n### Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n### Security\n\nIf you discover any security related issues, please email alfonso@vexilo.com instead of using the issue tracker.\n\n## Credits\n\n- [Alfonso Bribiesca](https://github.com/alfonsobries)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfonsobries%2Flaravel-spreadsheet-importer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falfonsobries%2Flaravel-spreadsheet-importer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfonsobries%2Flaravel-spreadsheet-importer/lists"}