Add excel shorthand for Excel-friendly UTF-8 exports#148
Merged
Conversation
ADmad
reviewed
May 11, 2026
ADmad
approved these changes
May 11, 2026
dbf5fc7 to
47a3e11
Compare
Microsoft Excel on Windows does not recognise a UTF-8 CSV unless it has a byte-order mark, CRLF line endings, and an explicit UTF-8 declaration. Users have had to remember and set all three options individually each time. This is a recurring source of "opens as mojibake" reports. Add a single `excel` config key (default false). When enabled, the view forces `bom => true`, `eol => "\r\n"`, and `csvEncoding => 'UTF-8'` at serialize time. The preset wins for those three keys; other CSV options (delimiter, enclosure, header, extract, setSeparator, etc.) are independent and behave normally. The preset runs in `_serialize()` rather than `initialize()` so it takes effect regardless of when `excel` is set, including the common test pattern of constructing the view and then calling `setConfig()`. README documents the new option under a new "Excel-friendly UTF-8 export" heading in the Usage section.
47a3e11 to
628ce5d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an
excelconfig shorthand that flips the three options Excel needs to open a UTF-8 CSV correctly on Windows: BOM, CRLF line endings, and UTF-8 encoding. Addresses recurring "opens as mojibake in Excel" reports (see #132).Why
Today users have to set three options individually:
…and remember to keep them in sync. Forgetting one is the most common reason a UTF-8 CSV opens as mojibake in Excel on Windows. The new
excel => trueshorthand collapses all three:Other CSV options (
delimiter,enclosure,setSeparator,header,extract, etc.) are independent and behave normally.Implementation
'excel' => false._applyExcelPreset()that, whenexcelis truthy, callssetConfig()to forcebom/eol/csvEncoding._serialize()(notinitialize()) so the preset takes effect regardless of whenexcelis set — including the test pattern of constructing the view and then callingsetConfig().Semantics
excel => truealways wins for the three keys it controls. If a user wants a different combination (e.g. UTF-16, no BOM) they should NOT enableexceland set the individual keys themselves. Documented explicitly in the docblock and README.Tests
Two new tests, all green:
testExcelPresetEmitsBomCrlfAndUtf8—excel => truealone produces a UTF-8 BOM, CRLF line endings, and UTF-8 output.testExcelPresetOverridesIndividualKeys— even when the user explicitly setsbom => falseandeol => "\n", the preset still wins for those three keys (excel => trueis a single switch by design).Total: 19 tests, 37 assertions, all green locally; phpstan level 8 clean.
Notes on CI
The
cs-stanjob is expected to fail on this PR because of the pre-existing infrastructure issue that #147 is fixing (squizlabs/php_codesniffer v4vsslevomat 8.29incompatibility — reproducible on5.xmaster). Nothing in this PR affects code style; merging #147 first (or rebasing this on top of it) will make CI green.Independent of the bug-fix PR (#146 / #147) and the streaming proposal from the earlier deep-dive review.