Skip to content

Add excel shorthand for Excel-friendly UTF-8 exports#148

Merged
dereuromark merged 1 commit into
5.xfrom
feature-excel-preset
May 11, 2026
Merged

Add excel shorthand for Excel-friendly UTF-8 exports#148
dereuromark merged 1 commit into
5.xfrom
feature-excel-preset

Conversation

@dereuromark
Copy link
Copy Markdown
Member

Summary

Adds an excel config 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:

'bom' => true,
'eol' => "\r\n",
'csvEncoding' => 'UTF-8',

…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 => true shorthand collapses all three:

$this->viewBuilder()
    ->setClassName('CsvView.Csv')
    ->setOptions([
        'serialize' => 'data',
        'excel' => true,
    ]);

Other CSV options (delimiter, enclosure, setSeparator, header, extract, etc.) are independent and behave normally.

Implementation

  • New default config key: 'excel' => false.
  • New method _applyExcelPreset() that, when excel is truthy, calls setConfig() to force bom/eol/csvEncoding.
  • Called from _serialize() (not initialize()) so the preset takes effect regardless of when excel is set — including the test pattern of constructing the view and then calling setConfig().
  • README has a new "Excel-friendly UTF-8 export" section under Usage explaining the option and the equivalent individual settings.

Semantics

excel => true always wins for the three keys it controls. If a user wants a different combination (e.g. UTF-16, no BOM) they should NOT enable excel and set the individual keys themselves. Documented explicitly in the docblock and README.

Tests

Two new tests, all green:

  • testExcelPresetEmitsBomCrlfAndUtf8excel => true alone produces a UTF-8 BOM, CRLF line endings, and UTF-8 output.
  • testExcelPresetOverridesIndividualKeys — even when the user explicitly sets bom => false and eol => "\n", the preset still wins for those three keys (excel => true is a single switch by design).

Total: 19 tests, 37 assertions, all green locally; phpstan level 8 clean.

Notes on CI

The cs-stan job is expected to fail on this PR because of the pre-existing infrastructure issue that #147 is fixing (squizlabs/php_codesniffer v4 vs slevomat 8.29 incompatibility — reproducible on 5.x master). 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.

Comment thread src/View/CsvView.php Outdated
@dereuromark dereuromark force-pushed the feature-excel-preset branch from dbf5fc7 to 47a3e11 Compare May 11, 2026 18:28
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.
@dereuromark dereuromark force-pushed the feature-excel-preset branch from 47a3e11 to 628ce5d Compare May 11, 2026 19:15
@dereuromark dereuromark merged commit 7b69f8a into 5.x May 11, 2026
7 checks passed
@dereuromark dereuromark deleted the feature-excel-preset branch May 11, 2026 19:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants