SpartnerNL/Laravel-Excel

This system is a Laravel Excel library that facilitates importing and exporting spreadsheet data through a typed, concern-based architecture. It supports various data sources including queries, collections, and Scout indexes, while offering robust features for batch processing, memory-efficient chunking, and queued job execution. The library provides comprehensive tools for data validation, formatting, and testing, ensuring reliable handling of large-scale spreadsheet operations within the Laravel ecosystem.

21 changes.

The project underwent a major architectural overhaul to decouple from legacy libraries, upgrade to PhpSpreadsheet v5, and enforce strict PHP 8.3 typing and static analysis. This period introduced a comprehensive concern-based interface for imports and exports, alongside robust testing infrastructure including fakes, assertions, and batch job support.

9 changes.

This period focused on expanding the library's core infrastructure by introducing new helper utilities, a file handling abstraction for remote storage, and a batch caching system. It also added configurable transaction management, data cleaning middleware, and convenient Laravel collection mixins to streamline import and export workflows.

5 changes.

The project refactored the export system to support extensible source handlers and introduced a comprehensive, type-safe column definition API for both exports and imports. This work included implementing specific handlers for various data sources and adding detailed unit tests to verify the new column types and disk resource handling.

Introduces two new read filters, \ChunkReadFilter\ and \LimitFilter\, to control memory usage during spreadsheet imports. \LimitFilter\ allows users to restrict the number of rows read into memory by specifying a start row and a limit, while also supporting an optional heading row. \ChunkReadFilter\ enables processing large files in batches by defining a start row, end row, and chunk size, ensuring only specific ranges of rows are loaded for each iteration.

src/Filters · high confidence

The Boost assistant now includes a dedicated skill for the \maatwebsite/excel\ package, providing structured guidelines, usage examples, and a comprehensive feature reference. This addition equips the assistant with specific rules for spreadsheet exports and imports, such as preferring dedicated export/import classes over ad-hoc controller logic, utilizing \FromQuery\ for large datasets, and leveraging \Excel::fake()\ for testing. Users interacting with spreadsheet-related tasks will now receive guidance aligned with these best practices, including handling queued operations, multi-sheet workbooks, and CSV settings.

resources · high confidence

The Excel facade introduces a \fake()\ method that swaps the underlying Excel instance with \ExcelFake\, enabling developers to intercept and verify Excel operations without performing actual file I/O. The facade's PHPDoc block has been expanded to include static method signatures for new testing assertions, such as \assertDownloaded\, \assertStored\, \assertQueued\, \assertQueuedWithChain\, \assertExportedInRaw\, and \assertImported\, allowing tests to verify that exports and imports were triggered with specific parameters.

src/Facades · high confidence

The library now uses an extensible registry of handlers to process different export data sources, replacing the previous monolithic approach. New contracts \SheetSourceHandler\ and \QueuedSheetSourceHandler\ define the interface for handling exports, with specific implementations provided for \FromArray\, \FromCollection\, \FromGenerator\, \FromIterator\, \FromQuery\, \FromScout\, and \FromView\. This structure allows users to register custom handlers for new data sources or override existing behavior by implementing these interfaces, making the export system more modular and open to extension.

src/Contracts, src/Handlers · high confidence

Adds the \config/excel.php\ file, providing a centralized configuration for the Excel package. This allows users to customize export settings such as chunk size, formula pre-calculation, and strict null comparison, as well as import behaviors like read-only mode, empty row handling, heading row formatting, and CSV parsing options. It also exposes configuration for worksheet properties, custom source handlers, and cell middleware.

config · high confidence

The library now uses a new \Files\ namespace containing a \Disk\ wrapper, a \Filesystem\ factory, and distinct \LocalTemporaryFile\ and \RemoteTemporaryFile\ classes to manage temporary storage. This change introduces support for storing temporary files on remote disks (via a configurable \temporary\_disk\ setting) in addition to local storage, with automatic synchronization between local and remote copies. It also adds configuration options for local file and directory permissions, handles concurrent directory creation, and ensures remote temporary files are correctly managed during import and export operations.

src/Files · high confidence

Adds the ExcelFake class and a dummy fake\_file asset to the src/Fakes directory, enabling users to mock Excel export and import operations during testing. The fake implements the Exporter and Importer interfaces, allowing assertions on downloads, stored files, queued jobs, and raw content, while also supporting batchable jobs and UploadedFile objects for imports.

src/Fakes · high confidence

Added new mixin classes in src/Mixins that extend Laravel's Collection and Eloquent Builder with convenient methods for Excel operations. Users can now call downloadExcel() and storeExcel() on Collections to export data to Excel files, with an optional withHeadings parameter to automatically generate column headers from the first row. Similarly, Eloquent models gain downloadQuery() and storeQuery() macros to export query results directly to Excel, and import macros (import(), importAs()) to import Excel files into models, supporting both automatic mapping via heading rows and custom mapping callbacks.

src/Mixins · high confidence

Users can now generate new import and export classes directly from the command line using the \make:import\ and \make:export\ commands. These commands create skeleton classes in the \Imports\ and \Exports\ namespaces respectively, supporting options to scaffold models (e.g., \--model\) and query-based implementations. The generated code includes appropriate interfaces (\ToModel\, \FromCollection\, \FromQuery\) and handles namespace resolution, with support for custom stubs via the \WithModelStub\ trait.

src/Console · high confidence

The cache layer now supports a new 'batch' driver that combines an in-memory cache with a persistent store (such as Illuminate's cache) to optimize performance during large Excel exports. This system introduces a configurable \default\_ttl\ setting for cache entries and enforces a \memory\_limit\ to automatically flush data to the persistent store when memory usage peaks, preventing excessive RAM consumption. To maintain compatibility with older environments, the implementation provides separate typed and untyped classes depending on the installed \psr/simple-cache\ version.

src/Cache · high confidence

The \src/Concerns\ directory now includes a comprehensive set of new interfaces and traits that define how exports and imports behave. For exports, the \Export\ interface and \Exportable\ trait provide the core methods for downloading, storing, queuing, and generating raw output, while specific data source interfaces like \FromArray\, \FromCollection\, \FromQuery\, \FromScout\, and \FromView\ allow users to define where their data comes from. Import functionality is similarly structured with the \Import\ interface and \Importable\ trait, alongside data handling interfaces like \ToModel\, \ToArray\, and \OnEachRow\. The update also introduces numerous configuration concerns for formatting (\WithColumnFormatting\, \WithStyles\), error handling (\SkipsErrors\, \SkipsFailures\), and advanced features like chunking (\WithChunkReading\), validation (\WithValidation\), and sheet management (\WithMultipleSheets\, \WithConditionalSheets\).

src/Concerns · high confidence

Added several new helper classes in src/Helpers to support core library functionality. ArrayHelper provides methods to normalize single-row arrays into multiple rows for consistent export/import handling. CellHelper extracts column letters from cell coordinates. ConcernTree safely flattens the tree of Export/Import concerns (including WithMultipleSheets) while preventing infinite recursion from identity or class-level cycles. FileTypeDetector identifies file types from paths or UploadedFile instances, throwing an exception if the type cannot be determined. QueueResolver reads \#\[Queue\] and \#\[Connection\] attributes (or falls back to properties) to determine where to dispatch import jobs. RichTextReader converts PhpSpreadsheet RichText cells into HTML, preserving formatting like bold, italic, underline, strikethrough, superscript, subscript, color, font family, and size.

src/Helpers · high confidence

The import engine has been refactored into a new set of classes (EndRowFinder, HeadingRowExtractor, HeadingRowFormatter, ModelImporter, ModelManager, CascadePersistManager) that enable row-level validation, batch inserts, and upsert operations. Users can now configure heading row formatting (slug or none), define start/end rows and column limits, and utilize concerns like WithBatchInserts, WithUpserts, and WithSkipDuplicates to control how data is persisted to the database, including cascading related models during mass imports.

src/Imports · high confidence

Users can now apply middleware to clean up cell data during import. The new TrimCellValue middleware removes leading/trailing whitespace, BOMs, and zero-width spaces from string values, while ConvertEmptyCellValuesToNull replaces empty strings with null. These are built on a new abstract CellMiddleware base class that defines the invocation contract.

src/Middleware · high confidence

The \src/Columns\ directory now contains a comprehensive set of column definition classes (Boolean, Date, DateTime, Decimal, Enum, Formula, Hyperlink, Image, Number, Percentage, Price, RichText, Text, Time) and supporting traits (Commentable, Filterable, Readable, Sizeable, Styleable, Writeable). This introduces a structured, type-safe approach to defining column behavior, allowing users to specify data types, formatting, styling, and reading/writing logic directly in column definitions rather than relying on sheet-level concerns alone.

src/Columns · high confidence

The library now supports configurable database transaction management for Excel operations, allowing users to enable or disable transactions and specify the database connection via the \excel.transactions\ configuration section. This change introduces a new \TransactionManager\ that selects between a \DbTransactionHandler\ (which wraps operations in a database transaction using the configured connection) and a \NullTransactionHandler\ (which executes callbacks without transactional overhead), replacing the previous hardcoded or implicit transaction behavior.

src/Transactions · high confidence

The library now centralizes reader and writer creation in new \ReaderFactory\ and \WriterFactory\ classes. For imports, \ReaderFactory\ handles CSV-specific settings (delimiter, enclosure, encoding), respects \WithReadFilter\ or \WithLimit\ constraints (including heading row logic), and manages read-only mode and empty cell handling. For exports, \WriterFactory\ configures disk caching, enables chart inclusion when \WithCharts\ is used, ensures all sheets are written for HTML exports with \WithMultipleSheets\, and applies CSV settings including automatic TSV detection and output encoding.

src/Factories · high confidence

This release upgrades the underlying PhpSpreadsheet dependency from ^1.30 to ^5.3 and raises the minimum requirements to PHP 8.3 and Laravel 12. The codebase is now fully typed with native parameter and return types, and static analysis is enforced at PHPStan level 6. New capabilities include the \WithColumns\ concern for typed column definitions, the \FromScout\ export interface (replacing Scout builder support in \FromQuery\), and the \ShouldBatch\ marker interface for dispatching jobs as Laravel job batches. Additionally, imports can now use Laravel's native \\#\[Queue\]\ and \\#\[Connection\]\ attributes, and the \ext-json\ requirement has been dropped.

(repo-wide) · high confidence

This release replaces the legacy PhpExcel library with PHPSpreadsheet v5, bringing modern PHP 8.3 compatibility, native types, and readonly properties throughout the codebase. The architecture is significantly refactored to decouple core components, introducing a new \HandlerRegistry\ for extensible export source handling, a dedicated \ChunkReader\ for memory-efficient batch imports, and a comprehensive event system (\BeforeImport\, \AfterBatch\, etc.) for better lifecycle control. Users benefit from improved performance, reduced memory usage during large imports/exports, and a more robust, testable foundation.

src · high confidence

The library now introduces a dedicated set of exception classes in the \src/Exceptions\ directory to provide clearer, context-specific error reporting for users. New types include \ColumnCollisionException\ for duplicate column assignments, \ConcernConflictException\ for incompatible export concerns (such as mixing \FromQuery\ with \FromView\ or \WithColumns\ with \WithMapping\), and \SheetNotFoundException\ for invalid sheet references. Additionally, \NoFilePathGivenException\ and \NoFilenameGivenException\ offer distinct errors for missing file paths versus missing download filenames, while \RowSkippedException\ now exposes detailed validation failures via a \failures()\ collection. These changes replace generic errors with specific, actionable messages that help users quickly identify and resolve configuration issues during imports and exports.

src/Exceptions · high confidence

The \src/Jobs\ directory has been refactored to use a new set of queueable job classes (such as \QueueExport\, \QueueImport\, \ReadChunk\, and \AppendQueryToSheet\) that implement Laravel's \Batchable\ trait. This change allows queued spreadsheet operations to be tracked in batches and supports batch cancellation, ensuring that jobs can be stopped if the parent batch is cancelled. Additionally, the new jobs include a \LocalizeJob\ middleware to handle locale settings and specific failure handling via the \ProxyFailures\ trait and \ImportFailed\ events.

src/Jobs · high confidence

The validator now exposes detailed, per-row failure information via a new \Failure\ class that implements \JsonSerializable\, allowing validation errors to be serialized to JSON. The \ValidationException\ has been updated to include a \failures()\ method that returns these structured failure objects, and the \RowValidator\ now captures the original row values alongside errors, enabling users to inspect exactly which data caused the validation to fail.

src/Validators · high confidence

Added comprehensive test suite for Excel library components; Added database model factories for testing; Added test coverage for import and export concerns; Added test fixtures for disk-based import scenarios; Added test stubs for group-related database migrations; Added tests for Disk resource handling; Added tests for Helpers (ConcernTree, FileTypeDetector, RichTextReader); Added tests for RowValidator rule formatting; Added tests for collection and query Excel macros; Added unit tests for the Cache subsystem; Added unit tests for the new Column types and API; Expanded test stubs for queued exports, imports, and concerns.

The package now requires PHP 8.3 and supports Laravel 12.0 or 13.0, upgrading the underlying spreadsheet library to PhpSpreadsheet ^5.9. Development tooling has been updated to use Laravel Pint for code style, PHPUnit 12/13 for testing, and Larastan 3 for static analysis, ensuring compatibility with modern Laravel versions and PHP standards.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 51 → 71 (+20.2)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 97 → 94 (-3.0)
• Architecture 94 → 97 (+3.2)
• Maturity 57 → 57 (-0.4)
• Readiness 25 → 70 (+44.9)
• Security 83 → 98 (+15.2)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• Duplicated block (5 lines × 2) (src/Concerns/MapsCsvSettings.php)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• No exposed public API
• No tests found
• Test reliability not included

• ChunkReader.read (cognitive 18) (src/ChunkReader.php)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 2) (src/Console/ExportMakeCommand.php)
• Duplicated block (18 lines × 2) (src/Fakes/ExcelFake.php)
• Duplicated block (33 lines × 2) (src/Mixins/DownloadCollectionMixin.php)
• Duplicated block (39 lines × 2) (src/Mixins/DownloadQueryMacro.php)
• Duplicated block (59 lines × 2) (src/Cache/MemoryCache.php)
• Duplicated block (67 lines × 2) (src/Cache/BatchCache.php)
• Duplicated block (8 lines × 3) (src/Jobs/AppendDataToSheet.php)
• Hotspot: src/Imports/ModelImporter.php (src/Imports/ModelImporter.php)
• Hotspot: src/Sheet.php (src/Sheet.php)
• ModelImporter.import (cognitive 29) (src/Imports/ModelImporter.php)
• ModelImporter.import (cyclomatic 18) (src/Imports/ModelImporter.php)
• No dependency advisory monitoring
• Off-boarding risk: anonymized user #1
• Outdated: composer/semver
• Outdated: phpoffice/phpspreadsheet
• Repeated repair: src/Jobs/AppendQueryToSheet.php (src/Jobs/AppendQueryToSheet.php)
• Secret: generic-api-key (.travis.yml)
• …and 8 more

• 21 commits — 16 feature/other, 5 fixes

• src/Concerns — 4 commits
• tests/Concerns — 4 commits
• (root) — 3 commits
• src/Columns — 2 commits
• (repo) — 1 commit
• config/excel.php — 1 commit
• src/Cache — 1 commit
• src/Factories — 1 commit
• src/Fakes — 1 commit
• src/Files — 1 commit
• src/Handlers — 1 commit
• src/Sheet.php — 1 commit

• fix: Fix Excel::fake() not working with ShouldBatch (#4425)
• fix: Fix infinite recursion when WithMultipleSheets references itself in sheets() (#4429)
• fix: Fix: FromScout does not close the sheet (#4413)
• fix: fix: initialize RemembersChunkOffset/RemembersRowNumber properties to null (#4431)
• fix: fix: make LimitFilter respect heading row and align start/end with reader (#4423)
• change: Add tests for WithCharts, WithDrawings and download buffer handling (#4427)
• change: Adjust phpdoc types/generics to add defaults and correct contravariant typing on WithMapping (#4422)
• change: Improve test coverage (#4426)
• change: Make OnEachRow extend Import (#4412)
• change: Merge branch '3.1' into 4.x
• change: Move stream copy into the disk so flystem handles it instead
• change: Refactor BatchCache and add tests (#4433)
• change: Replace deprecated SplObjectStorage::contains/attaach with offsetExis… (#4434)
• change: Resolve relative import paths against the disk before the working directory
• change: Update README.md
• change: Update composer.json
• change: Update upgrade guide with WithMultipleSheets (#4421)
• change: [4.x] Add Time/Enum column types and sheet-level concerns (#4417)
• change: [4.x] Add column definitions for exports and imports (#4416)
• change: [4.x] Configuration from environment (#4418)
• …and 1 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

SpartnerNL/Laravel-Excel was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.