Not only does it reduce the risk of typos; but at some point in the future, ExcelError values will be an object rather than a string, and we won't then need to update all the tests. - Don't over-complicate test code by testing happy and unhappy paths in the same test. This makes it easier to see exactly what is being tested when reviewing the PR. I want to be able to see it in the PR, not have to hunt in other unchanged classes to see what the test is doing. ## How to release 1. Complete CHANGELOG.md and commit 2. Create an annotated tag 1. `git tag -a 1.2.3` 2. Tag subject must be the version number, eg: `1.2.3` 3. Tag body must be a copy-paste of the changelog entries. 3. Push the tag with `git push --tags`, GitHub Actions will create a GitHub release automatically, and the release details will automatically be sent to packagist. 4. By default, Github removes markdown headings in the Release Notes. You can either edit to restore these, or, probably preferably, change the default comment character on your system - `git config core.commentChar ";"`. > **Note:** Tagged releases are made from the `master` branch. Only in an emergency should a tagged release be made from the `release` branch. (i.e. cherry-picked hot-fixes.) However, there are 4 branches which have been updated to apply security patches, and those may be tagged if future security updates are needed. - 1.30.x (no further updates aside from security patches, including code changes needed for Php 8.5 compatibility) - 2.1.x (no further updates aside from security patches, including code changes needed for Php 8.5 compatibility) - 2.4.x - 3.10.x ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2019-2026 PhpSpreadsheet Authors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # PhpSpreadsheet [](https://github.com/PHPOffice/PhpSpreadsheet/actions) [](https://coveralls.io/github/PHPOffice/PhpSpreadsheet?branch=master) [](https://packagist.org/packages/phpoffice/phpspreadsheet) [](https://packagist.org/packages/phpoffice/phpspreadsheet) [](https://packagist.org/packages/phpoffice/phpspreadsheet) [](https://gitter.im/PHPOffice/PhpSpreadsheet) PhpSpreadsheet is a library written in pure PHP and offers a set of classes that allow you to read and write various spreadsheet file formats such as Excel and LibreOffice Calc. This is the master branch, and is maintained for security and bug fixes. ## PHP Version Support LTS: For maintained branches, support for PHP versions will only be maintained for a period of six months beyond the [end of life](https://www.php.net/supported-versions) of that PHP version. Currently the required PHP minimum version is PHP __8.1__, and we [will support that version](https://www.php.net/supported-versions.php) until 30th June 2026. See the `composer.json` for other requirements. ## Installation See the [install instructions](https://phpspreadsheet.readthedocs.io/en/latest/#installation). ## Documentation Read more about it, including install instructions, in the [official documentation](https://phpspreadsheet.readthedocs.io). Or check out the [API documentation](https://phpoffice.github.io/PhpSpreadsheet). Please ask your support questions on [StackOverflow](https://stackoverflow.com/questions/tagged/phpspreadsheet), or have a quick chat on [Gitter](https://gitter.im/PHPOffice/PhpSpreadsheet). ## Patreon I am now running a [Patreon](https://www.patreon.com/MarkBaker) to support the work that I do on PhpSpreadsheet. Supporters will receive access to articles about working with PhpSpreadsheet, and how to use some of its more advanced features. Posts already available to Patreon supporters: - The Dating Game - A look at how MS Excel (and PhpSpreadsheet) handle date and time values. - Looping the Loop - Advice on Iterating through the rows and cells in a worksheet. And for Patrons at levels actively using PhpSpreadsheet: - Behind the Mask - A look at Number Format Masks. The Next Article (currently Work in Progress): - Formula for Success - How to debug formulae that don't produce the expected result. My aim is to post at least one article each month, taking a detailed look at some feature of MS Excel and how to use that feature in PhpSpreadsheet, or on how to perform different activities in PhpSpreadsheet. Planned posts for the future include topics like: - Tables - Structured References - AutoFiltering - Array Formulae - Conditional Formatting - Data Validation - Value Binders - Images - Charts After a period of six months exclusive to Patreon supporters, articles will be incorporated into the public documentation for the library. ## PHPExcel vs PhpSpreadsheet ? PhpSpreadsheet is the next version of PHPExcel. It breaks compatibility to dramatically improve the code base quality (namespaces, PSR compliance, use of latest PHP language features, etc.). Because all efforts have shifted to PhpSpreadsheet, PHPExcel will no longer be maintained. All contributions for PHPExcel, patches and new features, should target PhpSpreadsheet `master` branch. Do you need to migrate? There is [an automated tool](/docs/topics/migration-from-PHPExcel.md) for that. ## License PhpSpreadsheet is licensed under [MIT](https://github.com/PHPOffice/PhpSpreadsheet/blob/master/LICENSE). ================================================ FILE: bin/check-phpdoc-types.php ================================================ #!/usr/bin/env php generateLocales(); ================================================ FILE: bin/pre-commit ================================================ #!/bin/bash pass=true files=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(php|phtml)$') if [ "$files" != "" ]; then # Run php syntax check before commit while read -r file; do php -l "$file" if [ $? -ne 0 ]; then pass=false fi done <<< "$files" # Run php-cs-fixer validation before commit echo "$files" | xargs ./vendor/bin/php-cs-fixer fix --diff --config .php-cs-fixer.dist.php if [ $? -ne 0 ]; then pass=false fi # Automatically add files that may have been fixed by php-cs-fixer echo "$files" | xargs git add fi # Check PHPDoc types ./bin/check-phpdoc-types.php if [ $? -ne 0 ]; then pass=false fi if $pass; then exit 0 else echo "" echo "PRE-COMMIT HOOK FAILED:" echo "Code style validation failed. Please fix errors and try committing again." exit 1 fi ================================================ FILE: composer.json ================================================ { "name": "phpoffice/phpspreadsheet", "description": "PHPSpreadsheet - Read, Create and Write Spreadsheet documents in PHP - Spreadsheet engine", "keywords": [ "PHP", "OpenXML", "Excel", "xlsx", "xls", "ods", "gnumeric", "spreadsheet" ], "config": { "platform": { "php" : "8.1.99" }, "process-timeout": 600, "sort-packages": true, "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true } }, "homepage": "https://github.com/PHPOffice/PhpSpreadsheet", "type": "library", "license": "MIT", "authors": [ { "name": "Maarten Balliauw", "homepage": "https://blog.maartenballiauw.be" }, { "name": "Mark Baker", "homepage": "https://markbakeruk.net" }, { "name": "Franck Lefevre", "homepage": "https://rootslabs.net" }, { "name": "Erik Tilt" }, { "name": "Adrien Crivelli" }, { "name": "Owen Leibman" } ], "scripts": { "check": [ "php bin/check-phpdoc-types.php", "phpcs samples/ src/ tests/ --report=checkstyle", "phpcs samples/ src/ tests/ --standard=PHPCompatibility --runtime-set testVersion 8.0- --exclude=PHPCompatibility.Variables.ForbiddenThisUseContexts -n", "php-cs-fixer fix --ansi --dry-run --diff", "phpstan analyse --ansi --memory-limit=2048M", "phpunit --color=always" ], "style": [ "phpcs samples/ src/ tests/ --report=checkstyle", "php-cs-fixer fix --ansi --dry-run --diff" ], "fix": [ "phpcbf samples/ src/ tests/ --report=checkstyle", "php-cs-fixer fix" ], "versions": [ "phpcs samples/ src/ tests/ --standard=PHPCompatibility --runtime-set testVersion 8.0- --exclude=PHPCompatibility.Variables.ForbiddenThisUseContexts -n" ] }, "require": { "php": "^8.1", "ext-ctype": "*", "ext-dom": "*", "ext-fileinfo": "*", "ext-filter": "*", "ext-gd": "*", "ext-iconv": "*", "ext-libxml": "*", "ext-mbstring": "*", "ext-simplexml": "*", "ext-xml": "*", "ext-xmlreader": "*", "ext-xmlwriter": "*", "ext-zip": "*", "ext-zlib": "*", "composer/pcre": "^1||^2||^3", "maennchen/zipstream-php": "^2.1 || ^3.0", "markbaker/complex": "^3.0", "markbaker/matrix": "^3.0", "psr/simple-cache": "^1.0 || ^2.0 || ^3.0" }, "require-dev": { "ext-intl": "*", "dealerdirect/phpcodesniffer-composer-installer": "dev-main", "dompdf/dompdf": "^2.0 || ^3.0", "friendsofphp/php-cs-fixer": "^3.2", "mitoteam/jpgraph": "^10.5", "mpdf/mpdf": "^8.1.1", "phpcompatibility/php-compatibility": "^9.3", "phpstan/phpstan": "^1.1 || ^2.0", "phpstan/phpstan-deprecation-rules": "^1.0 || ^2.0", "phpstan/phpstan-phpunit": "^1.0 || ^2.0", "phpunit/phpunit": "^10.5", "squizlabs/php_codesniffer": "^3.7", "tecnickcom/tcpdf": "^6.5" }, "suggest": { "ext-intl": "PHP Internationalization Functions, required for NumberFormat Wizard and StringHelper::setLocale()", "mpdf/mpdf": "Option for rendering PDF with PDF Writer", "dompdf/dompdf": "Option for rendering PDF with PDF Writer", "tecnickcom/tcpdf": "Option for rendering PDF with PDF Writer", "mitoteam/jpgraph": "Option for rendering charts, or including charts with PDF or HTML Writers" }, "autoload": { "psr-4": { "PhpOffice\\PhpSpreadsheet\\": "src/PhpSpreadsheet" } }, "autoload-dev": { "psr-4": { "PhpOffice\\PhpSpreadsheetTests\\": "tests/PhpSpreadsheetTests", "PhpOffice\\PhpSpreadsheetInfra\\": "infra" } } } ================================================ FILE: docs/extra/extra.css ================================================ /* Make the huge table always visible */ table.features-cross-reference { overflow: visible !important; } .rst-content table.features-cross-reference.docutils th, .rst-content table.features-cross-reference.docutils td { background-color: white; } /* https://github.com/mkdocs/mkdocs/discussions/3035#discussioncomment-7237037 */ .wy-table-responsive table td, .wy-table-responsive table th { white-space: normal !important; } .wy-table-responsive { overflow : visible !important; } /* https://github.com/readthedocs/sphinx_rtd_theme/issues/295#issuecomment-455226058 */ .wy-nav-content {max-width: none;} ================================================ FILE: docs/extra/extrajs.js ================================================ document.addEventListener("DOMContentLoaded", function() { document.querySelectorAll("table").forEach(function(table) { table.classList.add("docutils"); }); }); ================================================ FILE: docs/faq.md ================================================ # Frequently asked questions ## There seems to be a problem with character encoding... It is necessary to use UTF-8 encoding for all texts in PhpSpreadsheet. If the script uses different encoding then you can convert those texts with PHP's `iconv()` or `mb_convert_encoding()` functions. ## Fatal error: Allowed memory size of xxx bytes exhausted (tried to allocate yyy bytes) in zzz on line aaa PhpSpreadsheet holds an "in memory" representation of a spreadsheet, so it is susceptible to PHP's memory limitations. The memory made available to PHP can be increased by editing the value of the `memory_limit` directive in your `php.ini` file, or by using `ini_set('memory_limit', '128M')` within your code. Some Readers and Writers are faster than others, and they also use differing amounts of memory. ## Protection on my worksheet is not working? When you make use of any of the worksheet protection features (e.g. cell range protection, prohibiting deleting rows, ...), make sure you enable worksheet security. This can for example be done like this: ```php $spreadsheet->getActiveSheet()->getProtection()->setSheet(true); ``` ## Feature X is not working with Reader\_Y / Writer\_Z Not all features of PhpSpreadsheet are implemented in all of the Reader / Writer classes. This is mostly due to underlying libraries not supporting a specific feature or not having implemented a specific feature. For example autofilter is not implemented in PEAR Spreadsheet\_Excel\_writer, which is the base of our Xls writer. We are slowly building up a list of features, together with the different readers and writers that support them, in the [features cross reference](./references/features-cross-reference.md). ## Formulas don't seem to be calculated in Excel2003 using compatibility pack? This is normal behaviour of the compatibility pack, `Xlsx` displays this correctly. Use `\PhpOffice\PhpSpreadsheet\Writer\Xls` if you really need calculated values, or force recalculation in Excel2003. ## Setting column width is not 100% accurate Trying to set column width, I experience one problem. When I open the file in Excel, the actual width is 0.71 less than it should be. The short answer is that PhpSpreadsheet uses a measure where padding is included. See [how to set a column's width](./topics/recipes.md#setting-a-columns-width) for more details. ## I cannot serialize or json_encode my Spreadsheet No, you can't. Consider the Spreadsheet object as a PHP resource, which cannot be serialized. ================================================ FILE: docs/index.md ================================================ # Welcome to PhpSpreadsheet's documentation  PhpSpreadsheet is a library written in pure PHP and offers a set of classes that allow you to read and write various spreadsheet file formats such as Excel and LibreOffice Calc. ## File formats supported |Format |Reading|Writing| |--------------------------------------------|:-----:|:-----:| |Open Document Format/OASIS (.ods) | ✓ | ✓ | |Office Open XML (.xlsx) Excel 2007 and above| ✓ | ✓ | |BIFF 8 (.xls) Excel 97 and above | ✓ | ✓ | |BIFF 5 (.xls) Excel 95 | ✓ | | |SpreadsheetML (.xml) Excel 2003 | ✓ | | |Gnumeric | ✓ | | |HTML | ✓ | ✓ | |SYLK | ✓ | | |CSV | ✓ | ✓ | |PDF (using either the TCPDF, Dompdf or mPDF libraries, which need to be installed separately)| | ✓ | Note - reading or writing certain aspects of a spreadsheet may not be supported in all formats. For more details, please consult [Features Cross-reference](./references/features-cross-reference.md). # Getting started ## Software requirements PHP version 8.1 or newer to develop using PhpSpreadsheet. Other requirements, such as PHP extensions, are enforced by composer. See the `require` section of [the composer.json file](https://github.com/PHPOffice/PhpSpreadsheet/blob/master/composer.json) for details. ### PHP version support LTS: Support for PHP versions will only be maintained for a period of six months beyond the [end of life of that PHP version](https://www.php.net/eol.php). Currently, the required PHP minimum version is __PHP 8.1__, and we [will support that version](https://www.php.net/eol.php) until June 2026. Support for PHP versions will only be maintained for a period of six months beyond the [end of life](https://www.php.net/supported-versions) of that PHP version. See the `composer.json` for other requirements. ## Installation Use [composer](https://getcomposer.org) to install PhpSpreadsheet into your project: ```sh composer require phpoffice/phpspreadsheet ``` Or also download the documentation and samples if you plan to use them (note that `git` must be in your path for this to work): ```sh composer require phpoffice/phpspreadsheet --prefer-source ``` If you are building your installation on a development machine that is on a different PHP version to the server where it will be deployed, or if your PHP CLI version is different from your run-time such as `php-fpm` or Apache's `mod_php`, then you might want to configure composer for that. See [composer documentation](https://getcomposer.org/doc/06-config.md#platform) on how to edit your `composer.json` to ensure that the correct dependencies are retrieved to match your deployment environment. See [CLI vs Application run-time](https://php.watch/articles/composer-platform-check) for more details. ### Additional Installation Options If you want to write to PDF, or to include Charts when you write to HTML or PDF, then you will need to install additional libraries: #### PDF For PDF Generation, you can install any of the following, and then configure PhpSpreadsheet to indicate which library you are going to use: - mpdf/mpdf - dompdf/dompdf - tecnickcom/tcpdf and configure PhpSpreadsheet using: ```php // Dompdf, Mpdf or Tcpdf (as appropriate) $className = \PhpOffice\PhpSpreadsheet\Writer\Pdf\Dompdf::class; IOFactory::registerWriter('Pdf', $className); ``` or the appropriate PDF Writer wrapper for the library that you have chosen to install. #### Chart Export For Chart export, we support following packages, which you will also need to install yourself using `composer require` - [jpgraph/jpgraph](https://packagist.org/packages/jpgraph/jpgraph) (this package was abandoned at version 4.0. You can manually download the latest version that supports PHP 8 and above from [jpgraph.net](https://jpgraph.net/)) - [mitoteam/jpgraph](https://packagist.org/packages/mitoteam/jpgraph) - up to date fork with modern PHP versions support and some bugs fixed. and then configure PhpSpreadsheet using: ```php // to use jpgraph/jpgraph Settings::setChartRenderer(\PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph::class); //or // to use mitoteam/jpgraph Settings::setChartRenderer(\PhpOffice\PhpSpreadsheet\Chart\Renderer\MtJpGraphRenderer::class); ``` One or the other of these libraries is necessary if you want to generate HTML or PDF files that include charts; or to render a Chart to an Image format from within your code. They are not necessary to define charts for writing to `Xlsx` files. Other file formats don't support writing Charts. ## Hello World This would be the simplest way to write a spreadsheet: ```php getActiveSheet(); $activeWorksheet->setCellValue('A1', 'Hello World !'); $writer = new Xlsx($spreadsheet); $writer->save('hello world.xlsx'); ``` ## Learn by example A good way to get started is to run some of the samples. Don't forget to download them via `--prefer-source` composer flag. And then serve them via PHP built-in webserver: ```sh php -S localhost:8000 -t vendor/phpoffice/phpspreadsheet/samples ``` Then point your browser to: > http://localhost:8000/ The samples may also be run directly from the command line, for example: ```sh php vendor/phpoffice/phpspreadsheet/samples/Basic/01_Simple.php ``` ## Learn by documentation For more documentation in depth, you may read about an [overview of the architecture](./topics/architecture.md), [creating a spreadsheet](./topics/creating-spreadsheet.md), [worksheets](./topics/worksheets.md), [accessing cells](./topics/accessing-cells.md) and [reading and writing to files](./topics/reading-and-writing-to-file.md). Or browse the [API documentation](https://phpoffice.github.io/PhpSpreadsheet). # Credits Please refer to the [contributor list](https://github.com/PHPOffice/PhpSpreadsheet/graphs/contributors) for up-to-date credits. ================================================ FILE: docs/references/features-cross-reference.md ================================================ # Features cross reference - ✔ Supported - ● Partially supported - ✖ Not supported - N/A Cannot be supported ## Readers
| Readers | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| XLS | XLSX | Excel2003XML | Ods | Gnumeric | CSV | SYLK | HTML | ||
| Reader Options | ✔ | ✔ | ● | ● | ✔ | N/A | N/A | ✔ | |
| Read Charts | ✖ | ✔ | ✖ | ✖ | ✖ | N/A | N/A | ✖ | |
| Read Data Only (no formatting) | ✔ | ✔ | ✖ | ✔ | ✔ | N/A | N/A | ✔ | |
| Read Only Specified Worksheets | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Read Only Specified Cells | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✔ | |
| Read External Images | ✖ | ✔ 9 | ✖ | ✖ | ✖ | N/A | N/A | ✔ 9 | |
| Document Properties | ● | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Standard Properties | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Creator | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Creation Date/Time | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Modifier | ✔ | ✔ | ✔ | N/A | N/A | N/A | N/A | ✔ | |
| Modified Date/Time | ✔ | ✔ | ✔ | ✔ | N/A | N/A | N/A | ✔ | |
| Title | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Description | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Subject | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Keywords | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Extended Properties | ✔ | ✔ | ✔ | N/A | ✔ | N/A | N/A | ✔ | |
| Category | ✔ | ✔ | ✔ | N/A | ✔ | N/A | N/A | ✔ | |
| Company | ✔ | ✔ | ✔ | N/A | ✔ | N/A | N/A | ✔ | |
| Manager | ✔ | ✔ | ✔ | N/A | ✔ | N/A | N/A | ✔ | |
| User-Defined (Custom) Properties | ✖ | ✔ | ✔ | ✔ | N/A | N/A | N/A | ✔ | |
| Text Properties | ✖ | ✔ | ✔ | ✔ | N/A | N/A | N/A | ✔ | |
| Number Properties | ✖ | ✔ | ✔ | ✔ | N/A | N/A | N/A | ✔ | |
| Date Properties | ✖ | ✔ | ✔ | ✔ | N/A | N/A | N/A | ✔ | |
| Yes/No (Boolean) Properties | ✖ | ✔ | ✔ | ✔ | N/A | N/A | N/A | ✔ | |
| Cell Data Types | |||||||||
| Empty/NULL | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Boolean | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Integer | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Floating Point | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| String | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Error | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Formula | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✔ | ✖ | |
| Array Formula | ✖ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | N/A | |
| Rich Text | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | |
| Conditional Formatting | ✔ | ✔ | ✖ | ✖ | ✖ | N/A | N/A | ✖ | |
| Rows and Column Properties | ✔ | ✔ | ✔ | ✖ | ✔ | N/A | N/A | ✔ | |
| Row Height/Column Width | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | ✔ | |
| Hidden | ✔ | ✔ | ✔ | ✖ | ✔ | N/A | N/A | ✔ | |
| Worksheet Properties | ● | ✔ | ● | ● | ✖ | N/A | N/A | ● | |
| Frozen Panes | ✔ | ✔ | ✔ | ✖ | ✖ | N/A | N/A | N/A | |
| Hidden Worksheets | ✔ | ✔ | ✖ | ✔ | ✖ | N/A | N/A | ● | |
| Coloured Tabs | ✖ | ✔ | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| Drawing hyperlink | ✖ | ✔ | ✖ | ✖ | ✖ | N/A | N/A | ✔ | |
| Cell Formatting | ✔ | ✔ | ● | ✖ | ✔ | N/A | ● | ● 7 | |
| Number Format Mask | ✔ | ✔ | ✔ | ● 6 | ✔ | N/A | ✔ | ✔ | |
| Alignment | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ● 7 | |
| Horizontal | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ✔ | |
| Vertical | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ✔ | |
| Wrapping | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ● | |
| Shrink-to-Fit | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ● | |
| Indent | ✔ | ✔ | ✖ | ✔ | ✔ | N/A | ✖ | ✔ | |
| Background Colour | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ● 7 | |
| Patterned | ✔ | ✔ | ✔ | N/A | ✔ | N/A | ✔ | ✖ | |
| Font Attributes | ✔ | ✔ | ✔ | ● | ✔ | N/A | ✔ | ● 7 | |
| Font Face | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Font Size | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Bold | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Italic | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Strikethrough | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Underline | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Superscript | ✔ | ✔ | ✔ | ✖ | ✔ | N/A | ✔ | ✔ | |
| Subscript | ✔ | ✔ | ✔ | ✖ | ✔ | N/A | ✔ | ✔ | |
| Borders | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ● | ● 7 | |
| Line Style | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Position | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Diagonal | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ✖ | |
| Hyperlinks | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ | ✖ | ✔ | |
| http | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ✔ | |
| Merged Cells | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | ✖ | ✔ | |
| Cell Comments | ● | ● | ● | ● | ● | N/A | ● | ● | |
| Rich Text | ✖ 2 | ✔ | ✖ | ✖ | ● | N/A | N/A | ✖ | |
| Alignment | ✖ 3 | ✔ | ✖ | ✖ | ✖ | N/A | ✖ | ✔ | |
| Background Image | ✖ | ✔ | ✖ | ✖ | ✖ | N/A | ✖ | ✖ | |
| Cell Validation | ✔ | ✔ | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| AutoFilters | ● | ● | ● | ● | ● | N/A | N/A | N/A | |
| AutoFilter Expressions | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Filter | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Custom Filter | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Date Filter | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Dynamic Filter | ✔ | ✔ | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Colour Filter | ✖ | ✖ | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| Icon Filter | ✖ | ✖ | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| Top 10 Filter | ✖ | ✔ | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| Macros | ✖ | ● 5
| ✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
| |
| Form Controls | ✖ | ● 4
| ✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
| |
| Security | ● | ● | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | |
| Protection (prevent editing) | ✔ | ✔ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | |
| Encryption (prevent viewing) | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | |
| XLS | XLSX | Excel2003XML | Ods | Gnumeric | CSV | SYLK | HTML | ||
| Readers | |||||||||
| Writers | |||||||
|---|---|---|---|---|---|---|---|
| XLS | XLSX | Ods | CSV | HTML | |||
| Document Properties | |||||||
| Standard Properties | |||||||
| Creator | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Creation Date/Time | ✔ | ✔ | ✔ | N/A | ✔ | ✖ | |
| Modifier | ✔ | ✔ | ✖ | N/A | ✔ | ✖ | |
| Modified Date/Time | ✔ | ✔ | ✖ | N/A | ✔ | ✖ | |
| Title | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Description | ✔ | ✔ | ✔ | N/A | ✔ | ✖ | |
| Subject | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Keywords | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Extended Properties | |||||||
| Category | ✔ | ✔ | ✖ | N/A | ✔ | ✖ | |
| Company | ✖ | ✔ | ✖ | N/A | ✔ | ✖ | |
| Manager | ✖ | ✔ | ✖ | N/A | ✔ | ✖ | |
| User-Defined (Custom) Properties | ✖ | ✔ | ✔ | N/A | ✔ | N/A | |
| Rich Text | ✔ | ✔ | ✖ | N/A | ✔ | ✔ | |
| Conditional Formatting | ✔ | ✔ | ✖ | ✖ | ✖ | ✖ | |
| Array Formula8 | ✖ | ✔ | ✔ | ✔ | ✔ | ✔ | |
| Rows and Column Properties | |||||||
| Row Height/Column Width | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Hidden | ✔ | ✔ | ✖ | N/A | ✔ | ✔ | |
| Worksheet Properties | |||||||
| Frozen Panes | ● | ✔ | ✖ | N/A | ✔ | ✖ | |
| Hidden Worksheets | ● | ✔ | ✖ | N/A | ✔ | ✖ | |
| Coloured Tabs | ✖ | ✔ | ✖ | N/A | ✖ | ✖ | |
| Drawing hyperlink | ✖ | ✔ | ✖ | N/A | ✖ | ✖ | |
| Cell Formatting | |||||||
| Number Format Mask | ✔ | ✔ | ✔6 | N/A | ✔ | ✔ | |
| Alignment | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Horizontal | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Vertical | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Wrapping | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Shrink-to-Fit | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Indent | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Background Colour | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Patterned | ✔ | ✔ | N/A | N/A | ✖ | ✖ | |
| Font Attributes | |||||||
| Font Face | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Font Size | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Bold | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Italic | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Strikethrough | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Underline | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Superscript | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Subscript | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Borders | |||||||
| Line Style | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Position | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Diagonal | ✔ | ✔ | ✔ | N/A | ✖ | ✖ | |
| Hyperlinks | ✔ | ✔ | ✖ | N/A | ✔ | ✖ | |
| http | ✔ | ✔ | ✖ | N/A | ✔ | ✖ | |
| Merged Cells | ✔ | ✔ | ✔ | N/A | ✔ | ✔ | |
| Cell Comments | ✖ | ● | ● | N/A | ● 1 | N/A | |
| Rich Text | ✖ | ✔ | ✖ | N/A | ✖ | N/A | |
| Alignment | ✖ | ✔ | ✖ | N/A | ✔ | N/A | |
| Background Image | ✖ | ✔ | ✖ | ✖ | ✖ | ✖ | |
| Cell Validation | ✔ | ✔ | ✖ | N/A | N/A | N/A | |
| AutoFilters | |||||||
| AutoFilter Expressions | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Filter | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Custom Filter | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| DateGroup Filter | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Dynamic Filter | ✔ | ✔ | ✔ | N/A | N/A | N/A | |
| Colour Filter | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| Icon Filter | ✖ | ✖ | ✖ | N/A | N/A | N/A | |
| Top 10 Filter | ✖ | ✔ | ✖ | N/A | N/A | N/A | |
| Macros | ✖ | ● 5
| ✖ |
N/A |
✖ |
✖ |
| |
| Form Controls | ✖ | ● 4
| ✖ |
N/A |
✖ |
✖ |
| |
| Security | |||||||
| Protection (prevent editing) | ✔ | ✔ | ✖ | N/A | ✖ | ✖ | |
| Encryption (prevent viewing) | ✖ | ✖ | ✖ | N/A | ✖ | ✖ | |
| XLS | XLSX | Ods | CSV | HTML | |||
| Writers | |||||||
| Methods | ||
|---|---|---|
| Getters | Setters | |
| Reader Options | ||
| Read Data Only (no formatting) | $reader->getReadDataOnly() | $reader->setReadDataOnly() |
| Read Only Specified Worksheets | $reader->getLoadSheetsOnly() | $reader->setLoadSheetsOnly() $reader->setLoadAllSheets() |
| Read Only Specified Cells | $reader->getReadFilter() | $reader->setReadFilter() |
| Document Properties | ||
| Standard Properties | ||
| Creator | $spreadsheet->getProperties()->getCreator() | $spreadsheet->getProperties()->setCreator() |
| Creation Date/Time | $spreadsheet->getProperties()->getCreated() | $spreadsheet->getProperties()->setCreated() |
| Modifier | $spreadsheet->getProperties()->getLastModifiedBy() | $spreadsheet->getProperties()->setLastModifiedBy() |
| Modified Date/Time | $spreadsheet->getProperties()->getModified() | $spreadsheet->getProperties()->setModified() |
| Title | $spreadsheet->getProperties()->getTitle() | $spreadsheet->getProperties()->setTitle() |
| Description | $spreadsheet->getProperties()->getDescription() | $spreadsheet->getProperties()->setDescription() |
| Subject | $spreadsheet->getProperties()->getSubject() | $spreadsheet->getProperties()->setSubject() |
| Keywords | $spreadsheet->getProperties()->getKeywords() | $spreadsheet->getProperties()->setKeywords() |
| Extended Properties | ||
| Category | $spreadsheet->getProperties()->getCategory() | $spreadsheet->getProperties()->setCategory() |
| Company | $spreadsheet->getProperties()->getCompany() | $spreadsheet->getProperties()->setCompany() |
| Manager | $spreadsheet->getProperties()->getManager() | $spreadsheet->getProperties()->setManager() |
| User-Defined (Custom) Properties | $spreadsheet->getProperties()->getCustomProperties() $spreadsheet->getProperties()->isCustomPropertySet() $spreadsheet->getProperties()->getCustomPropertyValue() $spreadsheet->getProperties()->getCustomPropertyType() |
$spreadsheet->getProperties()->setCustomProperty() |
| Drawing hyperlink | $drawing->getHyperlink()->getUrl() | $drawing->setHyperlink()->setUrl($url) |
| Hyperlinks | $cell->getHyperlink()->getUrl($url) | $cell->getHyperlink()->setUrl($url) |
| Cell Comments | ||
| Background Image | $comment->getBackgroundImage() | $comment->setBackgroundImage() |
| Cell Validation | $cell->getDataValidation() | $cell->setDataValidation() |
| AutoFilters | $sheet->getAutoFilter() | $sheet->setAutoFilter() |
| Macros | $spreadsheet->getMacrosCode();5 | $spreadsheet->setMacrosCode();5 |
| Security | ||
| Protection (prevent editing) | $sheet->getProtection() | $sheet->getProtection()->setSheet(true) |
| Getters | Setters | |
| Methods | ||
(if omitted, 24-hour time format is used) | AM or PM | Excel also supports Masks for Time Durations (note that spreadsheets using the 1904 base date can display negative durations, but those using the 1900 base date cannot). There is no "Wizard" for this; but the following Mask codes can be used to display Durations. | Code | Description | Displays as | |---------|----------------------------------------------------------------|-------------| | [h]:mm | Elapsed time in hours | e.g. 25:02 | | [hh]:mm | Elapsed time in hours
with a leading zero if less than 10 | e.g. 05:02 | | [mm]:ss | Elapsed time in minutes | e.g. 63:46 | | [m]:ss | Elapsed time in minutes
with a leading zero if less than 10 | e.g. 03:46 | | [s] | Elapsed time in seconds | | | [ss] | Elapsed time in seconds
with a leading zero if less than 10 | | ### Percentage This is among the simplest of the Excel "Wizards", only allowing you to specify the number of decimals to be displayed.  The Percentage mask looks like '0.00%'. Using the `%` code in a mask will multiply the value by 100 before rendering it, and it will always also display the `%` sign. The PhpSpreadsheet "Wizard" replicates this simple option; but also provides a locale option that allows locale-specific formatting, because there are a few locales where the percentage sign appears before the value rather than after it. As with all locale use for the PhpSpreadsheet "Wizard", this is dependent on having the `Intl` extension enabled. ```php use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Percentage; // Set Cell value $worksheet->getCell('C21')->setValue(-12345.67890); // Set Cell Style using the Percentage Wizard to build the Format Mask for a locale $localeCurrencyMask = new Percentage( locale: 'tr_TR' ); $worksheet->getCell('C21') ->getStyle()->getNumberFormat() ->setFormatCode($localeCurrencyMask); var_dump($worksheet->getCell('C21') ->getStyle()->getNumberFormat()->getFormatCode()); // %#,##0.00 var_dump($worksheet->getCell('C21')->getFormattedValue()); // %-12,345.68 ``` ### Fraction MS Excel presents two different options for fractions: the first where the denominator is calculated internally to either 1, 2 or 3 digits; and the second (introduced only recently) where the denominator is fixed as 2, 4, 8 or 16.  The Fraction mask looks like '# ?/???' where `#` indicates that the integer part of the value should be displayed, and then `?/???` to display the fraction with up to 3 digits in the denominator. The mask using a fixed-denominator looks like '# ?/16', with the denominator value replacing the variable `?`. If you use digit placeholders (`/??`) for the denominator, then Excel will calculate the lowest denominator that it can use for the fractional value. If you specify a fixed denominator (e.g. `/8`) then Excel will calculate the fraction in eighths. > **Note:** The internal renderer in PhpSpreadsheet does not consider the number of digits for the denominator, but will simply try to identify the lowest value denominator that it can use. There is currently no PhpSpreadsheet "Wizard" for Fraction Masks. ### Scientific This is among the simplest of the Excel "Wizards", only allowing you to specify the number of decimals to be displayed.  The Scientific mask looks like '0.00E+00'. > **Note**: The internal rendering used by PhpSpreadsheet will display only as many digits as necessary for the exponent; while the Excel mask specifies a minimum of 2 digits, with a leading zero if necessary. The PhpSpreadsheet "Wizard" replicates this simple option. ```php use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Scientific; // Set Cell value $worksheet->getCell('C20')->setValue(-12345.67890); // Set Cell Style using the Scientific Wizard to build the Format Mask $scientificMask = new Scientific( 4, ); $worksheet->getCell('C20') ->getStyle()->getNumberFormat() ->setFormatCode($scientificMask); var_dump($worksheet->getCell('C20') ->getStyle()->getNumberFormat()->getFormatCode()); // 0.0000E+00 var_dump($worksheet->getCell('C20')->getFormattedValue()); // -1.2346E+4 // Set Cell value $worksheet->getCell('C21')->setValue(-12345.67890); // Set Cell Style using the Scientific Wizard to build the Format Mask for a locale $localeScientificMask = new Scientific( 3, locale: 'nl_NL' ); $worksheet->getCell('C21') ->getStyle()->getNumberFormat() ->setFormatCode($localeScientificMask); var_dump($worksheet->getCell('C21') ->getStyle()->getNumberFormat()->getFormatCode()); // 0.000E+00 var_dump($worksheet->getCell('C21')->getFormattedValue()); // -1.235E+4 ``` If you specify a number of decimals to display, then the Scientific "Wizard" will apply that value, even when using a locale. ### Text MS Excel's Text "Wizard" has no options, but simply sets a mask to `@`, meaning display the value exactly as it is entered. Unlike `General`, which is adaptive, `@` will not change the displayed value in any way, except in one exceptional case (see note below). Very large or very small values will not be displayed in Scientific format, and leading zeroes will be displayed. >**Note:** If your cell contains Rich Text, then using `@` in a format mask will display it using the basic cell styling, ignoring the Rich Text styling.  PhpSpreadsheet doesn't emulate this behaviour; it simply displays the value as PHP would render that value cast to a string, which mimics Excel's quirk with Rich Text values. There is no PhpSpreadsheet "Wizard" for Text Masks. ### Special Excel's Special format "Wizard" is a recent introduction: select a locale, and then you may be offered a number of options for formatting values in a manner that is appropriate to that locale, such as US phone numbers, social security numbers, or zip codes; typically with separators between groups of digits. At this time, most locales have no special formats defined.  There is no PhpSpreadsheet "Wizard" for Special Masks. ## Custom Format Masks The Custom "Wizard" really isn't a Wizard at all, just an editing field that allows you to pre-populate from a list of common format masks before editing.  It does mean that you need to understand the rules for defining masks when you use this. When you create custom number formats, you can specify up to four sections of format code. These sections of code must be separated by semicolons (`;`). ### Sections for Composite Masks Sections of the mask define the formats for positive numbers, negative numbers, zero values, and text, in that order.  1. Format for Positive values 2. Format for Negative values 3. Format for Zero values 4. Format for Text If you specify only one section of format code, the code in that section is used for all numbers. If you specify two sections of format code, the first section of code is used for positive numbers and zeros, and the second section of code is used for negative numbers. If you specify a third section, then the first applies to positive values, the second to negative values, and the third to zero values. The fourth section only applies if the value is not numeric. If you skip code sections in the format mask, then you must include a semicolon for each of the missing sections. When you skip code sections in the format mask, then you must include a semicolon for each of the missing sections. Use `;` to indicate that a section exists, but with an empty mask; and that can be used to hide values that match the criteria for that section.  > **Note:** Negative values aren't shown with a sign when we use the negative value section. If we want the value to display with a sign, then we need to include an explicit '-' character in the Mask for that section (";-0;"). ### Basic Masking Symbols Three basic masking symbols are used to display numbers, and they differ in the way that they display leading or trailing zeroes. The fourth basic masking symbol is the text placeholder, which can be used to wrap the cell value within additional formatting. | Code | Description | Examples | |------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | 0 | Digit placeholder that displays insignificant zeros. | #.00 - always displays 2 decimal places.
If you type 5.5 in a cell, it will display as 5.50. | | # | Digit placeholder that represents optional digits and does not display extra zeros.
That is, if a number doesn't need a certain digit, it won't be displayed. | #.## - displays up to 2 decimal places.
If you type 5.5 in a cell, it will display as 5.5.
If you type 5.555, it will display as 5.56. | | ? | Digit placeholder that leaves a space for insignificant zeros on either side of the decimal point but doesn't display them. It is often used to align numbers in a column by decimal point. | #.??? - displays a maximum of 3 decimal places and aligns numbers in a column by decimal point. | | @ | Text placeholder | 0.00; -0.00; 0; [Red]@ - applies the red font colour for text values. | If a number entered in a cell has more digits to the right of the decimal point than there are placeholders in the format, the number is "rounded" to as many decimal places as there are placeholders. For example, if you have a value of `2.25` in a cell with '#.#' format, then the number will be rounded to 1 decimal, and will display as `2.3`. Digits to the left of the decimal point are always displayed regardless of the number of placeholders. For example, if the value in a cell is `202.25` with '#.#' format, the number will display as `202.3`.  To display leading zeroes for a numeric value, you might create a mask like '0000', which will always display at least 4 digits, padding the value with leading zeroes if it is less than 1000. ### Other Special Codes In addition to the masking symbols listed above, the following codes also enable special rendering of the value. | Code | Description | Example | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------| | . (period) | Decimal point. | ##0.00?? | | , (comma) | Thousands Separator.
A comma that follows a digit placeholder scales the number by a thousand. | #,##0
0.000,
Described below. | | \ | Text Escape Character that displays the character that follows it. | ##0\°
Described below. | | " " | Display any text that is enclosed in the double quotes. | ##0"°C"
Described below. | | % | Multiplies the value stored in the cell by 100 and display it with the percentage sign. | Examples provided in the "Wizard" section above. | | / | Display the value as a fraction. | Examples provided in the "Wizard" section above. | | E | Display the value in Scientific Format. | Examples provided in the "Wizard" section above. | | _ (underscore) | Space pad to the width of the next character in the mask.
It is commonly used in combination with parentheses to add left and right indents, `_(` and `_)` respectively. | Described below. | | * (asterisk) | Repeats the character that follows it until the width of the cell is filled.
It is often used in combination with the space character to change alignment. | Described below. | Simple examples of using these codes for Percentages, Fractions and Scientific Format can be found in the descriptions of those "Wizards". The other codes are described in detail below. ### Thousands Separator and Scaling To create an Excel custom number format with a thousands separator, include a comma (`,`) in the format code. For example: - #,### - display a thousands separator and no decimal places. - #,##0.00 - display a thousands separator and 2 decimal places. Microsoft Excel separates thousands by commas: if a comma is enclosed by any digit placeholders - the pound sign (`#`), question mark (`?`) or zero (`0`). But if no digit placeholder follows a comma, it scales the number by a thousand, two consecutive commas scale the number by a million, and so on. For example, if a cell format is '#.00,' and the cell value is `5000`, then the number `5.00` is displayed.  ### Formatting with Text If you want to include text in your format mask with numeric values, then there are two basic options. To add a single character, then you can prefix that character with a backslash ('\'), e.g. '#.00,\K' or '#.00,,\M'.  You don't need the backslash ('\') prefix for the following list of characters: | Character | Description | |-----------|----------------------------------| | + and - | Plus and Minus Signs | | ( and ) | Left and Right Parenthesis | | : | Colon | | ^ | Caret | | ' | Apostrophe | | { and } | Curly Braces | | < and > | Less Than and Greater than Signs | | = | Equals Sign | | / | Forward Slash | | ! | Exclamation Mark | | & | Ampersand | | ~ | Tilde | | | Space Character | You can also use additional padding characters if you want to break a number into groups. For example, to display a number as a phone number, you might use a mask like '00-0000-0000' or '(++00) 00-0000-0000'. It's a common practise in Accounting formats to wrap negative values in brackets; so you might use '([$€-nl-NL] #,##0.00)' for that section of the mask. To add words or for phrases to the mask, you should wrap the text in quotes: e.g. '#.00" Surplus";-#.00" Deficit";"Out of Stock"'.  ### Indents, Spacing and Alignment If you're wrapping negative values in brackets, you might like like to align your positive values with your negative values on the decimal, then you need to apply indents to the positive values to match the width of the bracket characters. The underscore code (`_`) tells Excel to pad the display to the width of the next character in the mask, so '_)' would tell Excel to pad to the width of ')' character like '[$€-nl-NL] _(#,##0.00_);[$€-nl-NL] (#,##0.00)'.  Accountants might also appreciate if the Currency symbols were also all aligned; so we can use the `*` code followed by a repeated character; and that will pad the width of the cell with the specified character. Typically, although not always, this will be a space character, '* '.  Which aligns all our currency symbols to the left of the cell, while displaying the value right-aligned in the cell, and all the decimal points neatly aligned. The `*` code can also be used to change the alignment of a value in a cell. If we want text to be rendered right aligned, even though the cell is left aligned, we can use '* @' as the mask, and this will push the display to the right of the cell.  Note that padding is not supported by PhpSpreadsheet's internal renderer for the cell's `getFormattedValue()` method, because the renderer is unaware of font or cell width, so it will simply add a single space in the formatted result. Nor will it change alignment in any way. ### Colours You can use format masks to change the font colour for a certain value with a custom number format. e.g. '[Red]@' Masking supports the following 8 main colours. - Black - Red - Green - Blue - Cyan - Yellow - Magenta - White To specify the colour, just type one of those colour names in the appropriate section of your number format code, wrapped in square braces (e.g. '[red]'). This colour code must be at the very start of the section, before any other formatting characters or instructions. The colour name is case-insensitive. If we wanted to show positive values in green and negative values in red we could apply different colours to the different sections of the mask, e.g. "[Green]#,##0.00;[Red]#,##0.00;0.00". > **Warning**: Colour masking doesn't apply when using Excel's `TEXT()` function; only when it is applied to a Cell's Format Mask. ### Conditional Formatting Not to be confused with actual Conditional Formatting in MS Excel; but we can apply some limited condition checks in normal Cell Format Masks, and apply different masking based on those conditions. While by default the different sections are interpreted by Excel as positive, negative, zero and text, we can override these definitions with conditions. We do this by defining the condition for matching against the value inside square braces.  The mask that we're using here is `[Red][<65]"Fail";[Blue]"Pass"`. This tells Excel to display the text "Fail" if the value in the Cell is less than 65, otherwise to display "Pass". The symbols allowed for comparison in Conditions are the standard mathematical comparison operators: | Symbol | Meaning | |--------|-----------------------| | \> | Greater than | | \>= | Greater than or Equal | | < | Less than | | <= | Less than or Equal | | = | Equal | | <\> | Not Equal | In this next example, we've created an additional condition, so we have three sections in the mask: the "Pass" grade is now any student that hasn't failed, but whose score is less than 85; the last section awards a grade of "Distinction" to any student whose score doesn't match the criteria for "Pass" or "Fail" (i.e. exceeds 85). `[Red][<65]"Fail";[Blue][<85]"Pass";"Distinction"`  We do need to be careful about the order that we define the conditions, because Excel will apply the mask for the first condition that matches the Cell value. > **Note**: Conditional Formatting using the Number Mask will also work with the TEXT() Function, although not with colour highlighting. We can also use Conditional Formatting to display Lakh, the different grouping often found in India and the countries of that region. While the thousands separator normally represents grouping to powers of 3 (103, 106, 109, etc), the Lakh is 103, 105, 107, etc. and is written as `1,00,000`. After the first 1000, the comma separator is used to represent groups of 2 digits, not groups of 3 digits. 150,000 rupees is 1.5 lakh rupees, and is written as `₹1,50,000` or `INR 1,50,000`. The mask used to represent lakh is: [>=10000000][$₹]##\,##\,##\,##0;[>=100000][$₹]##\,##\,##0;[$₹]##,##0 Note that we're only using the `,` for thousands grouping in the final block, to represent values less than 100,000 where we would only display a single `,` as a thousands separator. For the `,` in higher values, we are displaying a string literal `,` identified as such by the '\' immediately before it in the mask. ## Building Composite Masks using PhpSpreadsheet's Wizards Even though PhpSpreadsheet's Wizards don't yet support building sections with different masks for positive, negative, zero, and text, you can still create these using the Wizards as building blocks. ```php use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Currency; use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Number; // Set Cell value $worksheet->getCell('C20')->setValue(-12345.67890); // Set Cell Style using the Currency Wizard to build the Format Mask $currencyMask = new Currency( '€', 2, Number::WITH_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITH_SPACING ); // Build the composite mask applying colours to the different sections $compositeCurrencyMask = [ '[Green]' . $currencyMask, '[Red]' . $currencyMask, $currencyMask, ]; $worksheet->getCell('C20') ->getStyle()->getNumberFormat() ->setFormatCode(implode(';', $compositeCurrencyMask)); var_dump($worksheet->getCell('C20') ->getStyle()->getNumberFormat() ->getFormatCode()); // [Green]#,##0.00 €;[Red]#,##0.00 €;#,##0.00 € ``` We repeat the mask that's generated by the "Wizard" for each section of the composite mask, adding the required colour to each section. If we've used a locale to build a mask, then we may already have multiple sections: ```php use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Currency; // Set Cell value $worksheet->getCell('C20')->setValue(-12345.67890); // Set Cell Style using the Currency Wizard to build the Format Mask $currencyMask = new Currency( '€', locale: 'nl_NL' ); // Split the generated mask into sections // This particular mask already has positive and negative value sections, // but does not have a zero value section // Other locales may only have a positive section; or may already have a zero section $currencyMaskSections = explode(';', $currencyMask); // Recreate the modified mask applying colours to the different sections $compositeCurrencyMask = [ '[Green]' . $currencyMaskSections[0], '[Red]' . $currencyMaskSections[1] ?? $currencyMaskSections[0], $currencyMaskSections[2] ?? $currencyMaskSections[0], ]; $worksheet->getCell('C20') ->getStyle()->getNumberFormat() ->setFormatCode(implode(';', $compositeCurrencyMask)); var_dump($worksheet->getCell('C20') ->getStyle()->getNumberFormat() // [Green][$€-nl-NL] #,##0.00;[Red][$€-nl-NL] -#,##0.00;[$€-nl-NL] #,##0.00 ->getFormatCode()); ``` If the locale-generated mask already has a section defined, then we use that, otherwise we use the positive section (section 0) that will always exist as the base for each section. > **Warning:** You might need to add an explicit `-` for the negative section if that needs to be created. ## Summary Even though Excel displays the formatted value in the grid, the underlying value in the cell is unchanged. The value being displayed as a date is still an Excel Serialized Timestamp, even though it is being displayed as '2023-02-28'; the student grade is still a number, even though it is being displayed as "Distinction"/"Pass"/"Fail"; and the cell that looks empty may not be as empty as you think. The edit bar still shows us the value in the cell, not the formatted value; and we can still use that underlying value in formulae.  And we can even format the cell containing the result of that formula. Number format masks allow us to present the spreadsheet data in a format that makes it easy for the user to interpret; so they add a lot of value to the spreadsheets that we create. We just need to understand how to use them well to unlock that value. ================================================ FILE: docs/topics/Excel Anomalies.md ================================================ # Excel Anomalies This is documentation for some behavior in Excel itself which we just do not understand, or which may come as a surprise to the user. ## Date Number Format My system short date format is set to `yyyy-mm-dd`. Excel, for a very long time, did not include that amongst its formatting choices for dates, so it needed to be added as a custom format - no big deal. It has recently been added to the list of date formats, but ... I used Excel to create a spreadsheet, and included some dates, specifying `yyyy-mm-dd` formatting. When I looked at the resulting spreadsheet, I was surprised to see that Excel had stored the style not as `yyyy-mm-dd`, but rather as builtin style 14 (system short date format). Apparently the fact that the Excel styling matched my system choice was sufficient for it to override my choice! This is an astonishingly user-hostile implementation. Even though there are formats which, by design, "respond to changes in regional date and time settings", and even though the format I selected was not among those, Excel decided it was appropriate to vary the display even when I said I wanted an unvarying format. I assume, but have not confirmed, that this applies to formats other than `yyyy-mm-dd`. Note that this is not a problem when using PhpSpreadsheet to set the style, only when you let Excel do it. And, in that case, after a little experimentation, I figured out a format that Excel doesn't sabotage `[Black]yyyy-mm-dd`. If you have a spreadsheet that has been altered in this way, it can be fixed with the following PhpSpreadsheet code: ```php foreach ($spreadsheet->getCellXfCollection() as $style) { $numberFormat = $style->getNumberFormat(); // okay to use NumberFormat::SHORT_DATE_INDEX below if ($numberFormat->getBuiltInFormatCode() === 14) { $numberFormat->setFormatCode('yyyy-mm-dd'); } } ``` Starting with PhpSpreadsheet 4.5.0, this can be simplified to: ```php $spreadsheet->replaceBuiltinNumberFormat( \PhpOffice\PhpSpreadsheet\Style\NumberFormat::SHORT_DATE_INDEX, 'yyyy-mm-dd' ); ``` ## Negative Time Intervals You have a time in one cell, and a time in another, and you want to subtract and display the result in `h:mm` format. No problem if the result is positive. But, if it's negative, Excel just fills the cell with `#`. There is a solution of sorts. If you use a 1904 base date (default on Mac), the negative interval will work just fine. Alas, no dice if you use a 1900 base data (default on Windows). No idea why they can't fix that - the existing implementation can't really be something that anybody actually wants. Note that it is *not* safe to change the base date for an existing spreadsheet, so, if this is something you want to do, make sure you change the base date before populating any data. ## Long-ago Dates Excel does not support dates before either 1900-01-01 (Windows default) or 1904-01-01 (Mac default). For the 1900 base year, there is the additional problem that non-existent date 1900-02-29 is squeezed between 1900-02-28 and 1900-03-01. ## Weird Fractions Similar fraction formats have inconsistent results in Excel. For example, if a cell contains the value 1 and the cell's format is `0 0/0`, it will display as `1 0/1`. But, if the cell's format is `? ??/???`, it will display as `1`. See [this issue](https://github.com/PHPOffice/PhpSpreadsheet/issues/3625), which remains open because, in the absence of usable documentation, we aren't sure how to handle things. ## COUNTIF and Text Cells In Excel, COUNTIF appears to ignore text cells, behavior which doesn't seem to be documented anywhere. See [this issue](https://github.com/PHPOffice/PhpSpreadsheet/issues/3802), which remains open because, in the absence of usable documentation, we aren't sure how to handle things. ## SORT on Different DataTypes Excel appears to sort so that numbers are lowest in sort order, strings are next, booleans are next (LibreOffice treats booleans as ints), and null is highest. In addition, if your sort includes a numeric string with a leading plus or minus sign, the plus sign will be considered part of the string (so that `"+1"` will sort before `"0"`), but the minus sign will be ignored (so that `"-3"` will sort between `"25"` and `"40"`). There might be nuances I haven't thought of yet. PhpSpreadsheet will not necessarily duplicate Excel's behavior. The best advice we can offer is to make sure that arrays you wish to sort consist of a single datatype, and don't contain numeric strings. Samples samples/LookupRef/SortExcel and SortExcelCols are added to give an idea of how you might emulate Excel's behavior. I am not yet convinced that there is a use case for adding it as a class member in the src tree. ================================================ FILE: docs/topics/Looping the Loop.md ================================================ # Looping the Loop PhpSpreadsheet uses a lot of memory to maintain the Spreadsheet model; but I regularly see developers loading a Spreadsheet file and then calling the `toArray()` methods so that they can loop through the rows and columns of a worksheet. PHP arrays are also notoriously memory-intensive, so creating a large array duplicating the data that is already in the Spreadsheet model is a very inefficient use of memory. Generally, unless we are always working with very small spreadsheets, we would want to avoid this. So in this article, I'm going to look at a number of different ways of iterating through a worksheet to access the row and cell data; at their limitations; and at some of the options that each provides. ## Using `toArray()` Using a sample data file from Microsoft and available at https://go.microsoft.com/fwlink/?LinkID=521962, I can load up the file, call `toArray()` to return the worksheet data in an array, and iterate over the rows and cells of that array with the following code. ```php $inputFileType = 'Xlsx'; $inputFileName = __DIR__ . '/../Financial Sample.xlsx'; $reader = IOFactory::createReader($inputFileType); $spreadsheet = $reader->load($inputFileName); $worksheet = $spreadsheet->getActiveSheet(); $dataArray = $worksheet->toArray(); foreach ($dataArray as $row) { foreach ($row as $cellValue) { // Do something with the cell data here. } } ``` The Financial Sample spreadsheet is fairly small, 701 rows (including a heading row) and 16 columns; and is predominantly numeric data. To simulate a larger worksheet, I've duplicated that data to give 7001 rows; but this is still a small worksheet as MS Excel xlsx files can contain 1 million rows in each of several worksheets. If we look at the timings and memory usage for this process with my extended MS Financial Sample spreadsheet: ``` Current memory usage: 47104 KB Call time to build array was 0.6603 seconds Call time to iterate array rows was 0.0130 seconds Current memory usage: 57344 KB Peak memory usage: 57344 KB ``` We can see that using `toArray()` increases memory usage by 10240KB (10MB): that is the memory used by the array for a relatively small worksheet (less than 120,000 cells). For larger worksheets, with more rows and columns, and with more text than numeric values, this memory overhead can grow significantly larger. And while iteration over the array is very quick, it still takes 0.6603 seconds to build the array before we can start iterating over those rows and cells. --- The `toArray()` method is easy to use: but not only is it increasing the memory overhead, especially with larger worksheets; but it also lacks flexibility. It provides limited control over how the data from each cell is returned in the array. It can return the raw cell value (which isn't particularly useful if the cell contains a formula, or if the value should be interpreted as a date); it can force PhpSpreadsheet to calculate formulae and return the calculated value; or it can return the formatted cell value (which includes calculating any formulae) so that date values are presented in a human-readable format, but which will also format numeric values with thousand separators where the cell style applies that. | Argument Name | DataType | Default | Purpose | |--------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | $nullValue | mixed | null | A value to be returned in the array if a cell doesn't exist. | | $calculateFormulas | boolean | false | Flag to indicate if formula values should be calculated before returning. | | $formatData | boolean | false | Flag to request that values should be formatting before returning. | | $returnCellRef | boolean | false | False - Return a simple enumerated array of rows and columns (indexed by number counting from zero)
True - Return rows and columns indexed by their actual row and column IDs. | | $ignoreHidden | boolean | false | True - Ignore hidden rows and columns. | | $reduceArrays | boolean | false | True - If calculated value is an array, reduce it to top leftmost value. | | $lessFloatPrecision | boolean | false | True - PhpSpreadsheet 5.2+ - Floats, if formatted, will display as a more human-friendly but possibly less accurate value. | ### Dealing with empty rows The example spreadsheet that I've used here is well behaved, with no empty rows. Empty rows can cause problems, even when working in Excel itself. Let's take a look at a worksheet of Sales Data, where we're missing the returns for a couple of months:  If we're using MS Excel, and we hit `Ctrl-T` to create a table from this data, we might expect Excel to build that table from all rows up to `Dec`; but it won't, it will only build the table up to the next empty row.  And unless we're careful, we might not even notice that the last few months of the year are omitted. So empty rows can create problems even in MS Excel itself; and we certainly need to have some way of identifying them when we're processing a worksheet using PhpSpreadsheet. --- While we're iterating through a spreadsheet with PhpSpreadsheet, we might want to avoid trying to process blank data if we reach a row that is empty; or we might want to terminate iterating when we encounter an empty row. If we've created an array from a worksheet, then an empty row will be a row where every cell/column entry has a null value (unless called specifying an alternative value using the `$nullValue` argument). We can filter the row to eliminate null values, then count the length of that filtered array: if there are no remaining cells, then the row is empty. We can then skip that row in our code using `continue`. ```php foreach ($dataArray as $row) { // Check for empty rows if (count(array_filter($row, function ($value) { return $value !== null; })) === 0) { continue; // Ignore empty rows } foreach ($row as $cellValue) { // Do something with the cell data here. } } ``` Or if we want to terminate iterating when we encounter an empty row, use `break` rather than `continue`. ```php foreach ($dataArray as $row) { // Check for empty rows if (count(array_filter($row, function ($value) { return $value !== null; })) === 0) { break; // Stop at the first empty row } foreach ($row as $cellValue) { // Do something with the cell data here. } } ``` Using `toArray()` won't change anything in the worksheet model: it won't modify values or create new cells. It will return a row/column entry for every cell that can exist, even if that cell doesn't exist in the worksheet, or is part of a merge range. > **Note**: It is possible for several cells in a merge range to have a value. Although MS Excel doesn't allow you to set data like this, the option is available in other Spreadsheet software, and if the file is saved as an xlsx file, then the data for those cells is retained in the file, even though only the top left cell of a merge range shows a value in MS Excel. In PhpSpreadsheet, accessing those cells (including using `toArray()`) will return the "hidden" value. One useful factor about returning an array of arrays is if we want to populate a data model from that row before persisting to a database, for example. We don't need to iterate the columns in that row, but can work directly with the column array for each row. ```php class MonthlySales { private function __construct( public readonly string $month, public readonly array $sales, ) {} public static function fromExcel(array $values, array $headers): self { $month = array_shift($values); return new self($month, array_combine($headers, $values)); } } $monthlySalesData = new MonthlySalesCollection(); // Read from the header row of the worksheet $excelHeaderRow = ['Jones', 'Sorvino', 'Gupta', 'Choi']; $dataArray = $worksheet->toArray(formatData: true); foreach ($dataArray as $excelDataRow) { // Check for empty rows if (count(array_filter($excelDataRow, function ($value) { return $value !== null; })) === 0) { continue; // Ignore empty rows } $monthlySalesData->add(MonthlySales::fromExcel( $excelDataRow, $excelHeaderRow )); } ``` We can pass the row array directly to the static `MonthlySales::fromExcel()` constructor for our data object, handling any validation and manipulation of the structure there, to map the Excel data row to that object properties, handling filtering within the business logic of the Monthly Sales object's static constructor. --- And remember that by default, `toArray()` returns a simple enumerated array of enumerated arrays, to reflect rows and columns. You can modify this using the `$returnCellRef` argument to the method: set `$returnCellRef` to true, and the array indexes will be the row number (with 1 as the first row) and the column address ('A', 'B', 'C', etc); which can be useful if you want to do some processing of the cells based on that column address. ```php class MonthlySales { private function __construct( public readonly string $month, public readonly array $sales, ) {} public static function fromExcel(array $values, array $headers): self { $month = array_shift($values); $salesValues = []; foreach ($values as $column => $value) { // Ignore salespeople who have null sales values if ($value !== null) { $salesValues[$headers[$column]] = $value; } } return new self($month, $salesValues); } } $monthlySalesData = new MonthlySalesCollection(); // Read from the header row of the worksheet $excelHeaderRow = [ 'B' => 'Jones', 'C' => 'Sorvino', 'D' => 'Gupta', 'E' => 'Choi' ]; $dataArray = $worksheet->toArray(formatData: true, returnCellRef: true); foreach ($dataArray as $excelDataRow) { // Check for empty rows if (count(array_filter($excelDataRow, function ($value) { return $value !== null; })) === 0) { continue; // Ignore empty rows } $monthlySalesData->add(MonthlySales::fromExcel( $excelDataRow, $excelHeaderRow )); } ``` ## Using `rangeToArray()` The `toArray()` method uses information from the loaded file to identify the range of rows and columns to populate the array. `toArray()` uses two cached values to identify the range of cells to populate the array, values that are returned by the `getHighestRow()` and `getHighestColumn()` methods. But many worksheets do have trailing empty rows (or columns); and it is quite common for an Excel spreadsheet to have only a few rows or columns of data, but for the spreadsheet itself to claim that the highest row is 1,048,576 or that the highest column is XFD. Features such as Data Validation or Conditional Formatting that can also artificially inflate/increase the values returned by `getHighestRow()` and `getHighestColumn()` methods. If we use `toArray()` to build an array from the worksheet in this case, then it will build a 1,048,576x16,384 array, filled with null values, that will almost certainly exceed PHP's memory limits, and take a long time to do so. And if we do have enough memory to build the array, we will still be iterating over a lot more array entries than we want. Even if we're skipping empty rows, we're still testing every row to see if it's empty. Where possible, it's better to specify the limit of rows and columns that we want to use to build an array, and PhpSpreadsheet provides the `rangeToArray()` for that purpose. One option to reduce a large array using a lot of PHP memory would be to run a loop using `rangeToArray()` to build smaller arrays for blocks of perhaps 100 rows at a time. This will still take a while to run if we have a lot of trailing empty rows, but it won't exceed PHP's memory limits. ```php $startRow = 1; $batchSize = 100; while ($startRow <= $maxRow) { $endRow = min($startRow + $batchSize, $maxRow); $dataArray = $worksheet->rangeToArray("A{$startRow}:{$maxColumn}{$endRow}"); $startRow += $batchSize; foreach ($dataArray as $row) { // Check for empty rows if (count(array_filter($row, function ($value) { return $value !== null; })) === 0) { continue; // Ignore empty rows } foreach ($row as $cellValue) { // Do something with the cell data here. } } } ``` Alternatively, we can identify the highest row and highest column that actually contain cell data using the `getHighestDataRow()` and `getHighestDataColumn()` methods. This allows us to specify a range to pass to the `rangeToArray()` method. ```php $maxDataRow = $worksheet->getHighestDataRow(); $maxDataColumn = $worksheet->getHighestDataColumn(); $dataArray = $worksheet->rangeToArray("A1:{$maxDataColumn}{$maxDataRow}"); foreach ($dataArray as $row) { // Check for empty rows if (count(array_filter($row, function ($value) { return $value !== null; })) === 0) { continue; // Ignore empty rows } foreach ($row as $cellValue) { // Do something with the cell data here. } } ``` There might still be some empty rows in this array, so we still want to test for empty rows; but we won't have any trailing empty rows at the end of our data, so the iteration will terminate at the end of our specified row range, when we know we have no further data. And if there is a row or two of column headers that we want to ignore, we can modify the specified range to exclude them by adjusting the starting row of the range (e.g. `"A3:{$maxDataColumn}{$maxDataRow}"`); Because we're only building the array for a specified range of rows and columns, the array that the method builds will often be smaller than the array created by `toArray()`, using less memory; and it will often be faster iterating just the subset of rows that we've requested. A combination of these approaches - batching and using the 'getHighestDataRow()' value, will be more memory-efficient, and possibly faster, than using 'toArray()'. ```php $startRow = 1; $batchSize = 100; while ($startRow <= $maxDataRow) { $endRow = min($startRow + $batchSize, $maxDataRow); $dataArray = $worksheet->rangeToArray("A{$startRow}:{$maxDataColumn}{$endRow}"); $startRow += $batchSize; foreach ($dataArray as $row) { // Check for empty rows if (count(array_filter($row, function ($value) { return $value !== null; })) === 0) { continue; // Ignore empty rows } foreach ($row as $cellValue) { // Do something with the cell data here. } } } ``` How does this approach compare with using 'toArray()' in terms of memory and speed? Here are the details for using `rangeToArray()` with a batched approach: ``` Current memory usage: 47104 KB Call time to batch iterate array rows was 0.6844 seconds Current memory usage: 47104 KB Peak memory usage: 49152 KB ``` While the total time is 0.6844 seconds, that included building the smaller batched arrays, so its speed is comparable to the total time of 0.6733 seconds using `toArray()`. But a peak memory usage of 49,152KB compared with the 57,344KB used by `toArray()` make this approach a lot more memory efficient. Like `toArray()`, `rangeToArray()` is easy to use, but it has the same limitations for flexibility. It provides the same limited control over how the data from each cell is returned in the array as `toArray()`. The same additional arguments that can be provided for the `toArray()` method can also be provided to `rangeToArray()`. ## Using `rangeToArrayYieldRows()` Since v2.1.0 the worksheet method `rangeToArrayYieldRows()` is available. It allows you to iterate over all sheet's rows with little memory consumption, while obtaining each row as an array: ```php $rowGenerator = $sheet->rangeToArrayYieldRows( 'A1:' . $sheet->getHighestDataColumn() . $sheet->getHighestDataRow(), null, false, false ); foreach ($rowGenerator as $row) { echo $row[0] . ' | ' . $row[1] . "\n"; } ``` See `samples/Reader2/23_iterateRowsYield.php`. ## Using Iterators You don't need to build an array from the worksheet to loop through the rows and columns and do whatever processing you need; you can loop through the rows and columns in the Worksheet directly and more efficiently using PhpSpreadsheet's built-in iterators. And this also gives a lot more flexibility in how you can present the cell values, because the iterator will return the Cell itself, not a representation of its value. You can read its value, check its style, identify if it is part of a merge range. ```php $rowIterator = $worksheet->getRowIterator(); foreach ($rowIterator as $row) { $columnIterator = $row->getCellIterator(); foreach ($columnIterator as $cell) { // Do something with the cell here. } } ``` Let's look at the memory usage and timings for using PhpSpreadsheet's Iterators, as we did for building and iterating through the array. ``` Current memory usage: 47104 KB Call time to iterate rows was 0.0930 seconds Current memory usage: 47104 KB Peak memory usage: 47104 KB ``` Using the PhpSpreadsheet Iterators isn't as fast as iterating over an array; but it doesn't have the time or memory overheads of actually building that array from the worksheet. Using the same example spreadsheet, it only took 0.0130 seconds to iterate every cell of that array, but 0.6603 seconds to build the array, a total of 0.6733 seconds; but using the Iterator has performed the equivalent task in just 0.0930 seconds; about 7 times faster and without the increased memory overhead of the array. ### Dealing with empty rows As, when we were iterating over the array, we might want to identify empty rows so that we can avoid trying to process them. The Row Iterator provides a method to identify empty rows. ```php $rowIterator = $worksheet->getRowIterator(); foreach ($rowIterator as $row) { if ($row->isEmpty()) { // Ignore empty rows continue; } $columnIterator = $row->getCellIterator(); foreach ($columnIterator as $cell) { // Do something with the cell here. } } ``` One additional feature when using the Iterator to determine whether a row is empty or not is that we can set our own rules to define "empty". The default rule is if there is no entry for the Cell in the Cell Collection. If we also want to skip any Cell that contains a null value, then we can pass an argument using the pre-defined constant `CellIterator::TREAT_NULL_VALUE_AS_EMPTY_CELL`. If we also want to skip any Cell that contains an empty string, then we can pass an argument using the pre-defined constant `CellIterator::TREAT_EMPTY_STRING_AS_EMPTY_CELL`. And we can combine those rules: ```php if ($row->isEmpty( CellIterator::TREAT_EMPTY_STRING_AS_EMPTY_CELL | CellIterator::TREAT_NULL_VALUE_AS_EMPTY_CELL) ) { // Ignore empty rows continue; } ``` Since PhpSpreadsheet 1.27.0, we can take this empty test one step further. If we look at a slightly modified version of the Sales Data worksheet, rows 7 and 10 have no sales data, but they aren't empty because there is a month value in column A.  But we can tell the `isEmpty()` method to only check if a specified range of columns is empty in a row. ```php if ($row->isEmpty(startColumn: 'B', endColumn: 'E') { // Ignore empty rows where columns B to E are empty values // even though there is a value in Column A. continue; } ``` --- Like `toArray()`, the Iterators use the `getHighestRow()` and `getHighestColumn()` methods to identify the maximum row and column values for iterating; so it can still iterate over a lot of trailing empty rows and columns. But that is just a default behaviour. Similarly to `rangeToArray()` we can specify a range of rows, and a range of columns to iterate. ```php $maxDataRow = $worksheet->getHighestDataRow(); $maxDataColumn = $worksheet->getHighestDataColumn(); $rowIterator = $worksheet->getRowIterator(1, $maxDataRow); foreach ($rowIterator as $row) { if ($row->isEmpty()) { // Ignore empty rows continue; } $columnIterator = $row->getCellIterator('A', $maxDataColumn); foreach ($columnIterator as $cell) { // Do something with the cell here. } } ``` and if we have heading rows at the top of the worksheet that we want to ignore: ```php $rowIterator = $worksheet->getRowIterator(3, $maxDataRow); ``` And if we want to return only cells that aren't empty in the row, then we can tell the Cell Iterator to skip empty cells. ```php $rowIterator = $worksheet->getRowIterator(1, $maxDataRow); foreach ($rowIterator as $row) { $columnIterator = $row->getCellIterator(); $columnIterator->setIterateOnlyExistingCells(true); foreach ($columnIterator as $cell) { // Do something with the cell here. } } ``` Alongside the speed and memory benefits, another big advantage of using the Iterators (Row and Cell, or Column and Cell) is that we get direct access to the cell itself. We can look at its value, its style; we can identify if it is a formula, or formatted as a date/time, whether it is part of a merge range: we can choose exactly what we want to do with it. --- One drawback of the Cell Iterator is that it will create a new cell if none exists (by default) unless we're skipping empty cells. Until PhpSpreadsheet 1.27.0, the Cell Iterator would always create a new Cell if one didn't exist in the Cell Collection when it was required to access it. And this can lead to increasing memory consumption. PhpSpreadsheet 1.27.0 introduced the option to return a null value rather than to create and return a new Cell. ```php $rowIterator = $worksheet->getRowIterator(1, $maxDataRow); foreach ($rowIterator as $row) { $columnIterator = $row->getCellIterator(); $columnIterator->setIfNotExists(CellIterator::IF_NOT_EXISTS_RETURN_NULL); foreach ($columnIterator as $cell) { if ($cell !== null) { // Do something with the cell here. } } } ``` The default Iterator behaviour is still to create a new Cell, to retain backward compatibility; but the option to return a null value instead of a new empty cell now exists. > **Note**: This default behaviour is likely to be reversed with the eventual release of PhpSpreadsheet 2.0, with a null value as the default return, but with the option to create a new empty cell. ## Summary of Performance and Benefits So here is a quick summary of timing and memory usage for the three different approaches to iterating through the rows and cells of the 7000 row sample worksheet. Memory usage is adjusted for the 47,104 KB baseline of the loaded file. | Approach | Total Time (s) | Memory (KB) | |------------------------|----------------|-------------| | toArray() | 0.6733 | 10,240 | | rangeToArray (Batched) | 0.6844 | 2,048 | | Iterators | 0.0930 | 0 | These figures are all based on a well-formed spreadsheet, with no trailing empty rows, or empty rows within the dataset. Empty rows within a dataset can be identified by all three approaches, although only Iterators have a built-in method to identify an empty row. Using `toArray()` is not good for controlling memory usage, especially if there are trailing empty rows, so it should generally be avoided; but both `rangeToArray()` and the Iterators can exclude trailing rows by setting their scope based on the `getHighestDataRow()` and `getHighestDataColumn()` values. Batching rows with `rangeToArray()` is useful for keeping memory usage under control if you want to work with arrays. But using the Iterators is significantly faster than either "array" approach, with no memory overhead (especially if using the option of a null return for Cells that don't exist that was made available in PhpSpreadsheet 1.27.0); and as the Iterators return the Cell object rather than simply a cell value, they provide a lot more flexibility in how to process that cell. The flexibility to configure the definition of an empty row may also be useful to developers using this approach to iterating through a worksheet. ## Conclusions While it might require a little more userland code by developers using PhpSpreadsheet; because they are faster, have no additional memory overhead, and provide more flexibility, Iterators are the recommended approach for looping through the rows (and cells) of a worksheet. ================================================ FILE: docs/topics/The Dating Game.md ================================================ # The Dating Game Date and Time values are stored in different ways in spreadsheet files, depending on the file format; but internally when working in Excel the cell always contains a numeric value, representing the number of days since a baseline date, and formatted to appear as a human-readable date using a "Number Format Mask". This number is sometimes referred to as a serialized Excel date or timestamp. ## Dates That baseline date is normally 1st January 1900, although it can be 1st January 1904 (if the original spreadsheet file was created using the Mac version of MS Excel). Excel maintains a flag in the file indicating which baseline should be used; for file formats that don't provide this flag (such as .slk or .csv), the calendar defaults to the 1900 baseline.  Note that the baseline date itself is day 1; so strictly speaking, the base date 0 is '1899-12-31': Excel considers any value between 0 and 1 as purely a time value, trying to display 0 using a date format mask like 'yyyy-mm-dd' will show an invalid date like '1900-01-00' rather than '1899-12-31', but when using a time format mask like 'hh:mm:ss' it will appear as '00:00:00' (midnight). Values less than 0 are invalid as dates or as times, so a negative value in a cell with a date "Number Format Mask" will display as '############' in Excel. Open/Libre Office and Gnumeric don't have this limitation, and negative date/timestamp values are recognised and formatted correctly; but it is recommended that you don't rely on this when working with PhpSpreadsheet. To write a date in a cell using PhpSpreadsheet, we need to calculate the serialized Excel datestamp for that date. Methods to do this are available in the Shared\Date class, which provides a number of methods for conversion between different date options typically used in PHP applications (Unix timestamp, PHP DateTime objects and some recognisable formatted strings) and the Excel serialized value; and vice versa. - Shared\Date::convertIsoDate() - Converts a date/time in [ISO-8601 standard format](https://en.wikipedia.org/wiki/ISO_8601) to an Excel serialized timestamp - Shared\Date::PHPToExcel() - Converts a Unix timestamp, a PHP DateTime object, or a recognisable formatted string to an Excel serialized timestamp - Shared\Date::dateTimeToExcel() - Converts a Unix timestamp to an Excel serialized timestamp - Shared\Date::timestampToExcel() - Converts a PHP DateTime object to an Excel serialized timestamp - Shared\Date::formattedPHPToExcel() - Converts year, month, day, hour, minute, and second to an Excel serialized timestamp - Shared\Date::excelToDateTimeObject() - Converts an Excel serialized timestamp to a PHP DateTime object - Shared\Date::excelToTimestamp() - Converts an Excel serialized timestamp to a Unix timestamp. - The use of Unix timestamps, and therefore this function, is discouraged: they are not Y2038-safe on a 32-bit system, and have no timezone info. We probably also want to set the number format mask for the cell so that it will be displayed as a human-readable date. ```php use PhpOffice\PhpSpreadsheet\Spreadsheet; use PhpOffice\PhpSpreadsheet\Shared\Date as SharedDate; // Create new Spreadsheet object $spreadsheet = new Spreadsheet(); $worksheet = $spreadsheet->getActiveSheet(); // Calculate today's date as an Excel serialized timestamp $today = SharedDate::PHPToExcel(new DateTime('today')); $data = [ ['Formatted Date', 'Numeric Value'], ['=C2', 1], ['=C3', 2], ['=C4', $today], ]; // Write our data to the worksheet $worksheet->fromArray($data, null, 'B1'); // Display values in column B as human-readable dates $worksheet->getStyle('B2:B4')->getNumberFormat()->setFormatCode('yyyy-mm-dd'); // Set some additional styling $worksheet->getStyle('B1:C1')->getFont()->setBold(true); $worksheet->getColumnDimension('B')->setAutoSize(true); ``` ## Times Dates are always the integer part of the value (1, 2, 44943): the fractional part of the value is used to represent the time as a fraction of the day. So a value of 0.5 is 12:00 midday; 0.25 is 06:00 in the morning and 0.75 is 18:00 in the evening.  A float value greater than 1, like 44943.5 is considered as a datetime value: 12:00 (midday) on the 17th of January 2023. As with dates, to write a time value to a cell in PhpSpreadsheet, we write the numeric value for that time (or date/time) to the cell, and then apply a number format mask to the cell so that it will be displayed in a human-readable format. ```php use PhpOffice\PhpSpreadsheet\Spreadsheet; use PhpOffice\PhpSpreadsheet\Shared\Date as SharedDate; // Create new Spreadsheet object $spreadsheet = new Spreadsheet(); $worksheet = $spreadsheet->getActiveSheet(); // Calculate today's date as an Excel serialized timestamp $today = SharedDate::PHPToExcel(new DateTime('today')); $data = [ ['Formatted Time', 'Numeric Value'], ['=C2', 0], ['=C3', 0.25], ['=C4', 0.5], ['=C5', 0.75], ['=C6', $today + 0.5], ]; // Write our data to the worksheet $worksheet->fromArray($data, null, 'B1', true); // Display values in column B as human-readable dates $worksheet->getStyle('B2:B5')->getNumberFormat()->setFormatCode('hh:mm:ss'); $worksheet->getStyle('B6')->getNumberFormat()->setFormatCode('yyyy-mm-dd hh:mm:ss'); // Set some additional styling $worksheet->getStyle('B1:C1')->getFont()->setBold(true); $worksheet->getColumnDimension('B')->setAutoSize(true); ``` The same `Shared\Date` functions that convert between Excel dates and Unix Timestamps or PHP DateTime objects can also be used to convert time values. ## Dates/Times and Value Binders It is a standing joke that MS Excel tries to identify date and time values as you are entering data in Excel, and often treats any value as a possible date, converting it to an Excel serialized timestamp and applying date/time formatting, even though that may not have been what was intended.  Any change to a cell value in PhpSpreadsheet that isn't made using the setCellValueExplicit() method is passed through a "Value Binder", which triggers additional settings for that cell. > **Note**: dates and times maintained in true spreadsheet format files are always correctly identified in the file, and setCellValueExplicit() is used to store those values, with the formatting mask defined in that file. However, non-spreadsheet files such as .csv don't identify dates/times, so the Value Binder behaviour applies when loading those files. The Default Value Binder attempts to identify the datatype of the value and sets the cell datatype accordingly: and if you pass a string value like '2023-01-18 12:15:00' then the Default Value Binder will simply treat it as a string, and set it accordingly. However, if you choose to use the Advanced Value Binder, then that contains logic which looks more closely at those string values, and tries to determine if they are likely to be formatted dates or times, and in that regard it emulates Excel's behaviour. If the string value looks like a date or time, then it is converted to a serialized Excel date/timestamp, and an appropriate format mask is set for that cell. While the logic of this isn't perfect, I'd like to believe that it is less error-prone than Excel's own logic; but it won't necessarily recognise ambiguous formats and values correctly like '1/7/2023' as dates. (Is that the 1st of July? Or the 7th of January?) ## Reading Dates and Times from cells When we read the value of a cell that contains a Date/Time value, we are only reading a number (the Excel serialized timestamp); it is only the Number Format Mask that allows us to say whether that number is simply a number, or is meant to be a Date/Time value. PhpSpreadsheet provides a number of methods to identify whether a Number Format Mask represents a Date/Time format mask, or whether a Cell is formatted as a Date/Time. - Shared\Date::isDateTimeFormat() - Identifies if a NumberFormat Style object is an Excel Date/Time style format mask. - Shared\Date::isDateTimeFormatCode() - Identifies if the string value of a Number Format mask is an Excel Date/Time style format mask. - Shared\Date::isDateTime() - Identifies if a Cell is styled with a Number Format mask is an Excel Date/Time style format mask.**** These functions allow you to identify whether a cell value should be converted to a Unix Timestamp or PHP DateTime object (using one of the conversion functions provided in `Shared\Date`) for processing in your script, or for formatting as a Date/Time value. ## Date Arithmetic Because dates and times are just numeric values in MS Excel, this makes date/time arithmetic very easy to calculate: to count the number of days (or a duration) between two dates, we can use a simple subtraction.  Similarly, we can add date/time values like adding a duration to a start date to calculate an end date.  ## Excel Date Functions MS Excel provides a number of functions that will return a date or a time value. It also recognises when one of these functions is the "outer" function in a formula, so the final result will always be a serialized date/time value, and sets an appropriate format mask for that value. This behaviour is not replicated in PhpSpreadsheet. If you set a formula for a cell through your code that will return a date or time value, then you will also need to set the format mask for that cell manually. ## Formatting Options PhpSpreadsheet provides a number of built-in format code constants for dates and times in the NumberFormat class, matching those defined in the OfficeOpenXML specification, but you can always just set the format to any valid Excel formatting string, the equivalent of setting a custom date format in Excel. ### Dates When setting up a custom date format in Excel, you can use the following codes. | Code | Description | Example (January 3, 2023) | |-------|-------------------------------------|---------------------------------------| | m | Month number without a leading zero | 1 | | mm | Month number with a leading zero | 01 | | mmm | Month name, short form | Jan | | mmmm | Month name, full form | January | | mmmmm | Month as the first letter | J (stands for January, June and July) | | d | Day number without a leading zero | 3 | | dd | Day number with a leading zero | 03 | | ddd | Day of the week, short form | Tue | | dddd | Day of the week, full form | Tuesday | | yy | Year (last 2 digits) | 23 | | yyyy | Year (4 digits) | 2023 | ### Times When setting up a custom time format in Excel, you can use the following codes. | Code | Description | Displays as | |--------|--------------------------------------------------------------------|-------------| | h | Hours without a leading zero | 0-23 | | hh | Hours with a leading zero | 00-23 | | m | Minutes without a leading zero | 0-59 | | mm | Minutes with a leading zero | 00-59 | | s | Seconds without a leading zero | 0-59 | | ss | Seconds with a leading zero | 00-59 | | AM/PM | Periods of the day
(if omitted, 24-hour time format is used) | AM or PM | > **Warning** MS Excel allows any separator character between hours/minutes/seconds; PhpSpreadsheet currently requires a colon (`:`) to correctly distinguish minutes from months when rendering a time format within PHP code, although it will correctly write the format to file if any other separator character is used. ### Duration (Elapsed Time) Excel also supports formatting a value as a duration; a total number of hours, minutes or seconds rather than a time of day. However, please note that negative durations are supported only if using base year 1904 (Mac default). | Code | Description | Displays as | |---------|----------------------------------------------------------------|-------------| | [h]:mm | Elapsed time in hours | e.g. 25:02 | | [hh]:mm | Elapsed time in hours
with a leading zero if less than 10 | e.g. 05:02 | | [mm]:ss | Elapsed time in minutes | e.g. 63:46 | | [m]:ss | Elapsed time in minutes
with a leading zero if less than 10 | e.g. 03:46 | | [s] | Elapsed time in seconds | | | [ss] | Elapsed time in seconds
with a leading zero if less than 10 | | If you want to display an elapsed time in days, then you can use a normal date mask like `d h:mm` (without month or year), with the limitation that it will not exceed 31 days. ### Localisation #### Built-in Formats Some of the Excel built-in format masks are locale-aware.  Those locale-aware formats are highlighted with a * in Excel's drop-down lists for Date and Time, and will adapt when viewed in MS Excel, based on the locale settings of that local PC. PhpSpreadsheet is not locale-aware, so it will not render these formats as locale-formats, just as generic Date/Time formats; and localisation will be not be saved when writing to a spreadsheet file. #### Custom Formats When you're displaying a date/time using a format mask that isn't locale-aware in MS Excel, the locale settings for Excel are applied. So if you're displaying a month or day name, these will appear in the appropriate language for the locale of your PC.  You can force the display for a specific locale by prefixing the format mask with a locale setting, so that Excel will render it using the appropriate language. The locale code should be enclosed in [square brackets] and preceded with the dollar sign ($) and a dash (-). In this example, I'm forcing Dutch Netherlands by prefixing the mask with `[$-nl-NL]`. As an alternative, I could also have used the Windows LCID for that locale (`[$-413]`).  Because PhpSpreadsheet is not locale-aware, displaying the formatted value for that cell in your PHP script won't show the locale date/time, only a generic date/time; but it will still be written correctly when the file is saved (as a spreadsheet format) for Excel to render correctly and in the appropriate language. If you need this, then you can find a list of Windows LCID values [here](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/a29e5c28-9fb9-4c49-8e43-4b9b8e733a05) ## Summary Example Let's summarise some of this information with a script that will build a project timesheet for a week of work on that project. I'll keep the basic data in arrays for simplicity. ```php // In a real application, we might read this data from a database to build a project timesheet $projectHeading = [['Project', 'PhpSpreadsheet - The Dating Game']]; $weekHeading = [ ['Week', '=ISOWEEKNUM(D3)', 'Start Date', '=DATE(2023,1,16)'], ['Day', 'Start Time', 'End Time', 'Hours Worked'], ]; $timesheetData = [ ['2023-01-16', '17:25', '20:15'], ['2023-01-16', '20:50', '23:35'], ['2023-01-17', '18:10', '19:35'], ['2023-01-17', '20:10', '22:15'], ['2023-01-17', '22:35', '23:45'], ['2023-01-18', '09:15', '11:25'], ]; ``` Because I've used string values for the dates and times, I'm going to use the Advanced Value Binder to populate the worksheet. The Binder will also format the time values in columns B and C; but I want to override the Binder formatting for date values in column A; and I'm using an Excel formula for the "start date" value in cell D3, so I have to set the format manually for that. ```php use PhpOffice\PhpSpreadsheet\Spreadsheet; use PhpOffice\PhpSpreadsheet\Cell\Cell; use PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder; use PhpOffice\PhpSpreadsheet\Style\Alignment; // Create new Spreadsheet object $spreadsheet = new Spreadsheet(); $worksheet = $spreadsheet->getActiveSheet(); // Use the Advanced Value Binder so that our string date/time values will be automatically converted // to Excel serialized date/timestamps // Old method using static property Cell::setValueBinder(new AdvancedValueBinder()); // Preferred method using dynamic property since 3.4.0 $spreadsheet->setValueBinder(new AdvancedValueBinder()); // Write our data to the worksheet $worksheet->fromArray($projectHeading); $worksheet->fromArray($weekHeading, null, 'A3'); // Let Excel calculate the duration for each timesheet entry $row = 4; foreach ($timesheetData as $timesheetEntry) { ++$row; $worksheet->fromArray($timesheetEntry, null, "A{$row}"); $worksheet->setCellValue("D{$row}", "=C{$row} - B{$row}"); } $totalRow = $row + 2; $worksheet->setCellValue("D{$totalRow}", "=SUM(D4:D{$row})"); $worksheet->setCellValue("E{$totalRow}", 'Total Hours'); ``` And then the final formatting: ```php // Display values in column A as human-readable dates $worksheet->getStyle("A5:A{$row}")->getNumberFormat()->setFormatCode('dd (ddd)'); // Display values in column D as human-readable durations $worksheet->getStyle("D5:D{$totalRow}")->getNumberFormat()->setFormatCode('[h]:mm'); // Set some additional styling $worksheet->getStyle('D3')->getNumberFormat()->setFormatCode('yyyy-mm-dd'); $worksheet->getStyle('A1')->getFont()->setBold(true); $worksheet->getStyle('A3:D4')->getFont()->setBold(true); $worksheet->getStyle("A5:A{$row}")->getAlignment()->setHorizontal(Alignment::HORIZONTAL_LEFT); $worksheet->getColumnDimension('D')->setAutoSize(true); $worksheet->getStyle("E{$totalRow}")->getFont()->setBold(true); ``` And the resulting spreadsheet will look something like:  ## Final Notes MS Excel is not Timezone aware, nor does it have any logic for handling Daylight Savings. Excel functions like the NOW() function return the serialized timestamp of the current date and time. The date and time are provided by the operating system, and that determines, according to the time zone and date of the year if Daylight Saving Time is in effect. So functions like NOW() include any DST offset, because it is automatically included by the OS. ================================================ FILE: docs/topics/accessing-cells.md ================================================ # Accessing cells Accessing cells in a Spreadsheet should be pretty straightforward. This topic lists some of the options to access a cell. For all of these, the cell can be accessed by coordinate (e.g. `B3`), by an array of column index (where A is 1) and row (e.g. `[2, 3]`), or as a CellAddress object (e.g. `new CellAddress('B3', /* optional */ $worksheet)`. ## Setting a cell value Setting a cell value can be done using the worksheet's `setCellValue()` method. ```php // Set cell A1 with a string value $spreadsheet->getActiveSheet()->setCellValue('A1', 'PhpSpreadsheet'); // Set cell A2 with a numeric value $spreadsheet->getActiveSheet()->setCellValue([1, 2], 12345.6789); // Set cell A3 with a boolean value $spreadsheet->getActiveSheet()->setCellValue(new CellAddress('A3'), TRUE); // Set cell A4 with a formula $spreadsheet->getActiveSheet()->setCellValue( 'A4', '=IF(A3, CONCATENATE(A1, " ", A2), CONCATENATE(A2, " ", A1))' ); ``` Alternatively, you can retrieve the cell object, and then call the cell’s `setValue()` method: ```php $spreadsheet->getActiveSheet() ->getCell('B8') ->setValue('Some value'); ``` ### Creating a new Cell If you make a call to `getCell()`, and the cell doesn't already exist, then PhpSpreadsheet will create that cell for you. ### Copying a Cell's Value And Style Adjusting Formulas If cell A1 contains `5`, cell A2 contains `10`, and cell `B1` contains `=A1`, the formula in B1 will be evaluated as `5`. In Excel, if you copy B1 to B2, B2 will wind up with the adjusted formula `=A2` and will be evaluated as 10. Until release 5.1.0, PhpSpreadsheet requires the program to perform its own formula adjustment. In 5.1.0, a new method is introduced to handle formula adjustments: ```php $worksheet->copyformula($fromCell, $toCell); ``` This will behave as Excel does. If $fromCell does not contain a formula, its contents will be copied as-is. If you also want to copy $fromCell's style, as Excel does, you can use the following (available in all supported releases): ```php $worksheet->duplicateStyle($fromCell->getStyle(), $toCell); ``` ### BEWARE: Cells and Styles assigned to variables as a Detached Reference As an "in-memory" model, PHPSpreadsheet can be very demanding of memory, particularly when working with large spreadsheets. One technique used to reduce this memory overhead is cell caching, so cells are actually maintained in a collection that may or may not be held in memory while you are working with the spreadsheet. Because of this, a call to `getCell()` (or any similar method) returns the cell data, and sets a cell pointer to that cell in the collection. While this is not normally an issue, it can become significant if you assign the result of a call to `getCell()` to a variable. Any subsequent calls to retrieve other cells will change that pointer, although the cell object will still retain its data values. This is also true when assigning a variable to the result of `getStyle()`. What does this mean? Consider the following code: ```php $spreadSheet = new Spreadsheet(); $workSheet = $spreadSheet->getActiveSheet(); // Set details for the formula that we want to evaluate, together with any data on which it depends $workSheet->fromArray( [1, 2, 3], null, 'A1' ); $cellC1 = $workSheet->getCell('C1'); echo 'Value: ', $cellC1->getValue(), '; Address: ', $cellC1->getCoordinate(), PHP_EOL; $cellA1 = $workSheet->getCell('A1'); echo 'Value: ', $cellA1->getValue(), '; Address: ', $cellA1->getCoordinate(), PHP_EOL; echo 'Value: ', $cellC1->getValue(), '; Address: ', $cellC1->getCoordinate(), PHP_EOL; ``` The call to `getCell('C1')` returns the cell at `C1` containing its value (`3`), together with its link to the collection (used to identify its address/coordinate `C1`). The subsequent call to access cell `A1` modifies the value of `$cellC1`, detaching its link to the collection. So when we try to display the value and address a second time, we can display its value, but trying to display its address/coordinate will throw an exception because that link has been set to null. __Note:__ There are some internal methods that will fetch other cells from the collection, and this too will detach the link to the collection from any cell that you might have assigned to a variable. ## Excel DataTypes MS Excel supports 7 basic datatypes: - string - number - boolean - null - formula - error - Inline (or rich text) string By default, when you call the worksheet's `setCellValue()` method or the cell's `setValue()` method, PhpSpreadsheet will use the appropriate datatype for PHP nulls, booleans, floats or integers; or cast any string data value that you pass to the method into the most appropriate datatype, so numeric strings will be cast to numbers, while string values beginning with `=` will be converted to a formula. Strings that aren't numeric, or that don't begin with a leading `=` will be treated as genuine string values. Note that a numeric string that begins with a leading zero (that isn't immediately followed by a decimal separator) will not be converted to a numeric, so values like phone numbers (e.g. `01615991375``will remain as strings). This "conversion" is handled by a cell "value binder", and you can write custom "value binders" to change the behaviour of these "conversions". The standard PhpSpreadsheet package also provides an "advanced value binder" that handles a number of more complex conversions, such as converting strings with a fractional format like "3/4" to a number value (0.75 in this case) and setting an appropriate "fraction" number format mask. Similarly, strings like "5%" will be converted to a value of 0.05, and a percentage number format mask applied, and strings containing values that look like dates will be converted to Excel serialized datetimestamp values, and a corresponding mask applied. This is particularly useful when loading data from csv files, or setting cell values from a database. Formats handled by the advanced value binder include: - TRUE or FALSE (dependent on locale settings) are converted to booleans. - Numeric strings identified as scientific (exponential) format are converted to numbers. - Fractions and vulgar fractions are converted to numbers, and an appropriate number format mask applied. - Percentages are converted to numbers, divided by 100, and an appropriate number format mask applied. - Dates and times are converted to Excel timestamp values (numbers), and an appropriate number format mask applied. - When strings contain a newline character (`\n`), then the cell styling is set to wrap. Basically, it attempts to mimic the behaviour of the MS Excel GUI. You can read more about value binders [later in this section of the documentation](#using-value-binders-to-facilitate-data-entry). ### Setting a formula in a Cell As stated above, if you store a string value with the first character an `=` in a cell. PHPSpreadsheet will treat that value as a formula, and then you can evaluate that formula by calling `getCalculatedValue()` against the cell. There may be times though, when you wish to store a value beginning with `=` as a string, and that you don't want PHPSpreadsheet to evaluate as though it was a formula. To do this, you need to "escape" the value by setting it as "quoted text". ```php // Set cell A4 with a formula $spreadsheet->getActiveSheet()->setCellValue( 'A4', '=IF(A3, CONCATENATE(A1, " ", A2), CONCATENATE(A2, " ", A1))' ); $spreadsheet->getActiveSheet()->getCell('A4') ->getStyle()->setQuotePrefix(true); ``` Then, even if you ask PHPSpreadsheet to return the calculated value for cell `A4`, it will return `=IF(A3, CONCATENATE(A1, " ", A2), CONCATENATE(A2, " ", A1))` as a string, and not try to evaluate the formula. ### Setting a date and/or time value in a cell Date or time values are held as timestamp in Excel (a simple floating point value), and a number format mask is used to show how that value should be formatted; so if we want to store a date in a cell, we need to calculate the correct Excel timestamp, and set a number format mask. ```php // Get the current date/time and convert to an Excel date/time $dateTimeNow = time(); $excelDateValue = \PhpOffice\PhpSpreadsheet\Shared\Date::PHPToExcel( $dateTimeNow ); // Set cell A6 with the Excel date/time value $spreadsheet->getActiveSheet()->setCellValue( 'A6', $excelDateValue ); // Set the number format mask so that the excel timestamp will be displayed as a human-readable date/time $spreadsheet->getActiveSheet()->getStyle('A6') ->getNumberFormat() ->setFormatCode( \PhpOffice\PhpSpreadsheet\Style\NumberFormat::FORMAT_DATE_DATETIME ); ``` ### Setting a number with leading zeroes By default, PhpSpreadsheet will automatically detect the value type and set it to the appropriate Excel numeric datatype. This type conversion is handled by a value binder, as described in the section of this document entitled "Using value binders to facilitate data entry". Numbers don't have leading zeroes, so if you try to set a numeric value that does have leading zeroes (such as a telephone number) then these will be normally be lost as the value is cast to a number, so "01513789642" will be displayed as 1513789642. There are two ways you can force PhpSpreadsheet to override this behaviour. Firstly, you can set the datatype explicitly as a string so that it is not converted to a number. ```php // Set cell A8 with a numeric value, but tell PhpSpreadsheet it should be treated as a string $spreadsheet->getActiveSheet()->setCellValueExplicit( 'A8', "01513789642", \PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_STRING ); ``` Alternatively, you can use a number format mask to display the value with leading zeroes. ```php // Set cell A9 with a numeric value $spreadsheet->getActiveSheet()->setCellValue('A9', 1513789642); // Set a number format mask to display the value as 11 digits with leading zeroes $spreadsheet->getActiveSheet()->getStyle('A9') ->getNumberFormat() ->setFormatCode( '00000000000' ); ``` With number format masking, you can even break up the digits into groups to make the value more easily readable. ```php // Set cell A10 with a numeric value $spreadsheet->getActiveSheet()->setCellValue('A10', 1513789642); // Set a number format mask to display the value as 11 digits with leading zeroes $spreadsheet->getActiveSheet()->getStyle('A10') ->getNumberFormat() ->setFormatCode( '0000-000-0000' ); ```  **Note:** that not all complex format masks such as this one will work when retrieving a formatted value to display "on screen", or for certain writers such as HTML or PDF, but it will work with the true spreadsheet writers (Xlsx and Xls). ## Setting a range of cells from an array It is also possible to set a range of cell values in a single call by passing an array of values to the `fromArray()` method. ```php $arrayData = [ [NULL, 2010, 2011, 2012], ['Q1', 12, 15, 21], ['Q2', 56, 73, 86], ['Q3', 52, 61, 69], ['Q4', 30, 32, 0], ]; $spreadsheet->getActiveSheet() ->fromArray( $arrayData, // The data to set NULL, // Array values with this value will not be set 'C3' // Top left coordinate of the worksheet range where // we want to set these values (default is A1) ); ```  If you pass a 2-d array, then this will be treated as a series of rows and columns. A 1-d array will be treated as a single row, which is particularly useful if you're fetching an array of data from a database. ```php $rowArray = ['Value1', 'Value2', 'Value3', 'Value4']; $spreadsheet->getActiveSheet() ->fromArray( $rowArray, // The data to set NULL, // Array values with this value will not be set 'C3' // Top left coordinate of the worksheet range where // we want to set these values (default is A1) ); ```  If you have a simple 1-d array, and want to write it as a column, then the following will convert it into an appropriately structured 2-d array that can be fed to the `fromArray()` method: ```php $rowArray = ['Value1', 'Value2', 'Value3', 'Value4']; $columnArray = array_chunk($rowArray, 1); $spreadsheet->getActiveSheet() ->fromArray( $columnArray, // The data to set NULL, // Array values with this value will not be set 'C3' // Top left coordinate of the worksheet range where // we want to set these values (default is A1) ); ```  ## Retrieving a cell value To retrieve the value of a cell, the cell should first be retrieved from the worksheet using the `getCell()` method. A cell's value can be read using the `getValue()` method. ```php // Get the value from cell A1 $cellValue = $spreadsheet->getActiveSheet()->getCell('A1')->getValue(); ``` This will retrieve the raw, unformatted value contained in the cell. If a cell contains a formula, and you need to retrieve the calculated value rather than the formula itself, then use the cell's `getCalculatedValue()` method. This is further explained in [the calculation engine](./calculation-engine.md). ```php // Get the value from cell A4 $cellValue = $spreadsheet->getActiveSheet()->getCell('A4')->getCalculatedValue(); ``` Alternatively, if you want to see the value with any cell formatting applied (e.g. for a human-readable date or time value), then you can use the cell's `getFormattedValue()` method. ```php // Get the value from cell A6 $cellValue = $spreadsheet->getActiveSheet()->getCell('A6')->getFormattedValue(); ``` ## Retrieving a range of cell values to an array It is also possible to retrieve a range of cell values to an array in a single call using the `toArray()`, `rangeToArray()` or `namedRangeToArray()` methods. ```php $dataArray = $spreadsheet->getActiveSheet() ->rangeToArray( 'C3:E5', // The worksheet range that we want to retrieve NULL, // Value that should be returned for empty cells TRUE, // Should formulas be calculated (the equivalent of getCalculatedValue() for each cell) TRUE, // Should values be formatted (the equivalent of getFormattedValue() for each cell) TRUE // Should the array be indexed by cell row and cell column ); ``` These methods will all return a 2-d array of rows and columns. The `toArray()` method will return the whole worksheet; `rangeToArray()` will return a specified range or cells; while `namedRangeToArray()` will return the cells within a defined `named range`. ## Looping through cells ### Looping through cells using iterators The easiest way to loop cells is by using iterators. Using iterators, one can use foreach to loop worksheets, rows within a worksheet, and cells within a row. Below is an example where we read all the values in a worksheet and display them in a table. ```php $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader('Xlsx'); $reader->setReadDataOnly(TRUE); $spreadsheet = $reader->load("test.xlsx"); $worksheet = $spreadsheet->getActiveSheet(); echo '
| ' . $cell->getValue() . ' | ' . PHP_EOL; } echo '
| ' . $value . ' | ' . PHP_EOL; } echo '
| ' . $worksheet->getCell($col . $row) ->getValue() . ' | ' . PHP_EOL; } echo '
```
You might want to see:
```html
```
You can use the following code to achieve this result:
```php
$writer->setImagesRoot('http://www.example.com');
```
#### Formula pre-calculation
By default, this writer pre-calculates all formulas in the spreadsheet.
This can be slow on large spreadsheets, and maybe even unwanted. You can
however disable formula pre-calculation:
```php
$writer = new \PhpOffice\PhpSpreadsheet\Writer\Html($spreadsheet);
$writer->setPreCalculateFormulas(false);
$writer->save("05featuredemo.htm");
```
#### Embedding generated HTML in a web page
There might be a situation where you want to embed the generated HTML in
an existing website. \PhpOffice\PhpSpreadsheet\Writer\Html provides
support to generate only specific parts of the HTML code, which allows
you to use these parts in your website.
Supported methods:
- `generateHTMLHeader()`
- `generateStyles()`
- `generateSheetData()`
- `generateHTMLFooter()`
- `generateHTMLAll()`
Here's an example which retrieves all parts independently and merges
them into a resulting HTML page:
```php
$writer = new \PhpOffice\PhpSpreadsheet\Writer\Html($spreadsheet);
$hdr = $writer->generateHTMLHeader();
$sty = $writer->generateStyles(false); // do not write
$newstyle = <<| Hello World |
| Hello World |
| Hello World |
| Hello World |
| Hello World |
CHARTS | DATA
ONLY | IGNORE
EMPTY | IGNORE
ROWS | EXTERNAL
IMAGES | |----------|--------|------|--------|--------|--------| | Xlsx | YES | YES | YES | YES | YES | | Xls | NO | YES | YES | NO | NO | | Xml | NO | NO | NO | NO | NO | | Ods | NO | YES | NO | NO | NO | | Gnumeric | NO | YES | NO | NO | NO | | Html | N/A | N/A | N/A | N/A | YES | | Slk | N/A | NO | NO | NO | N/A | | Csv | N/A | NO | NO | NO | N/A | Likewise, when saving a file using a Writer, loaded charts will not be saved unless you explicitly tell the Writer to include them: ```php $writer = IOFactory::createWriter($spreadsheet, 'Xlsx'); $writer->setIncludeCharts(true); $writer->save('mySavedFileWithCharts.xlsx'); ``` As with the `load()` method, you can also pass flags in the `save()` method: ```php $writer = IOFactory::createWriter($spreadsheet, 'Xlsx'); $writer->save('mySavedFileWithCharts.xlsx', \PhpOffice\PhpSpreadsheet\Writer\IWriter::SAVE_WITH_CHARTS); ``` Flags that are available that can be passed to the Reader in this way include: - $reader::SAVE_WITH_CHARTS - $reader::DISABLE_PRECALCULATE_FORMULAE | Writers | SAVE_WITH_CHARTS | DISABLE_PRECALCULATE_FORMULAE | |---------|------------------|-------------------------------| | Xlsx | YES | YES | | Xls | NO | NO | | Ods | NO | YES | | Html | YES | YES | | Pdf | YES | YES | | Csv | N/A | YES | ### Combining Flags One benefit of flags is that you can pass several flags in a single method call. Two or more flags can be passed together using PHP's `|` operator. ```php $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReaderForFile('myExampleFile.xlsx'); $reader->load( 'spreadsheetWithCharts.xlsx', $reader::READ_DATA_ONLY | $reader::IGNORE_EMPTY_CELLS ); ``` ## Writing Data as a Plaintext Grid Although not really a spreadsheet format, it can be useful to write data in grid format to a plaintext file. Code like the following can be used: ```php $array = $sheet->toArray(null, true, true, true); $textGrid = new \PhpOffice\PhpSpreadsheet\Shared\TextGrid( $array, true, // true for cli, false for html // Starting with release 4.2, // the output format can be tweaked by uncommenting // any of the following 3 optional parameters. // rowDividers: true, // rowHeaders: false, // columnHeaders: false, // Starting with release 5.4: // numbersRight: TextGridRightAlign::numeric, ); $result = $textGrid->render(); ``` You can then echo `$result` to a terminal, or write it to a file with `file_put_contents`. The result will resemble: ``` +-----+------------------+---+----------+ | A | B | C | D | +---+-----+------------------+---+----------+ | 1 | 6 | 1900-01-06 00:00 | | 0.572917 | | 2 | 6 | TRUE | | 1<>2 | | 3 | xyz | xyz | | | +---+-----+------------------+---+----------+ ``` Please note that this may produce sub-optimal results for situations such as: - use of accents as combining characters rather than using pre-composed characters (may be handled by extending the class to override the `getString` or `strlen` methods) - Fullwidth characters - right-to-left characters (better display in a browser than a terminal on a non-RTL system) - multi-line strings ================================================ FILE: docs/topics/reading-files.md ================================================ # Reading Files ## Security XML-based formats such as OfficeOpen XML, Excel2003 XML, OASIS and Gnumeric are susceptible to XML External Entity Processing (XXE) injection attacks when reading spreadsheet files. This can lead to: - Disclosure whether a file is existent - Server Side Request Forgery - Command Execution (depending on the installed PHP wrappers) To prevent this, by default every XML-based Reader looks for XML entities declared inside the DOCTYPE and if any is found an exception is raised. Read more [about of XXE injection](https://websec.io/2012/08/27/Preventing-XXE-in-PHP.html). ## Loading a Spreadsheet File The simplest way to load a workbook file is to let PhpSpreadsheet's IO Factory identify the file type and load it, calling the static `load()` method of the `\PhpOffice\PhpSpreadsheet\IOFactory` class. ```php $inputFileName = './sampleData/example1.xls'; /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load($inputFileName); ``` See `samples/Reader/01_Simple_file_reader_using_IOFactory.php` for a working example of this code. The `load()` method will attempt to identify the file type, and instantiate a loader for that file type; using it to load the file and store the data and any formatting in a `Spreadsheet` object. The method makes an initial guess at the loader to instantiate based on the file extension; but will test the file before actually executing the load: so if (for example) the file is actually a CSV file or contains HTML markup, but that has been given a .xls extension (quite a common practise), it will reject the Xls loader that it would normally use for a .xls file; and test the file using the other loaders until it finds the appropriate loader, and then use that to read the file. If you know that this is an `xls` file, but don't know whether it is a genuine BIFF-format Excel or Html markup with an xls extension, you can limit the loader to check only those two possibilities by passing in an array of Readers to test against. ```php $inputFileName = './sampleData/example1.xls'; $testAgainstFormats = [ \PhpOffice\PhpSpreadsheet\IOFactory::READER_XLS, \PhpOffice\PhpSpreadsheet\IOFactory::READER_HTML, ]; /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load($inputFileName, 0, $testAgainstFormats); ``` While easy to implement in your code, and you don't need to worry about the file type; this isn't the most efficient method to load a file; and it lacks the flexibility to configure the loader in any way before actually reading the file into a `Spreadsheet` object. ## Creating a Reader and Loading a Spreadsheet File If you know the file type of the spreadsheet file that you need to load, you can instantiate a new reader object for that file type, then use the reader's `load()` method to read the file to a `Spreadsheet` object. It is possible to instantiate the reader objects for each of the different supported filetype by name. However, you may get unpredictable results if the file isn't of the right type (e.g. it is a CSV with an extension of .xls), although this type of exception should normally be trapped. ```php $inputFileName = './sampleData/example1.xls'; /** Create a new Xls Reader **/ $reader = new \PhpOffice\PhpSpreadsheet\Reader\Xls(); // $reader = new \PhpOffice\PhpSpreadsheet\Reader\Xlsx(); // $reader = new \PhpOffice\PhpSpreadsheet\Reader\Xml(); // $reader = new \PhpOffice\PhpSpreadsheet\Reader\Ods(); // $reader = new \PhpOffice\PhpSpreadsheet\Reader\Slk(); // $reader = new \PhpOffice\PhpSpreadsheet\Reader\Gnumeric(); // $reader = new \PhpOffice\PhpSpreadsheet\Reader\Csv(); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/02_Simple_file_reader_using_a_specified_reader.php` for a working example of this code. Alternatively, you can use the IO Factory's `createReader()` method to instantiate the reader object for you, simply telling it the file type of the reader that you want instantiating. ```php $inputFileType = 'Xls'; // $inputFileType = 'Xlsx'; // $inputFileType = 'Xml'; // $inputFileType = 'Ods'; // $inputFileType = 'Slk'; // $inputFileType = 'Gnumeric'; // $inputFileType = 'Csv'; $inputFileName = './sampleData/example1.xls'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/03_Simple_file_reader_using_the_IOFactory_to_return_a_reader.php` for a working example of this code. If you're uncertain of the filetype, you can use the `IOFactory::identify()` method to identify the reader that you need, before using the `createReader()` method to instantiate the reader object. ```php $inputFileName = './sampleData/example1.xls'; /** * Identify the type of $inputFileName. * See below for a possible improvement for release 4.1.0+. */ $inputFileType = \PhpOffice\PhpSpreadsheet\IOFactory::identify($inputFileName); /** Create a new Reader of the type that has been identified **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/04_Simple_file_reader_using_the_IOFactory_to_identify_a_reader_to_use.php` for a working example of this code. Prior to release 4.1.0, `identify` returns a file type. It may be more useful to return a fully-qualified class name, which can be accomplished using a parameter introduced in 4.1.0: ```php $inputFileType = \PhpOffice\PhpSpreadsheet\IOFactory::identify($inputFileName, null, true); ``` As with the IOFactory `load()` method, you can also pass an array of formats for the `identify()` method to check against if you know that it will only be in a subset of the possible formats that PhpSpreadsheet supports. ```php $inputFileName = './sampleData/example1.xls'; $testAgainstFormats = [ \PhpOffice\PhpSpreadsheet\IOFactory::READER_XLS, \PhpOffice\PhpSpreadsheet\IOFactory::READER_HTML, ]; /** Identify the type of $inputFileName **/ $inputFileType = \PhpOffice\PhpSpreadsheet\IOFactory::identify($inputFileName, $testAgainstFormats); ``` You can also use this to confirm that a file is what it claims to be: ```php $inputFileName = './sampleData/example1.xls'; try { /** Verify that $inputFileName really is an Xls file **/ $inputFileType = \PhpOffice\PhpSpreadsheet\IOFactory::identify($inputFileName, [\PhpOffice\PhpSpreadsheet\IOFactory::READER_XLS]); } catch (\PhpOffice\PhpSpreadsheet\Reader\Exception $e) { // File isn't actually an Xls file, even though it has an xls extension } ``` ## Spreadsheet Reader Options Once you have created a reader object for the workbook that you want to load, you have the opportunity to set additional options before executing the `load()` method. All of these options can be set by calling the appropriate methods against the Reader (as described below), but some options (those with only two possible values) can also be set through flags, either by calling the Reader's `setFlags()` method, or passing the flags as an argument in the call to `load()`. Those options that can be set through flags are: Option | Flag | Default -------------------|-------------------------------------|------------------------ Empty Cells | IReader::IGNORE_EMPTY_CELLS | Load empty cells Rows with no Cells | IReader::IGNORE_ROWS_WITH_NO_CELLS | Load rows with no cells Data Only | IReader::READ_DATA_ONLY | Read data, structure and style Charts | IReader::LOAD_WITH_CHARTS | Don't read charts Several flags can be combined in a single call: ```php $inputFileType = 'Xlsx'; $inputFileName = './sampleData/example1.xlsx'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Set additional flags before the call to load() */ $reader->setFlags(IReader::IGNORE_EMPTY_CELLS | IReader::LOAD_WITH_CHARTS); $reader->load($inputFileName); ``` or ```php $inputFileType = 'Xlsx'; $inputFileName = './sampleData/example1.xlsx'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Set additional flags in the call to load() */ $reader->load($inputFileName, IReader::IGNORE_EMPTY_CELLS | IReader::LOAD_WITH_CHARTS); ``` ### Ignoring Empty Cells Many Excel files have empty rows or columns at the end of a worksheet, which can't easily be seen when looking at the file in Excel (Try using Ctrl-End to see the last cell in a worksheet). By default, PhpSpreadsheet will load these cells, because they are valid Excel values; but you may find that an apparently small spreadsheet requires a lot of memory for all those empty cells. If you are running into memory issues with seemingly small files, you can tell PhpSpreadsheet not to load those empty cells using the `setReadEmptyCells()` method. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example1.xls'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Advise the Reader that we only want to load cell's that contain actual content **/ $reader->setReadEmptyCells(false); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` Note that cells containing formulae will still be loaded, even if that formula evaluates to a NULL or an empty string. Similarly, Conditional Styling might also hide the value of a cell; but cells that contain Conditional Styling or Data Validation will always be loaded regardless of their value. This option is available for the following formats: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | YES | Xls | YES | Xml | NO | Ods | NO | SYLK | NO | Gnumeric | NO | CSV | NO | HTML | NO This option is also available through flags. ### Ignoring Rows With No Cells Similar to the previous item, you can choose to ignore rows which contain no cells. This can also help with memory issues. ```php $inputFileType = 'Xlsx'; $inputFileName = './sampleData/example1.xlsx'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Advise the Reader that we do not want rows with no cells **/ $reader->setIgnoreRowsWithNoCells(true); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` This option is available only for Xlsx. It is also available through flags. ### Reading Only Data from a Spreadsheet File If you're only interested in the cell values in a workbook, but don't need any of the cell formatting information, then you can set the reader to read only the data values and any formulae from each cell using the `setReadDataOnly()` method. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example1.xls'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Advise the Reader that we only want to load cell data **/ $reader->setReadDataOnly(true); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/05_Simple_file_reader_using_the_read_data_only_option.php` for a working example of this code. It is important to note that most Workbooks (and PhpSpreadsheet) store dates and times as simple numeric values: they can only be distinguished from other numeric values by the format mask that is applied to that cell. When setting read data only to true, PhpSpreadsheet doesn't read the cell format masks, so it is not possible to differentiate between dates/times and numbers. The Gnumeric loader has been written to read the format masks for date values even when read data only has been set to true, so it can differentiate between dates/times and numbers; but this change hasn't yet been implemented for the other readers. Reading Only Data from a Spreadsheet File applies to Readers: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | YES | Xls | YES | Xml | YES | Ods | YES | SYLK | NO | Gnumeric | YES | CSV | NO | HTML | NO This option is also available through flags. ### Reading Only Named WorkSheets from a File If your workbook contains a number of worksheets, but you are only interested in reading some of those, then you can use the `setLoadSheetsOnly()` method to identify those sheets you are interested in reading. To read a single sheet, you can pass that sheet name as a parameter to the `setLoadSheetsOnly()` method. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example1.xls'; $sheetname = 'Data Sheet #2'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Advise the Reader of which WorkSheets we want to load **/ $reader->setLoadSheetsOnly($sheetname); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/07_Simple_file_reader_loading_a_single_named_worksheet.php` for a working example of this code. If you want to read more than just a single sheet, you can pass a list of sheet names as an array parameter to the `setLoadSheetsOnly()` method. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example1.xls'; $sheetnames = ['Data Sheet #1','Data Sheet #3']; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Advise the Reader of which WorkSheets we want to load **/ $reader->setLoadSheetsOnly($sheetnames); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/08_Simple_file_reader_loading_several_named_worksheets.php` for a working example of this code. To reset this option to the default, you can call the `setLoadAllSheets()` method. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example1.xls'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Advise the Reader to load all Worksheets **/ $reader->setLoadAllSheets(); /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/06_Simple_file_reader_loading_all_worksheets.php` for a working example of this code. Reading Only Named WorkSheets from a File applies to Readers: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | YES | Xls | YES | Xml | YES | Ods | YES | SYLK | NO | Gnumeric | YES | CSV | NO | HTML | NO ### Reading Only Specific Columns and Rows from a File (Read Filters) If you are only interested in reading part of a worksheet, then you can write a filter class that identifies whether or not individual cells should be read by the loader. A read filter must implement the `\PhpOffice\PhpSpreadsheet\Reader\IReadFilter` interface, and contain a `readCell()` method that accepts arguments of `$column`, `$row` and `$worksheetName`, and return a boolean true or false that indicates whether a workbook cell identified by those arguments should be read or not. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example1.xls'; $sheetname = 'Data Sheet #3'; /** Define a Read Filter class implementing \PhpOffice\PhpSpreadsheet\Reader\IReadFilter */ class MyReadFilter implements \PhpOffice\PhpSpreadsheet\Reader\IReadFilter { public function readCell($columnAddress, $row, $worksheetName = '') { // Read rows 1 to 7 and columns A to E only if ($row >= 1 && $row <= 7) { if (in_array($columnAddress,range('A','E'))) { return true; } } return false; } } /** Create an Instance of our Read Filter **/ $filterSubset = new MyReadFilter(); /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Tell the Reader that we want to use the Read Filter **/ $reader->setReadFilter($filterSubset); /** Load only the rows and columns that match our filter to Spreadsheet **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/09_Simple_file_reader_using_a_read_filter.php` for a working example of this code. This example is not particularly useful, because it can only be used in a very specific circumstance (when you only want cells in the range A1:E7 from your worksheet. A generic Read Filter would probably be more useful: ```php /** Define a Read Filter class implementing \PhpOffice\PhpSpreadsheet\Reader\IReadFilter */ class MyReadFilter implements \PhpOffice\PhpSpreadsheet\Reader\IReadFilter { private $startRow = 0; private $endRow = 0; private $columns = []; /** Get the list of rows and columns to read */ public function __construct($startRow, $endRow, $columns) { $this->startRow = $startRow; $this->endRow = $endRow; $this->columns = $columns; } public function readCell($columnAddress, $row, $worksheetName = '') { // Only read the rows and columns that were configured if ($row >= $this->startRow && $row <= $this->endRow) { if (in_array($columnAddress,$this->columns)) { return true; } } return false; } } /** Create an Instance of our Read Filter, passing in the cell range **/ $filterSubset = new MyReadFilter(9,15,range('G','K')); ``` See `samples/Reader/10_Simple_file_reader_using_a_configurable_read_filter.php` for a working example of this code. This can be particularly useful for conserving memory, by allowing you to read and process a large workbook in "chunks": an example of this usage might be when transferring data from an Excel worksheet to a database. Read Filtering does not renumber cell rows and columns. If you filter to read only rows 100-200, cells that you read will still be numbered A100-A200, not A1-A101. Cells A1-A99 will not be loaded, but if you then try to call `getCell()` for a cell outside your loaded range, then PHPSpreadsheet will create a new cell with a null value. Methods such as `toArray()` assume that all cells in a spreadsheet has been loaded from A1, so will return null values for rows and columns that fall outside your filter range: it is recommended that you keep track of the range that your filter has requested, and use `rangeToArray()` instead. ```php $inputFileType = 'Xls'; $inputFileName = './sampleData/example2.xls'; /** Define a Read Filter class implementing \PhpOffice\PhpSpreadsheet\Reader\IReadFilter */ class ChunkReadFilter implements \PhpOffice\PhpSpreadsheet\Reader\IReadFilter { private $startRow = 0; private $endRow = 0; /** Set the list of rows that we want to read */ public function setRows($startRow, $chunkSize) { $this->startRow = $startRow; $this->endRow = $startRow + $chunkSize; } public function readCell($columnAddress, $row, $worksheetName = '') { // Only read the heading row, and the configured rows if (($row == 1) || ($row >= $this->startRow && $row < $this->endRow)) { return true; } return false; } } /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Define how many rows we want to read for each "chunk" **/ $chunkSize = 2048; /** Create a new Instance of our Read Filter **/ $chunkFilter = new ChunkReadFilter(); /** Tell the Reader that we want to use the Read Filter **/ $reader->setReadFilter($chunkFilter); /** Loop to read our worksheet in "chunk size" blocks **/ for ($startRow = 2; $startRow <= 65536; $startRow += $chunkSize) { /** Tell the Read Filter which rows we want this iteration **/ $chunkFilter->setRows($startRow,$chunkSize); /** Load only the rows that match our filter **/ $spreadsheet = $reader->load($inputFileName); // Do some processing here } ``` See `samples/Reader/12_Reading_a_workbook_in_chunks_using_a_configurable_read_filter_` for a working example of this code. Using Read Filters applies to: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | YES | Xls | YES | Xml | YES | Ods | YES | SYLK | NO | Gnumeric | YES | CSV | YES | HTML | NO | | | ### Combining Multiple Files into a Single Spreadsheet Object While you can limit the number of worksheets that are read from a workbook file using the `setLoadSheetsOnly()` method, certain readers also allow you to combine several individual "sheets" from different files into a single `Spreadsheet` object, where each individual file is a single worksheet within that workbook. For each file that you read, you need to indicate which worksheet index it should be loaded into using the `setSheetIndex()` method of the `$reader`, then use the `loadIntoExisting()` method rather than the `load()` method to actually read the file into that worksheet. ```php $inputFileType = 'Csv'; $inputFileNames = [ './sampleData/example1.csv', './sampleData/example2.csv' './sampleData/example3.csv' ]; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Extract the first named file from the array list **/ $inputFileName = array_shift($inputFileNames); /** Load the initial file to the first worksheet in a `Spreadsheet` Object **/ $spreadsheet = $reader->load($inputFileName); /** Set the worksheet title (to the filename that we've loaded) **/ $spreadsheet->getActiveSheet() ->setTitle(pathinfo($inputFileName,PATHINFO_BASENAME)); /** Loop through all the remaining files in the list **/ foreach($inputFileNames as $sheet => $inputFileName) { /** Increment the worksheet index pointer for the Reader **/ $reader->setSheetIndex($sheet+1); /** Load the current file into a new worksheet in Spreadsheet **/ $reader->loadIntoExisting($inputFileName,$spreadsheet); /** Set the worksheet title (to the filename that we've loaded) **/ $spreadsheet->getActiveSheet() ->setTitle(pathinfo($inputFileName,PATHINFO_BASENAME)); } ``` See `samples/Reader/13_Simple_file_reader_for_multiple_CSV_files.php` for a working example of this code. Note that using the same sheet index for multiple sheets won't append files into the same sheet, but overwrite the results of the previous load. You cannot load multiple CSV files into the same worksheet. Combining Multiple Files into a Single Spreadsheet Object applies to: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | NO | Xls | NO | Xml | NO | Ods | NO | SYLK | YES | Gnumeric | NO | CSV | YES | HTML | NO ### Combining Read Filters with the `setSheetIndex()` method to split a large CSV file across multiple Worksheets An Xls BIFF .xls file is limited to 65536 rows in a worksheet, while the Xlsx Microsoft Office Open XML SpreadsheetML .xlsx file is limited to 1,048,576 rows in a worksheet; but a CSV file is not limited other than by available disk space. This means that we wouldn’t ordinarily be able to read all the rows from a very large CSV file that exceeded those limits, and save it as an Xls or Xlsx file. However, by using Read Filters to read the CSV file in "chunks" (using the ChunkReadFilter Class that we defined in [the above section](#reading-only-specific-columns-and-rows-from-a-file-read-filters), and the `setSheetIndex()` method of the `$reader`, we can split the CSV file across several individual worksheets. ```php $inputFileType = 'Csv'; $inputFileName = './sampleData/example2.csv'; echo 'Loading file ',pathinfo($inputFileName,PATHINFO_BASENAME),' using IOFactory with a defined reader type of ',$inputFileType,'
'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Define how many rows we want to read for each "chunk" **/ $chunkSize = 65530; /** Create a new Instance of our Read Filter **/ $chunkFilter = new ChunkReadFilter(); /** Tell the Reader that we want to use the Read Filter **/ /** and that we want to store it in contiguous rows/columns **/ $reader->setReadFilter($chunkFilter) ->setContiguous(true); /** Instantiate a new Spreadsheet object manually **/ $spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet(); /** Set a sheet index **/ $sheet = 0; /** Loop to read our worksheet in "chunk size" blocks **/ /** $startRow is set to 2 initially because we always read the headings in row #1 **/ for ($startRow = 2; $startRow <= 1000000; $startRow += $chunkSize) { /** Tell the Read Filter which rows we want to read this loop **/ $chunkFilter->setRows($startRow,$chunkSize); /** Increment the worksheet index pointer for the Reader **/ $reader->setSheetIndex($sheet); /** Load only the rows that match our filter into a new worksheet **/ $reader->loadIntoExisting($inputFileName,$spreadsheet); /** Set the worksheet title for the sheet that we've justloaded) **/ /** and increment the sheet index as well **/ $spreadsheet->getActiveSheet()->setTitle('Country Data #'.(++$sheet)); } ``` See `samples/Reader/14_Reading_a_large_CSV_file_in_chunks_to_split_across_multiple_worksheets.php` for a working example of this code. This code will read 65,530 rows at a time from the CSV file that we’re loading, and store each "chunk" in a new worksheet. The `setContiguous()` method for the Reader is important here. It is applicable only when working with a Read Filter, and identifies whether or not the cells should be stored by their position within the CSV file, or their position relative to the filter. For example, if the filter returned true for cells in the range B2:C3, then with setContiguous set to false (the default) these would be loaded as B2:C3 in the `Spreadsheet` object; but with setContiguous set to true, they would be loaded as A1:B2. Splitting a single loaded file across multiple worksheets applies to: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | NO | Xls | NO | Xml | NO | Ods | NO | SYLK | NO | Gnumeric | NO | CSV | YES | HTML | NO ### Pipe or Tab Separated Value Files The CSV loader will attempt to auto-detect the separator used in the file. If it cannot auto-detect, it will default to the comma. If this does not fit your use-case, you can manually specify a separator by using the `setDelimiter()` method. ```php $inputFileType = 'Csv'; $inputFileName = './sampleData/example1.tsv'; /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Set the delimiter to a TAB character **/ $reader->setDelimiter("\t"); // $reader->setDelimiter('|'); /** Load the file to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/15_Simple_file_reader_for_tab_separated_value_file_using_the_Advanced_Value_Binder.php` for a working example of this code. In addition to the delimiter, you can also use the following methods to set other attributes for the data load: Method | Default -------------------|---------- setEnclosure() | `"` setInputEncoding() | `UTF-8` Setting CSV delimiter applies to: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | NO | Xls | NO | Xml | NO | Ods | NO | SYLK | NO | Gnumeric | NO | CSV | YES | HTML | NO ### Reading formatted Numbers from a CSV File Unfortunately, numbers in a CSV file may be formatted as strings. If that number is a simple integer or float (with a decimal `.` separator) without any thousands separator, then it will be treated as a number. However, if the value has a thousands separator (e.g. `12,345`), or a decimal separator that isn't a `.` (e.g. `123,45` for a European locale), then it will be loaded as a string with that formatting. If you want the Csv Reader to convert that value to a numeric when it loads the file, the you need to tell it to do so. The `castFormattedNumberToNumeric()` lets you do this. (Assuming that our server is configured with German locale settings: otherwise it may be necessary to call `setlocale()` before loading the file.) ```php $inputFileType = 'Csv'; $inputFileName = './sampleData/example1.de.csv'; /** It may be necessary to call setlocale() first if this is not your default locale */ // setlocale(LC_ALL, 'de_DE.UTF-8', 'deu_deu'); /** Create a new Reader of the type defined in $inputFileType **/ $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); /** Enable loading numeric values formatted with German , decimal separator and . thousands separator **/ $reader->castFormattedNumberToNumeric(true); /** Load the file to a Spreadsheet Object **/ $spreadsheet = $reader->load($inputFileName); ``` This will attempt to load those formatted numeric values as numbers, based on the server's locale settings. If you want to load those values as numbers, but also to retain the formatting as a number format mask, then you can pass a boolean `true` as a second argument to the `castFormattedNumberToNumeric()` method to tell the Reader to identify the format masking to use for that value. This option does have an arbitrary limit of 6 decimal places. If your Csv file includes other formats for numbers (currencies, scientific format, etc); then you should probably also use the Advanced Value Binder to handle these cases. Applies to: Reader | Y/N |Reader | Y/N |Reader | Y/N | ----------|:---:|--------|:---:|--------------|:---:| Xlsx | NO | Xls | NO | Xml | NO | Ods | NO | SYLK | NO | Gnumeric | NO | CSV | YES | HTML | NO ## A Brief Word about the Advanced Value Binder When loading data from a file that contains no formatting information, such as a CSV file, then data is read either as strings or numbers (float or integer). This means that PhpSpreadsheet does not automatically recognise dates/times (such as `16-Apr-2009` or `13:30`), booleans (`true` or `false`), percentages (`75%`), hyperlinks (`https://www.example.com`), etc as anything other than simple strings. However, you can apply additional processing that is executed against these values during the load process within a Value Binder. A Value Binder is a class that implement the `\PhpOffice\PhpSpreadsheet\Cell\IValueBinder` interface. It must contain a `bindValue()` method that accepts a `\PhpOffice\PhpSpreadsheet\Cell\Cell` and a value as arguments, and return a boolean `true` or `false` that indicates whether the workbook cell has been populated with the value or not. The Advanced Value Binder implements such a class: amongst other tests, it identifies a string comprising "TRUE" or "FALSE" (based on locale settings) and sets it to a boolean; or a number in scientific format (e.g. "1.234e-5") and converts it to a float; or dates and times, converting them to their Excel timestamp value – before storing the value in the cell object. It also sets formatting for strings that are identified as dates, times or percentages. It could easily be extended to provide additional handling (including text or cell formatting) when it encountered a hyperlink, or HTML markup within a CSV file. So using a Value Binder allows a great deal more flexibility in the loader logic when reading unformatted text files. ```php $inputFileType = 'Csv'; $inputFileName = './sampleData/example1.tsv'; $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); $reader->setDelimiter("\t"); /** Tell PhpSpreadsheet that we want to use the Advanced Value Binder **/ // Old method using static property \PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() ); // Preferred method using dynamic property since 3.4.0 $reader::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() ); $spreadsheet = $reader->load($inputFileName); ``` See `samples/Reader/15_Simple_file_reader_for_tab_separated_value_file_using_the_Advanced_Value_Binder.php` for a working example of this code. Loading using a Value Binder applies to: Reader | Y/N |Reader | Y/N |Reader | Y/N ----------|:---:|--------|:---:|--------------|:---: Xlsx | NO | Xls | NO | Xml | NO Ods | NO | SYLK | YES | Gnumeric | NO CSV | YES | HTML | YES Note that you can also use the Binder to determine how PhpSpreadsheet identified datatypes for values when you set a cell value without explicitly setting a datatype. Value Binders can also be used to set formatting for a cell appropriate to the value. ## Error Handling Of course, you should always apply some error handling to your scripts as well. PhpSpreadsheet throws exceptions, so you can wrap all your code that accesses the library methods within Try/Catch blocks to trap for any problems that are encountered, and deal with them in an appropriate manner. The PhpSpreadsheet Readers throw a `\PhpOffice\PhpSpreadsheet\Reader\Exception`. ```php $inputFileName = './sampleData/example-1.xls'; try { /** Load $inputFileName to a Spreadsheet Object **/ $spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load($inputFileName); } catch(\PhpOffice\PhpSpreadsheet\Reader\Exception $e) { die('Error loading file: '.$e->getMessage()); } ``` See `samples/Reader/16_Handling_loader_exceptions_using_TryCatch.php` for a working example of this code. ## Helper Methods You can retrieve a list of worksheet names contained in a file without loading the whole file by using the Reader’s `listWorksheetNames()` method; similarly, a `listWorksheetInfo()` method will retrieve the dimensions of worksheet in a file without needing to load and parse the whole file. ### listWorksheetNames The `listWorksheetNames()` method returns a simple array listing each worksheet name within the workbook: ```php $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType); $worksheetNames = $reader->listWorksheetNames($inputFileName); echo '
Worksheet Names
'; echo '- ';
foreach ($worksheetNames as $worksheetName) {
echo '
- ', $worksheetName, ' '; } echo '
Worksheet Information
'; echo '- ';
foreach ($worksheetData as $worksheet) {
echo '
- ', $worksheet['worksheetName'], '
'; echo 'Rows: ', $worksheet['totalRows'], ' Columns: ', $worksheet['totalColumns'], '
'; echo 'Cell Range: A1:', $worksheet['lastColumnLetter'], $worksheet['totalRows'], '
'; echo 'Sheet state: ', $worksheet['sheetState']; echo ' ';
}
echo '
Click here for details of Spreadsheet Document Properties
These are accessed in MS Excel from the "Info" option on the "File" menu:  Some of these properties can be edited "in situ" in the Properties Block:  For more advanced properties, click on the "Properties" dropdown:  And you will be able to add/edit/delete a lot of different property values.  Properties on the "General", "Statistics" and "Contents" tabs are informational, and cannot be user-defined in Excel itself. Properties on the "Summary" tab are all string values. The "Custom" tab allows you to define your own properties. More information from the Microsoft Documentation can be found [here](https://support.microsoft.com/en-us/office/view-or-change-the-properties-for-an-office-file-21d604c2-481e-4379-8e54-1dd4622c6b75).  You can select a property name from the dropdown, or type a new name of your choice; select a Type; enter a value; and then click on "Add". The new property will then be created and displayed in the list at the bottom of the form. While "Text", "Number" (can be an integer or a floating point value) and "Yes or No" types are straightforward to add a value, "Date" types are more difficult, and Microsoft provide very little help. However, you need to enter the date in the format that matches your locale, so an American would enter "7/4/2023 for the 4th of July; but in the UK I would enter "4/7/2023" for the same date. Although typically recognised as a date elsewhere in MS Excel, the almost universally recognised `2022-12-31` date format is not recognised as valid here.Click here for details of Property Getters/Setters
PhpSpreadsheet provides specific getters/setters for a number of pre-defined properties. | Property Name | DataType | Getter/Setter | Notes | |------------------|-------------------------|----------------------------------------------|-----------------------------------------------------------| | Creator | string | getCreator()setCreator() | | | Last Modified By | string | getLastModifiedBy()
setLastModifiedBy() | | | Created | float/int
timestamp | getCreated()
setCreated() | Cannot be modified in MS Excel; but is automatically set. | | Modified | float/int
timestamp | getModified()
setModified() | Cannot be modified in MS Excel; but is automatically set. | | Title | string | getTitle()
setTitle() | | | Description | string | getDescription()
setDescription() | | | Subject | string | getSubject()
setSubject() | | | Keywords | string | getKeywords()
setKeywords() | | | Category | string | getCategory()
setCategory() | Not supported in xls files. | | Company | string | getCompany()
setCompany() | Not supported in xls files. | | Manager | string | getManager()
setManager() | Not supported in xls files. | > **Note:** Not all Spreadsheet File Formats support all of these properties. > For example: "Category", "Company" and "Manager" are not supported in `xls` files.
Click here for details of Custom Properties
Additionally, PhpSpreadsheet supports the creation and reading of custom properties for those file formats that accept custom properties. The following methods of the Properties class can be used when working with custom properties. - `getCustomProperties()`Will return an array listing the names of all custom properties that are defined. - `isCustomPropertySet(string $propertyName)`
Will return a boolean indicating if the named custom property is defined. - `getCustomPropertyValue(string $propertyName)`
Will return the "raw" value of the named custom property; or null if the property doesn't exist. - `getCustomPropertyType(string $propertyName)`
Will return the datatype of the named custom property; or null if the property doesn't exist. - `setCustomProperty(string $propertyName, $propertyValue = '', $propertyType = null)`
Will let you set (or modify) a custom property. If you don't provide a datatype, then PhpSpreadsheet will attempt to identify the datatype from the value that you set. The recognised Property Types are: | Constant | Datatype | Value | |-----------------------------------|----------|-------| | Properties::PROPERTY_TYPE_BOOLEAN | boolean | b | | Properties::PROPERTY_TYPE_INTEGER | integer | i | | Properties::PROPERTY_TYPE_FLOAT | float | f | | Properties::PROPERTY_TYPE_DATE | date | d | | Properties::PROPERTY_TYPE_STRING | string | s | When reading property types, you might also encounter: | Datatype | Value | |----------|--------------| | null | null value | | empty | empty string | | u | unknown | Other more complex types, such as pointers and filetime, are not supported by PhpSpreadsheet; and are discarded when reading a file.
Click here for details about Worksheets
When you create a new Spreadsheet in MS Excel, it creates the Spreadsheet with a single Worksheet ("Sheet1")  and that is the "Active" Worksheet.  This is the same as ```php $spreadsheet = new Spreadsheet(); $activeWorksheet = $spreadsheet->getActiveSheet(); ``` in PhpSpreadsheet. And you can then write values to Cells in `$activeWorksheet` (`Sheet1`). To create a new Worksheet in MS Excel, you click on the "+" button in the Worksheet Tab Bar. MS Excel will then create a new Worksheet ("Sheet2") in the Spreadsheet, and make that the current "Active" Worksheet.  Excel always shows the "Active" Worksheet in the Grid, and you can see which Worksheet is "Active" because it is highlighted in the Worksheet Tab Bar at the bottom of the Worksheet Grid. This is the same as ```php $activeWorksheet = $spreadsheet->createSheet(); ``` in PhpSpreadsheet. And you can then write values to Cells in `$activeWorksheet` (`Sheet2`).Click here for an example of the Date/Time Wizards
```php use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Date as DateWizard; use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Time as TimeWizard; use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\DateTime as DateTimeWizard; $spreadsheet->getActiveSheet()->setCellValue('A1', '=NOW()') $spreadsheet->getActiveSheet()->setCellValue('A2', '=NOW()') $spreadsheet->getActiveSheet()->setCellValue('A3', '=NOW()') // yyyy-mm-dd $dateFormat = new DateWizard( DateWizard::SEPARATOR_DASH, DateWizard::YEAR_FULL, DateWizard::MONTH_NUMBER_LONG, DateWizard::DAY_NUMBER_LONG ); $spreadsheet->getActiveSheet()->getStyle('A1') ->getNumberFormat() ->setFormatCode($dateFormat); // hh:mm $timeFormat = new TimeWizard( TimeWizard::SEPARATOR_COLON, TimeWizard::HOURS_LONG, TimeWizard::MINUTES_LONG, ); $spreadsheet->getActiveSheet()->getStyle('A2') ->getNumberFormat() ->setFormatCode($timeFormat); // yyyy-mm-dd hh:mm $dateTimeFormat = new DateTimeWizard(' ', $dateFormat, $timeFormat); $spreadsheet->getActiveSheet()->getStyle('A3') ->getNumberFormat() ->setFormatCode($dateTimeFormat); ```\n"; } ``` If Russian language files aren't available, the `setLocale()` method will return an error, and English settings will be used throughout. Once you have set a locale, you can translate a formula from its internal English coding. ```php $formula = $spreadsheet->getActiveSheet()->getCell('B8')->getValue(); $translatedFormula = \PhpOffice\PhpSpreadsheet\Calculation\Calculation::getInstance()->translateFormulaToLocale($formula); ``` You can also create a formula using the function names and argument separators appropriate to the defined locale; then translate it to English before setting the cell value: ```php $formula = '=ДНЕЙ360(ДАТА(2010;2;5);ДАТА(2010;12;31);ИСТИНА)'; $internalFormula = \PhpOffice\PhpSpreadsheet\Calculation\Calculation::getInstance()->translateFormulaToEnglish($formula); $spreadsheet->getActiveSheet()->setCellValue('B8',$internalFormula); ``` Currently, formula translation only translates the function names, the constants TRUE and FALSE (and NULL), Excel error messages, and the function argument separators. Cell addressing using R1C1 formatting is not supported. At present, the following locale settings are supported: Language | | Locale Code ---------------------|----------------------|------------- Bulgarian | български | bg Czech | Ceština | cs Danish | Dansk | da German | Deutsch | de Spanish | Español | es Finnish | Suomi | fi French | Français | fr Hungarian | Magyar | hu Italian | Italiano | it Dutch | Nederlands | nl Norwegian | Norsk Bokmål | nb Polish | Jezyk polski | pl Portuguese | Português | pt Brazilian Portuguese | Português Brasileiro | pt_br Russian | русский язык | ru Swedish | Svenska | sv Turkish | Türkçe | tr If anybody can provide translations for additional languages, particularly Basque (Euskara), Catalan (Català), Croatian (Hrvatski jezik), Galician (Galego), Greek (Ελληνικά), Slovak (Slovenčina) or Slovenian (Slovenščina); please feel free to volunteer your services, and we'll happily show you what is needed to contribute a new language. ## Write a newline character "\n" in a cell (ALT+"Enter") In Microsoft Office Excel you get a line break in a cell by hitting ALT+"Enter". When you do that, it automatically turns on "wrap text" for the cell. Here is how to achieve this in PhpSpreadsheet: ```php $spreadsheet->getActiveSheet()->getCell('A1')->setValue("hello\nworld"); $spreadsheet->getActiveSheet()->getStyle('A1')->getAlignment()->setWrapText(true); ``` **Tip** Read more about formatting cells using `getStyle()` elsewhere. **Tip** AdvancedValuebinder.php automatically turns on "wrap text" for the cell when it sees a newline character in a string that you are inserting in a cell. Just like Microsoft Office Excel. Try this: ```php // Old method using static property \PhpOffice\PhpSpreadsheet\Cell\Cell::setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() ); // Preferred method using dynamic property since 3.4.0 $spreadsheet->setValueBinder( new \PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder() ); $spreadsheet->getActiveSheet()->getCell('A1')->setValue("hello\nworld"); ``` Read more about AdvancedValueBinder.php elsewhere. ## Explicitly set a cell's datatype You can set a cell's datatype explicitly by using the cell's setValueExplicit method, or the setCellValueExplicit method of a worksheet. Here's an example: ```php $spreadsheet->getActiveSheet()->getCell('A1') ->setValueExplicit( '25', \PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_NUMERIC ); ``` ## Change a cell into a clickable URL You can make a cell (or, for Xlsx only, a drawing) a clickable URL by setting its hyperlink property: ```php $spreadsheet->getActiveSheet()->setCellValue('E26', 'www.example.com'); $spreadsheet->getActiveSheet()->getCell('E26') ->getHyperlink() ->setUrl('https://www.example.com'); ``` If you want to make a hyperlink to another worksheet/cell, use the following code: ```php $spreadsheet->getActiveSheet() ->setCellValue('E27', 'go to another sheet'); $spreadsheet->getActiveSheet()->getCell('E27') ->getHyperlink() ->setUrl("sheet://'Sheetname'!A1"); ``` Xlsx format uses `#` in place of `sheet://`. PhpSpreadsheet will automatically convert to that form when writing a spreadsheet, so you should continue to use `sheet://` for greater interoperability. Excel automatically supplies a special style when a hyperlink is entered into a cell. PhpSpreadsheet cannot do so. However, starting with release 4.3, you can mimic Excel's behavior with: ```php $spreadsheet->getActiveSheet() ->getStyle('E26') ->getFont() ->setHyperlinkTheme(); ``` This will set underline (all formats) and text color (always for Xlsx, and usually for other formats). ## Setting Printer Options for Excel files ### Setting a worksheet's page orientation and size Setting a worksheet's page orientation and size can be done using the following lines of code: ```php $spreadsheet->getActiveSheet()->getPageSetup() ->setOrientation(\PhpOffice\PhpSpreadsheet\Worksheet\PageSetup::ORIENTATION_LANDSCAPE); $spreadsheet->getActiveSheet()->getPageSetup() ->setPaperSize(\PhpOffice\PhpSpreadsheet\Worksheet\PageSetup::PAPERSIZE_A4); ``` Note that there are additional page settings available. Please refer to the [API documentation](https://phpoffice.github.io/PhpSpreadsheet) for all possible options. The default papersize is initially PAPERSIZE_LETTER. However, this default can be changed for new sheets with the following call: ```php \PhpOffice\PhpSpreadsheet\Worksheet\PageSetup::setPaperSizeDefault( \PhpOffice\PhpSpreadsheet\Worksheet\PageSetup::PAPERSIZE_A4 ); ``` The default orientation is ORIENTATION_DEFAULT, which will be treated as Portrait in Excel. However, this default can be changed for new sheets with the following call: ```php \PhpOffice\PhpSpreadsheet\Worksheet\PageSetup::setOrientationDefault( \PhpOffice\PhpSpreadsheet\Worksheet\PageSetup::ORIENTATION_LANDSCAPE ); ``` ### Page Setup: Scaling options The page setup scaling options in PhpSpreadsheet relate directly to the scaling options in the "Page Setup" dialog as shown in the illustration. Default values in PhpSpreadsheet correspond to default values in MS Office Excel as shown in illustration  method | initial value | calling method will trigger | Note --------------------|:-------------:|-----------------------------|------ setFitToPage(...) | FALSE | - | setScale(...) | 100 | setFitToPage(FALSE) | setFitToWidth(...) | 1 | setFitToPage(TRUE) | value 0 means do-not-fit-to-width setFitToHeight(...) | 1 | setFitToPage(TRUE) | value 0 means do-not-fit-to-height #### Example Here is how to fit to 1 page wide by infinite pages tall: ```php $spreadsheet->getActiveSheet()->getPageSetup()->setFitToWidth(1); $spreadsheet->getActiveSheet()->getPageSetup()->setFitToHeight(0); ``` As you can see, it is not necessary to call setFitToPage(TRUE) since setFitToWidth(...) and setFitToHeight(...) triggers this. If you use `setFitToWidth()` you should in general also specify `setFitToHeight()` explicitly like in the example. Be careful relying on the initial values. ### Page margins To set page margins for a worksheet, use this code: ```php $spreadsheet->getActiveSheet()->getPageMargins()->setTop(1); $spreadsheet->getActiveSheet()->getPageMargins()->setRight(0.75); $spreadsheet->getActiveSheet()->getPageMargins()->setLeft(0.75); $spreadsheet->getActiveSheet()->getPageMargins()->setBottom(1); ``` Note that the margin values are specified in inches.  ### Center a page horizontally/vertically To center a page horizontally/vertically, you can use the following code: ```php $spreadsheet->getActiveSheet()->getPageSetup()->setHorizontalCentered(true); $spreadsheet->getActiveSheet()->getPageSetup()->setVerticalCentered(false); ``` ### Setting the print header and footer of a worksheet Setting a worksheet's print header and footer can be done using the following lines of code: ```php $spreadsheet->getActiveSheet()->getHeaderFooter() ->setOddHeader('&C&HPlease treat this document as confidential!'); $spreadsheet->getActiveSheet()->getHeaderFooter() ->setOddFooter('&L&B' . $spreadsheet->getProperties()->getTitle() . '&RPage &P of &N'); ``` Notice the use of `oddHeader/Footer` above. This is, by default, the header used on all pages, not just the odd-numbered pages. You can specify a different header/footer for the first page and/or for even-numbered pages. ```php $spreadsheet->getActiveSheet()->getHeaderFooter() ->setDifferentFirst(true); // then as above except setFirstHeader/Footer rather than Odd $spreadsheet->getActiveSheet()->getHeaderFooter() ->setDifferentOddEven(true); // then as above except setEvenHeader/Footer rather than Odd ``` Substitution and formatting codes (starting with &) can be used inside headers and footers. There is no required order in which these codes must appear. The first occurrence of the following codes turns the formatting ON, the second occurrence turns it OFF again: - Strikethrough - Superscript - Subscript Superscript and subscript cannot both be ON at same time. Whichever comes first wins and the other is ignored, while the first is ON. The following codes are supported by Xlsx: Code | Meaning -------------------------|----------- `&L` | Code for "left section" (there are three header / footer locations, "left", "center", and "right"). When two or more occurrences of this section marker exist, the contents from all markers are concatenated, in the order of appearance, and placed into the left section. `&P` | Code for "current page #" `&N` | Code for "total pages" `&font size` | Code for "text font size", where font size is a font size in points. `&K` | Code for "text font color" - RGB Color is specified as RRGGBB Theme Color is specifed as TTSNN where TT is the theme color Id, S is either "+" or "-" of the tint/shade value, NN is the tint/shade value. `&S` | Code for "text strikethrough" on / off `&X` | Code for "text super script" on / off `&Y` | Code for "text subscript" on / off `&C` | Code for "center section". When two or more occurrences of this section marker exist, the contents from all markers are concatenated, in the order of appearance, and placed into the center section. `&D` | Code for "date" `&T` | Code for "time" `&G` | Code for "picture as background" - Please make sure to add the image to the header/footer (see [Tip for picture](#Tip-for-picture)) `&U` | Code for "text single underline" `&E` | Code for "double underline" `&R` | Code for "right section". When two or more occurrences of this section marker exist, the contents from all markers are concatenated, in the order of appearance, and placed into the right section. `&Z` | Code for "this workbook's file path" `&F` | Code for "this workbook's file name" `&A` | Code for "sheet tab name" `&+` | Code for add to page # `&-` | Code for subtract from page # `&"font name,font type"` | Code for "text font name" and "text font type", where font name and font type are strings specifying the name and type of the font, separated by a comma. When a hyphen appears in font name, it means "none specified". Both of font name and font type can be localized values. `&"-,Bold"` | Code for "bold font style" `&B` | Code for "bold font style" `&"-,Regular"` | Code for "regular font style" `&"-,Italic"` | Code for "italic font style" `&I` | Code for "italic font style" `&"-,Bold Italic"` | Code for "bold italic font style" `&O` | Code for "outline style" `&H` | Code for "shadow style" **Tip** The above table of codes may seem overwhelming first time you are trying to figure out how to write some header or footer. Luckily, there is an easier way. Let Microsoft Office Excel do the work for you.For example, create in Microsoft Office Excel an xlsx file where you insert the header and footer as desired using the programs own interface. Save file as test.xlsx. Now, take that file and read off the values using PhpSpreadsheet as follows: ```php $spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load('test.xlsx'); $worksheet = $spreadsheet->getActiveSheet(); var_dump($worksheet->getHeaderFooter()->getOddFooter()); var_dump($worksheet->getHeaderFooter()->getEvenFooter()); var_dump($worksheet->getHeaderFooter()->getOddHeader()); var_dump($worksheet->getHeaderFooter()->getEvenHeader()); ``` That reveals the codes for the even/odd header and footer. Experienced users may find it easier to rename test.xlsx to test.zip, unzip it, and inspect directly the contents of the relevant xl/worksheets/sheetX.xml to find the codes for header/footer. **Tip for picture** ```php $drawing = new \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooterDrawing(); $drawing->setName('PhpSpreadsheet logo'); $drawing->setPath('./images/PhpSpreadsheet_logo.png'); $drawing->setHeight(36); $spreadsheet->getActiveSheet() ->getHeaderFooter() ->addImage( $drawing, \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooter::IMAGE_HEADER_LEFT ); ``` If you want your image to be used only on the first page or only on even pages, use, for example, `HeaderFooter::IMAGE_FOOTER_CENTER_EVEN`. You must still call [`setDifferentFirst/Even`](#setDifferent) for this to work. This will work only for Xlsx. ### Setting printing breaks on a row or column To set a print break, use the following code, which sets a row break on row 10. ```php $spreadsheet->getActiveSheet()->setBreak( 'A10', \PhpOffice\PhpSpreadsheet\Worksheet\Worksheet::BREAK_ROW ); ``` The following line of code sets a print break on column D: ```php $spreadsheet->getActiveSheet()->setBreak( 'D10', \PhpOffice\PhpSpreadsheet\Worksheet\Worksheet::BREAK_COLUMN ); ``` ### Show/hide gridlines when printing To show/hide gridlines when printing, use the following code: ```php $spreadsheet->getActiveSheet()->setPrintGridlines(true); ``` ### Setting rows/columns to repeat at top/left PhpSpreadsheet can repeat specific rows/cells at top/left of a page. The following code is an example of how to repeat row 1 to 5 on each printed page of a specific worksheet: ```php $spreadsheet->getActiveSheet()->getPageSetup()->setRowsToRepeatAtTopByStartAndEnd(1, 5); ``` ### Specify printing area To specify a worksheet's printing area, use the following code: ```php $spreadsheet->getActiveSheet()->getPageSetup()->setPrintArea('A1:E5'); ``` There can also be multiple printing areas in a single worksheet: ```php $spreadsheet->getActiveSheet()->getPageSetup()->setPrintArea('A1:E5,G4:M20'); ``` ## Styles ### Formatting cells A cell can be formatted with font, border, fill, ... style information. For example, one can set the foreground colour of a cell to red, aligned to the right, and the border to black and thick border style. Let's do that on cell B2: ```php $spreadsheet->getActiveSheet()->getStyle('B2') ->getFont()->getColor()->setARGB(\PhpOffice\PhpSpreadsheet\Style\Color::COLOR_RED); $spreadsheet->getActiveSheet()->getStyle('B2') ->getAlignment()->setHorizontal(\PhpOffice\PhpSpreadsheet\Style\Alignment::HORIZONTAL_RIGHT); $spreadsheet->getActiveSheet()->getStyle('B2') ->getBorders()->getTop()->setBorderStyle(\PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK); $spreadsheet->getActiveSheet()->getStyle('B2') ->getBorders()->getBottom()->setBorderStyle(\PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK); $spreadsheet->getActiveSheet()->getStyle('B2') ->getBorders()->getLeft()->setBorderStyle(\PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK); $spreadsheet->getActiveSheet()->getStyle('B2') ->getBorders()->getRight()->setBorderStyle(\PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK); $spreadsheet->getActiveSheet()->getStyle('B2') ->getFill()->setFillType(\PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID); $spreadsheet->getActiveSheet()->getStyle('B2') ->getFill()->getStartColor()->setARGB('FFFF0000'); ``` `getStyle()` also accepts a cell range as a parameter. For example, you can set a red background color on a range of cells: ```php $spreadsheet->getActiveSheet()->getStyle('B3:B7')->getFill() ->setFillType(\PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID) ->getStartColor()->setARGB('FFFF0000'); ``` **Tip** It is recommended to style many cells at once, using e.g. getStyle('A1:M500'), rather than styling the cells individually in a loop. This is much faster compared to looping through cells and styling them individually. **Tip** If you are styling entire row(s) or column(s), e.g. getStyle('A:A'), it is recommended to use applyFromArray as described below rather than setting the styles individually as described above. Also, starting with release 3.9.0, you should use getRowStyle or getColumnStyle to get the style for an entire row or column. There is also an alternative manner to set styles. The following code sets a cell's style to font bold, alignment right, top border thin and a gradient fill: ```php $styleArray = [ 'font' => [ 'bold' => true, ], 'alignment' => [ 'horizontal' => \PhpOffice\PhpSpreadsheet\Style\Alignment::HORIZONTAL_RIGHT, ], 'borders' => [ 'top' => [ 'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THIN, ], ], 'fill' => [ 'fillType' => \PhpOffice\PhpSpreadsheet\Style\Fill::FILL_GRADIENT_LINEAR, 'rotation' => 90, 'startColor' => [ 'argb' => 'FFA0A0A0', ], 'endColor' => [ 'argb' => 'FFFFFFFF', ], ], ]; $spreadsheet->getActiveSheet()->getStyle('A3')->applyFromArray($styleArray); ``` Or with a range of cells: ```php $spreadsheet->getActiveSheet()->getStyle('B3:B7')->applyFromArray($styleArray); ``` This alternative method using arrays should be faster in terms of execution whenever you are setting more than one style property. But the difference may barely be measurable unless you have many different styles in your workbook. You can perform the opposite function, exporting a Style as an array, as follows: ``` php $styleArray = $spreadsheet->getActiveSheet()->getStyle('A3')->exportArray(); ``` ### Number formats You often want to format numbers in Excel. For example you may want a thousands separator plus a fixed number of decimals after the decimal separator. Or perhaps you want some numbers to be zero-padded. In Microsoft Office Excel you may be familiar with selecting a number format from the "Format Cells" dialog. Here there are some predefined number formats available including some for dates. The dialog is designed in a way so you don't have to interact with the underlying raw number format code unless you need a custom number format. In PhpSpreadsheet, you can also apply various predefined number formats. Example: ```php $spreadsheet->getActiveSheet()->getStyle('A1')->getNumberFormat() ->setFormatCode(\PhpOffice\PhpSpreadsheet\Style\NumberFormat::FORMAT_NUMBER_COMMA_SEPARATED1); ``` This will format a number e.g. 1587.2 so it shows up as 1,587.20 when you open the workbook in MS Office Excel. (Depending on settings for decimal and thousands separators in Microsoft Office Excel it may show up as 1.587,20) You can achieve exactly the same as the above by using this: ```php $spreadsheet->getActiveSheet()->getStyle('A1')->getNumberFormat() ->setFormatCode('#,##0.00'); ``` In Microsoft Office Excel, as well as in PhpSpreadsheet, you will have to interact with raw number format codes whenever you need some special custom number format. Example: ```php $spreadsheet->getActiveSheet()->getStyle('A1')->getNumberFormat() ->setFormatCode('[Blue][>=3000]$#,##0;[Red][<0]$#,##0;$#,##0'); ``` Another example is when you want numbers zero-padded with leading zeros to a fixed length: ```php $spreadsheet->getActiveSheet()->getCell('A1')->setValue(19); $spreadsheet->getActiveSheet()->getStyle('A1')->getNumberFormat() ->setFormatCode('0000'); // will show as 0019 in Excel ``` **Tip** The rules for composing a number format code in Excel can be rather complicated. Sometimes you know how to create some number format in Microsoft Office Excel, but don't know what the underlying number format code looks like. How do you find it? The readers shipped with PhpSpreadsheet come to the rescue. Load your template workbook using e.g. Xlsx reader to reveal the number format code. Example how read a number format code for cell A1: ```php $reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader('Xlsx'); $spreadsheet = $reader->load('template.xlsx'); var_dump($spreadsheet->getActiveSheet()->getStyle('A1')->getNumberFormat()->getFormatCode()); ``` Advanced users may find it faster to inspect the number format code directly by renaming template.xlsx to template.zip, unzipping, and looking for the relevant piece of XML code holding the number format code in *xl/styles.xml*. ### Alignment and wrap text Let's set vertical alignment to the top for cells A1:D4 ```php $spreadsheet->getActiveSheet()->getStyle('A1:D4') ->getAlignment()->setVertical(\PhpOffice\PhpSpreadsheet\Style\Alignment::VERTICAL_TOP); ``` Here is how to achieve wrap text: ```php $spreadsheet->getActiveSheet()->getStyle('A1:D4') ->getAlignment()->setWrapText(true); ``` ### Setting the default style of a workbook It is possible to set the default style of a workbook. Let's set the default font to Arial size 8: ```php $spreadsheet->getDefaultStyle()->getFont()->setName('Arial'); $spreadsheet->getDefaultStyle()->getFont()->setSize(8); ``` Excel also offers "theme fonts", with separate font names for major (header) and minor (body) text. PhpSpreadsheet will use the Excel 2007 default (Cambria) for major (default is Calibri Light in Excel 2013+); PhpSpreadsheet default for minor is Calibri, which is used by Excel 2007+. To align the default font name with the minor font name: ```php $spreadsheet->getTheme() ->setThemeFontName('custom') ->setMinorFontValues('Arial', 'Arial', 'Arial', []); $spreadsheet->getDefaultStyle()->getFont()->setScheme('minor'); ``` All cells bound to the theme fonts (via the `Font::setScheme` method) can be easily changed to a different font in Excel. To do this in PhpSpreadsheet, an additional method call is needed: ```php $spreadsheet->resetThemeFonts(); ``` ### Charset for Arabic and Persian Fonts It is unknown why this should be needed. However, some Excel users have reported better results if the internal declaration for an Arabic/Persian font includes a `charset` declaration. This seems like a bug in Excel, but, starting with release 4.4, this can be accomplished at the spreadsheet level, via: ```php $spreadsheet->addFontCharset('C Nazanin'); ``` As many charsets as desired can be added in this manner. There is a second optional parameter specifying the charset id to this method, but, since this seems to be needed only for Arabic/Persian, that is its default value. ### Styling cell borders In PhpSpreadsheet it is easy to apply various borders on a rectangular selection. Here is how to apply a thick red border outline around cells B2:G8. ```php $styleArray = [ 'borders' => [ 'outline' => [ 'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK, 'color' => ['argb' => 'FFFF0000'], ], ], ]; $worksheet->getStyle('B2:G8')->applyFromArray($styleArray); ``` In Microsoft Office Excel, the above operation would correspond to selecting the cells B2:G8, launching the style dialog, choosing a thick red border, and clicking on the "Outline" border component. Note that the border outline is applied to the rectangular selection B2:G8 as a whole, not on each cell individually. You can achieve any border effect by using just the 5 basic borders and operating on a single cell at a time: - left - right - top - bottom - diagonal Additional shortcut borders come in handy like in the example above. These are the shortcut borders available: - allBorders - outline - inside - vertical - horizontal An overview of all border shortcuts can be seen in the following image:  If you simultaneously set e.g. allBorders and vertical, then we have "overlapping" borders, and one of the components has to win over the other where there is border overlap. In PhpSpreadsheet, from weakest to strongest borders, the list is as follows: allBorders, outline/inside, vertical/horizontal, left/right/top/bottom/diagonal. This border hierarchy can be utilized to achieve various effects in an easy manner. #### Advanced borders There is a second parameter `$advancedBorders` which can be supplied to applyFromArray. The default is `true`; when set to this value, the border styles are applied to the range as a whole, not to the individual cells. When set to `false`, the border styles are applied to each cell. The following code and screenshot demonstrates the difference. ```php $sheet->setShowGridlines(false); $styleArray = [ 'borders' => [ 'bottom' => ['borderStyle' => 'hair', 'color' => ['argb' => 'FFFF0000']], 'top' => ['borderStyle' => 'hair', 'color' => ['argb' => 'FFFF0000']], 'right' => ['borderStyle' => 'hair', 'color' => ['argb' => 'FF00FF00']], 'left' => ['borderStyle' => 'hair', 'color' => ['argb' => 'FF00FF00']], ], ]; $sheet->getStyle('B2:C3')->applyFromArray($styleArray); $sheet->getStyle('B5:C6')->applyFromArray($styleArray, false); ```  ### Valid array keys for style `applyFromArray()` The following table lists the valid array keys for `\PhpOffice\PhpSpreadsheet\Style\Style::applyFromArray()` classes. If the "Maps to property" column maps a key to a setter, the value provided for that key will be applied directly. If the "Maps to property" column maps a key to a getter, the value provided for that key will be applied as another style array. **\PhpOffice\PhpSpreadsheet\Style\Style** Array key | Maps to property -------------|------------------- alignment | setAlignment() borders | setBorders() fill | setFill() font | setFont() numberFormat | setNumberFormat() protection | setProtection() quotePrefix | setQuotePrefix() **\PhpOffice\PhpSpreadsheet\Style\Alignment** Array key | Maps to property ----------------|------------------- horizontal | setHorizontal() justifyLastLine | setJustifyLastLine() indent | setIndent() readOrder | setReadOrder() shrinkToFit | setShrinkToFit() textRotation | setTextRotation() vertical | setVertical() wrapText | setWrapText() **\PhpOffice\PhpSpreadsheet\Style\Border** Array key | Maps to property ------------|------------------- borderStyle | setBorderStyle() color | setColor() **\PhpOffice\PhpSpreadsheet\Style\Borders** Array key | Maps to property ------------------|------------------- allBorders | getLeft(); getRight(); getTop(); getBottom() bottom | getBottom() diagonal | getDiagonal() diagonalDirection | setDiagonalDirection() left | getLeft() right | getRight() top | getTop() **\PhpOffice\PhpSpreadsheet\Style\Color** Array key | Maps to property ------------|------------------- argb | setARGB() **\PhpOffice\PhpSpreadsheet\Style\Fill** Array key | Maps to property -----------|------------------- color | getStartColor() endColor | getEndColor() fillType | setFillType() rotation | setRotation() startColor | getStartColor() **\PhpOffice\PhpSpreadsheet\Style\Font** Array key | Maps to property ------------|------------------- bold | setBold() color | getColor() italic | setItalic() name | setName() size | setSize() strikethrough | setStrikethrough() subscript | setSubscript() superscript | setSuperscript() underline | setUnderline() **\PhpOffice\PhpSpreadsheet\Style\NumberFormat** Array key | Maps to property ----------|------------------- formatCode | setFormatCode() **\PhpOffice\PhpSpreadsheet\Style\Protection** Array key | Maps to property ----------|------------------- locked | setLocked() hidden | setHidden() ## Conditional formatting a cell A cell can be formatted conditionally, based on a specific rule. For example, one can set the foreground colour of a cell to red if its value is below zero, and to green if its value is zero or more. One can set a conditional style ruleset to a cell using the following code: ```php $conditional1 = new \PhpOffice\PhpSpreadsheet\Style\Conditional(); $conditional1->setConditionType(\PhpOffice\PhpSpreadsheet\Style\Conditional::CONDITION_CELLIS); $conditional1->setOperatorType(\PhpOffice\PhpSpreadsheet\Style\Conditional::OPERATOR_LESSTHAN); $conditional1->addCondition('0'); $conditional1->getStyle()->getFont()->getColor()->setARGB(\PhpOffice\PhpSpreadsheet\Style\Color::COLOR_RED); $conditional1->getStyle()->getFont()->setBold(true); $conditional2 = new \PhpOffice\PhpSpreadsheet\Style\Conditional(); $conditional2->setConditionType(\PhpOffice\PhpSpreadsheet\Style\Conditional::CONDITION_CELLIS); $conditional2->setOperatorType(\PhpOffice\PhpSpreadsheet\Style\Conditional::OPERATOR_GREATERTHANOREQUAL); $conditional2->addCondition('0'); $conditional2->getStyle()->getFont()->getColor()->setARGB(\PhpOffice\PhpSpreadsheet\Style\Color::COLOR_GREEN); $conditional2->getStyle()->getFont()->setBold(true); $conditionalStyles = $spreadsheet->getActiveSheet()->getStyle('B2')->getConditionalStyles(); $conditionalStyles[] = $conditional1; $conditionalStyles[] = $conditional2; $spreadsheet->getActiveSheet()->getStyle('B2')->setConditionalStyles($conditionalStyles); ``` If you want to copy the ruleset to other cells, you can duplicate the style object: ```php $spreadsheet->getActiveSheet() ->duplicateConditionalStyle( $spreadsheet->getActiveSheet()->getConditionalStyles('B2'), 'B3:B7' ); ``` More detailed documentation of the Conditional Formatting options and rules, and the use of Wizards to help create them, can be found in [a dedicated section of the documentation](https://phpspreadsheet.readthedocs.io/en/latest/topics/conditional-formatting/). ### DataBar of Conditional formatting The basics are the same as conditional formatting. Additional DataBar object to conditional formatting. For example, the following code will result in the conditional formatting shown in the image. ```php $conditional = new Conditional(); $conditional->setConditionType(Conditional::CONDITION_DATABAR); $conditional->setDataBar(new ConditionalDataBar()); $conditional->getDataBar() ->setMinimumConditionalFormatValueObject(new ConditionalFormatValueObject('num', '2')) ->setMaximumConditionalFormatValueObject(new ConditionalFormatValueObject('max')) ->setColor('FFFF555A'); $ext = $conditional ->getDataBar() ->setConditionalFormattingRuleExt(new ConditionalFormattingRuleExtension()) ->getConditionalFormattingRuleExt(); $ext->setCfRule('dataBar'); $ext->setSqref('A1:A5'); // target CellCoordinates $ext->setDataBarExt(new ConditionalDataBarExtension()); $ext->getDataBarExt() ->setMinimumConditionalFormatValueObject(new ConditionalFormatValueObject('num', '2')) ->setMaximumConditionalFormatValueObject(new ConditionalFormatValueObject('autoMax')) ->setMinLength(0) ->setMaxLength(100) ->setBorder(true) ->setDirection('rightToLeft') ->setNegativeBarBorderColorSameAsPositive(false) ->setBorderColor('FFFF555A') ->setNegativeFillColor('FFFF0000') ->setNegativeBorderColor('FFFF0000') ->setAxisColor('FF000000'); ```  ## Add a comment to a cell To add a comment to a cell, use the following code. The example below adds a comment to cell E11: ```php $spreadsheet->getActiveSheet() ->getComment('E11') ->setAuthor('Mark Baker'); $commentRichText = $spreadsheet->getActiveSheet() ->getComment('E11') ->getText()->createTextRun('PhpSpreadsheet:'); $commentRichText->getFont()->setBold(true); $spreadsheet->getActiveSheet() ->getComment('E11') ->getText()->createTextRun("\r\n"); $spreadsheet->getActiveSheet() ->getComment('E11') ->getText()->createTextRun('Total amount on the current invoice, excluding VAT.'); ```  ## Add a comment with background image to a cell To add a comment with background image to a cell, use the following code: ```php $sheet = $spreadsheet->getActiveSheet(); $sheet->setCellValue('B5', 'Gibli Chromo'); // Add png image to comment background $drawing = new Drawing(); $drawing->setName('Gibli Chromo'); $drawing->setPath('/tmp/gibli_chromo.png'); $comment = $sheet->getComment('B5'); $comment->setBackgroundImage($drawing); // Set the size of the comment equal to the size of the image $comment->setSizeAsBackgroundImage(); ```  ## Apply autofilter to a range of cells To apply an autofilter to a range of cells, use the following code: ```php $spreadsheet->getActiveSheet()->setAutoFilter('A1:C9'); ``` **Make sure that you always include the complete filter range!** Excel does support setting only the caption row, but that's **not** a best practice... ## Setting security on a spreadsheet Excel offers 3 levels of "protection": - Document: allows you to set a password on a complete spreadsheet, allowing changes to be made only when that password is entered. - Worksheet: offers other security options: you can disallow inserting rows on a specific sheet, disallow sorting, ... - Cell: offers the option to lock/unlock a cell as well as show/hide the internal formula. **Make sure you enable worksheet protection if you need any of the worksheet or cell protection features!** This can be done using the following code: ```php $spreadsheet->getActiveSheet()->getProtection()->setSheet(true); ``` > Note that "protection" is not the same as "encryption". > Protection is about preventing parts of a spreadsheet from being changed, not about preventing the spreadsheet from being looked at.
PhpSpreadsheet does not support encrypting a spreadsheet; nor can it read encrypted spreadsheets. ### Document An example on setting document security: ```php $security = $spreadsheet->getSecurity(); $security->setLockWindows(true); $security->setLockStructure(true); $security->setWorkbookPassword("PhpSpreadsheet"); ``` Note that there are additional methods setLockRevision and setRevisionsPassword which apply only to change tracking and history for shared workbooks. ### Worksheet An example on setting worksheet security (user can sort, insert rows, or format cells without unprotecting): ```php $protection = $spreadsheet->getActiveSheet()->getProtection(); $protection->setPassword('PhpSpreadsheet'); $protection->setSheet(true); $protection->setSort(false); $protection->setInsertRows(false); $protection->setFormatCells(false); ``` Note that allowing sort without providing the sheet password (similarly with autoFilter) requires that you explicitly enable the cell ranges for which sort is permitted, with or without a range password: ```php $sheet->protectCells('A:A'); // column A can be sorted without password $sheet->protectCells('B:B', 'sortpw'); // column B can be sorted if the range password sortpw is supplied ``` If writing Xlsx files you can specify the algorithm used to hash the password before calling `setPassword()` like so: ```php $protection = $spreadsheet->getActiveSheet()->getProtection(); $protection->setAlgorithm(Protection::ALGORITHM_SHA_512); $protection->setSpinCount(20000); $protection->setPassword('PhpSpreadsheet'); ``` The salt should **not** be set manually and will be automatically generated when setting a new password. ### Cell An example on setting cell security. Note that cell security is honored only when sheet is protected. Also note that the `hidden` property applies only to formulas, and tells whether the formula is hidden on the formula bar, not in the cell. ```php $spreadsheet->getActiveSheet()->getStyle('B1') ->getProtection() ->setLocked(\PhpOffice\PhpSpreadsheet\Style\Protection::PROTECTION_UNPROTECTED) ->setHidden(\PhpOffice\PhpSpreadsheet\Style\Protection::PROTECTION_PROTECTED); ``` ## Reading protected spreadsheet Spreadsheets that are protected as described above can always be read by PhpSpreadsheet. There is no need to know the password or do anything special in order to read a protected file. However if you need to implement a password verification mechanism, you can use the following helper method: ```php $protection = $spreadsheet->getActiveSheet()->getProtection(); $allowed = $protection->verify('my password'); if ($allowed) { doSomething(); } else { throw new Exception('Incorrect password'); } ``` If you need to completely prevent reading a file by any tool, including PhpSpreadsheet, then you are looking for "encryption", not "protection". ## Setting data validation on a cell Data validation is a powerful feature of Xlsx. It allows to specify an input filter on the data that can be inserted in a specific cell. This filter can be a range (i.e. value must be between 0 and 10), a list (i.e. value must be picked from a list), ... The following piece of code only allows numbers between 10 and 20 to be entered in cell B3: ```php $validation = $spreadsheet->getActiveSheet()->getCell('B3') ->getDataValidation(); $validation->setType( \PhpOffice\PhpSpreadsheet\Cell\DataValidation::TYPE_WHOLE ); $validation->setErrorStyle( \PhpOffice\PhpSpreadsheet\Cell\DataValidation::STYLE_STOP ); $validation->setAllowBlank(true); $validation->setShowInputMessage(true); $validation->setShowErrorMessage(true); $validation->setErrorTitle('Input error'); $validation->setError('Number is not allowed!'); $validation->setPromptTitle('Allowed input'); $validation->setPrompt('Only numbers between 10 and 20 are allowed.'); $validation->setFormula1(10); $validation->setFormula2(20); ``` The following piece of code only allows an item picked from a list of data to be entered in cell B5: ```php $validation = $spreadsheet->getActiveSheet()->getCell('B5') ->getDataValidation(); $validation->setType( \PhpOffice\PhpSpreadsheet\Cell\DataValidation::TYPE_LIST ); $validation->setErrorStyle( \PhpOffice\PhpSpreadsheet\Cell\DataValidation::STYLE_INFORMATION ); $validation->setAllowBlank(false); $validation->setShowInputMessage(true); $validation->setShowErrorMessage(true); $validation->setShowDropDown(true); $validation->setErrorTitle('Input error'); $validation->setError('Value is not in list.'); $validation->setPromptTitle('Pick from list'); $validation->setPrompt('Please pick a value from the drop-down list.'); $validation->setFormula1('"Item A,Item B,Item C"'); ``` When using a data validation list like above, make sure you put the list between `"` and `"` and that you split the items with a comma (`,`). It is important to remember that any string participating in an Excel formula is allowed to be maximum 255 characters (not bytes). This sets a limit on how many items you can have in the string "Item A,Item B,Item C". Therefore it is normally a better idea to type the item values directly in some cell range, say A1:A3, and instead use, say, `$validation->setFormula1('\'Sheet title\'!$A$1:$A$3')`. Another benefit is that the item values themselves can contain the comma `,` character itself. ### Setting Validation on Multiple Cells - Release 3 and Below If you need data validation on multiple cells, one can clone the ruleset: ```php $spreadsheet->getActiveSheet()->getCell('B8')->setDataValidation(clone $validation); ``` Alternatively, one can apply the validation to a range of cells: ```php $validation->setSqref('B5:B1048576'); ``` ### Setting Validation on Multiple Cells - Release 4 and Above Starting with Release 4, Data Validation can be set simultaneously on several cells/cell ranges. ```php $spreadsheet->getActiveSheet()->getDataValidation('A1:A4 D5 E6:E7') ->set...(...); ``` In theory, this means that more than one Data Validation can apply to a cell. It appears that, when Excel reads a spreadsheet with more than one Data Validation applying to a cell, whichever appears first in the Xml is what Xml uses. PhpSpreadsheet will instead apply a DatValidation applying to a single cell first; then, if it doesn't find such a match, it will use the first applicable definition which is read (or created after or in lieu of reading). This allows you, for example, to set Data Validation on all but a few cells in a column: ```php $dv = new DataValidation(); $dv->setType(DataValidation::TYPE_NONE); $sheet->setDataValidation('A5:A7', $dv); $dv = new DataValidation(); $dv->set...(...); $sheet->setDataValidation('A:A', $dv); $dv = new DataValidation(); $dv->setType(DataValidation::TYPE_NONE); $sheet->setDataValidation('A9', $dv); ``` ## Setting a column's width A column's width can be set using the following code: ```php $spreadsheet->getActiveSheet()->getColumnDimension('D')->setWidth(12); ``` If you want to set a column width using a different UoM (Unit of Measure), then you can do so by telling PhpSpreadsheet what UoM the width value that you are setting is measured in. Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches), `cm` (centimeters) and `mm` (millimeters). Setting the column width to `-1` tells MS Excel to display the column using its default width. ```php $spreadsheet->getActiveSheet()->getColumnDimension('D')->setWidth(120, 'pt'); ``` If you want PhpSpreadsheet to perform an automatic width calculation, use the following code. PhpSpreadsheet will approximate the column width to the width of the widest value displayed in that column. ```php $spreadsheet->getActiveSheet()->getColumnDimension('B')->setAutoSize(true); ```  The measure for column width in PhpSpreadsheet does **not** correspond exactly to the measure you may be used to in Microsoft Office Excel. Column widths are difficult to deal with in Excel, and there are several measures for the column width. 1. Inner width in character units (e.g. 8.43 this is probably what you are familiar with in Excel) 2. Full width in pixels (e.g. 64 pixels) 3. Full width in character units (e.g. 9.140625, value -1 indicates unset width) **PhpSpreadsheet always operates with "3. Full width in character units"** which is in fact the only value that is stored in any Excel file, hence the most reliable measure. Unfortunately, **Microsoft Office Excel does not present you with this measure**. Instead measures 1 and 2 are computed by the application when the file is opened and these values are presented in various dialogues and tool tips. The character width unit is the width of a `0` (zero) glyph in the workbooks default font. Therefore column widths measured in character units in two different workbooks can only be compared if they have the same default workbook font.If you have some Excel file and need to know the column widths in measure 3, you can read the Excel file with PhpSpreadsheet and echo the retrieved values. ## Show/hide a column To set a worksheet's column visibility, you can use the following code. The first line explicitly shows the column C, the second line hides column D. ```php $spreadsheet->getActiveSheet()->getColumnDimension('C')->setVisible(true); $spreadsheet->getActiveSheet()->getColumnDimension('D')->setVisible(false); ``` ## Group/outline a column To group/outline a column, you can use the following code: ```php $spreadsheet->getActiveSheet()->getColumnDimension('E')->setOutlineLevel(1); ``` You can also collapse the column. Note that you should also set the column invisible, otherwise the collapse will not be visible in Excel 2007. ```php $spreadsheet->getActiveSheet()->getColumnDimension('E')->setCollapsed(true); $spreadsheet->getActiveSheet()->getColumnDimension('E')->setVisible(false); ``` Please refer to the section "group/outline a row" for a complete example on collapsing. You can instruct PhpSpreadsheet to add a summary to the right (default), or to the left. The following code adds the summary to the left: ```php $spreadsheet->getActiveSheet()->setShowSummaryRight(false); ``` ## Setting a row's height A row's height can be set using the following code: ```php $spreadsheet->getActiveSheet()->getRowDimension('10')->setRowHeight(100); ``` Excel measures row height in points, where 1 pt is 1/72 of an inch (or about 0.35mm). The default value is 12.75 pts; and the permitted range of values is between 0 and 409 pts, where 0 pts is a hidden row. If you want to set a row height using a different UoM (Unit of Measure), then you can do so by telling PhpSpreadsheet what UoM the height value that you are setting is measured in. Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches), `cm` (centimeters) and `mm` (millimeters). ```php $spreadsheet->getActiveSheet()->getRowDimension('10')->setRowHeight(100, 'pt'); ``` Setting the row height to `-1` tells MS Excel to display the column using its default height, which is based on the character font size. If you have wrapped text in a cell, then the `-1` default will only set the row height to display a single line of that wrapped text. If you need to calculate the actual height for the row, then count the lines that should be displayed (count the `\n` and add 1); then adjust for the font. The adjustment for Calibri 11 is approximately 14.5; for Calibri 12 15.9, etc. ```php $spreadsheet->getActiveSheet()->getRowDimension(1)->setRowHeight( 14.5 * (substr_count($sheet->getCell('A1')->getValue(), "\n") + 1) ); ``` ## Show/hide a row To set a worksheet''s row visibility, you can use the following code. The following example hides row number 10. ```php $spreadsheet->getActiveSheet()->getRowDimension('10')->setVisible(false); ``` Note that if you apply active filters using an AutoFilter, then this will override any rows that you hide or unhide manually within that AutoFilter range if you save the file. ## Group/outline a row To group/outline a row, you can use the following code: ```php $spreadsheet->getActiveSheet()->getRowDimension('5')->setOutlineLevel(1); ``` You can also collapse the row. Note that you should also set the row invisible, otherwise the collapse will not be visible in Excel 2007. ```php $spreadsheet->getActiveSheet()->getRowDimension('5')->setCollapsed(true); $spreadsheet->getActiveSheet()->getRowDimension('5')->setVisible(false); ``` Here's an example which collapses rows 50 to 80: ```php for ($i = 51; $i <= 80; $i++) { $spreadsheet->getActiveSheet()->setCellValue('A' . $i, "FName $i"); $spreadsheet->getActiveSheet()->setCellValue('B' . $i, "LName $i"); $spreadsheet->getActiveSheet()->setCellValue('C' . $i, "PhoneNo $i"); $spreadsheet->getActiveSheet()->setCellValue('D' . $i, "FaxNo $i"); $spreadsheet->getActiveSheet()->setCellValue('E' . $i, true); $spreadsheet->getActiveSheet()->getRowDimension($i)->setOutlineLevel(1); $spreadsheet->getActiveSheet()->getRowDimension($i)->setVisible(false); } $spreadsheet->getActiveSheet()->getRowDimension(81)->setCollapsed(true); ``` You can instruct PhpSpreadsheet to add a summary below the collapsible rows (default), or above. The following code adds the summary above: ```php $spreadsheet->getActiveSheet()->setShowSummaryBelow(false); ``` ## Merge/Unmerge cells If you have a big piece of data you want to display in a worksheet, or a heading that needs to span multiple sub-heading columns, you can merge two or more cells together, to become one cell. This can be done using the following code: ```php $spreadsheet->getActiveSheet()->mergeCells('A18:E22'); ``` Removing a merge can be done using the `unmergeCells()` method: ```php $spreadsheet->getActiveSheet()->unmergeCells('A18:E22'); ``` MS Excel itself doesn't yet offer the functionality to simply hide the merged cells, or to merge the content of cells into a single cell, but it is available in Open/Libre Office. ### Merge with MERGE_CELL_CONTENT_EMPTY The default behaviour is to empty all cells except for the top-left corner cell in the merge range; and this is also the default behaviour for the `mergeCells()` method in PhpSpreadsheet. When this behaviour is applied, those cell values will be set to null; and if they are subsequently Unmerged, they will be empty cells. Passing an extra flag value to the `mergeCells()` method in PhpSpreadsheet can change this behaviour.  Possible flag values are: - Worksheet::MERGE_CELL_CONTENT_EMPTY (the default) - Worksheet::MERGE_CELL_CONTENT_HIDE - Worksheet::MERGE_CELL_CONTENT_MERGE ### Merge with MERGE_CELL_CONTENT_HIDE The first alternative, available only in OpenOffice, is to hide those cells, but to leave their content intact. When a file saved as `Xlsx` in those applications is opened in MS Excel, and those cells are unmerged, the original content will still be present. ```php $spreadsheet->getActiveSheet()->mergeCells('A1:C3', Worksheet::MERGE_CELL_CONTENT_HIDE); ``` Will replicate that behaviour. ### Merge with MERGE_CELL_CONTENT_MERGE The second alternative, available in both OpenOffice and LibreOffice is to merge the content of every cell in the merge range into the top-left cell, while setting those hidden cells to empty. ```php $spreadsheet->getActiveSheet()->mergeCells('A1:C3', Worksheet::MERGE_CELL_CONTENT_MERGE); ``` Particularly when the merged cells contain formulas, the logic for this merge seems strange: walking through the merge range, each cell is calculated in turn, and appended to the "master" cell, then it is emptied, so any subsequent calculations that reference the cell see an empty cell, not the pre-merge value. For example, suppose our spreadsheet contains  where `B2` is the formula `=5-B1` and `C2` is the formula `=A2/B2`, and we want to merge cells `A2` to `C2` with all the cell values merged. The result is:  The cell value `12` from cell `A2` is fixed; the value from `B2` is the result of the formula `=5-B1` (`4`, which is appended to our merged value), and cell `B2` is then emptied, so when we evaluate cell `C2` with the formula `=A2/B2` it gives us `12 / 0` which results in a `#DIV/0!` error (so the error `#DIV/0!` is appended to our merged value rather than the original calculation result of `3`). ## Inserting or Removing rows/columns You can insert/remove rows/columns at a specific position. The following code inserts 2 new rows, right before row 7: ```php $spreadsheet->getActiveSheet()->insertNewRowBefore(7, 2); ``` while ```php $spreadsheet->getActiveSheet()->removeRow(7, 2); ``` will remove 2 rows starting at row number 7 (ie. rows 7 and 8). Equivalent methods exist for inserting/removing columns: ```php $spreadsheet->getActiveSheet()->removeColumn('C', 2); ``` All subsequent rows (or columns) will be moved to allow the insertion (or removal) with all formulas referencing thise cells adjusted accordingly. Note that this is a fairly intensive process, particularly with large worksheets, and especially if you are inserting/removing rows/columns from near beginning of the worksheet. If you need to insert/remove several consecutive rows/columns, always use the second argument rather than making multiple calls to insert/remove a single row/column if possible. ## Add a drawing to a worksheet A drawing is always represented as a separate object, which can be added to a worksheet. Therefore, you must first instantiate a new `\PhpOffice\PhpSpreadsheet\Worksheet\Drawing`, and assign its properties a meaningful value: ```php $drawing = new \PhpOffice\PhpSpreadsheet\Worksheet\Drawing(); $drawing->setName('Logo'); $drawing->setDescription('Logo'); $drawing->setPath('./images/officelogo.jpg'); $drawing->setHeight(36); ``` To add the above drawing to the worksheet, use the following snippet of code. PhpSpreadsheet creates the link between the drawing and the worksheet: ```php $drawing->setWorksheet($spreadsheet->getActiveSheet()); ``` You can set numerous properties on a drawing, here are some examples: ```php $drawing->setName('Paid'); $drawing->setDescription('Paid'); $drawing->setPath('./images/paid.png'); $drawing->setCoordinates('B15'); $drawing->setOffsetX(110); $drawing->setRotation(25); $drawing->getShadow()->setVisible(true); $drawing->getShadow()->setDirection(45); ``` You can also add images created using GD functions without needing to save them to disk first as In-Memory drawings. ```php // Use GD to create an in-memory image $gdImage = @imagecreatetruecolor(120, 20) or die('Cannot Initialize new GD image stream'); $textColor = imagecolorallocate($gdImage, 255, 255, 255); imagestring($gdImage, 1, 5, 5, 'Created with PhpSpreadsheet', $textColor); // Add the In-Memory image to a worksheet $drawing = new \PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing(); $drawing->setName('In-Memory image 1'); $drawing->setDescription('In-Memory image 1'); $drawing->setCoordinates('A1'); $drawing->setImageResource($gdImage); $drawing->setRenderingFunction( \PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing::RENDERING_JPEG ); $drawing->setMimeType(\PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing::MIMETYPE_DEFAULT); $drawing->setHeight(36); $drawing->setWorksheet($spreadsheet->getActiveSheet()); ``` Note that GD images are memory-intensive. ### Creating a Drawing from string or stream data If you want to create a drawing from a string containing the binary image data, or from an external datasource such as an S3 bucket, then you can create a new MemoryDrawing from these sources using the `fromString()` or `fromStream()` static methods. ```php $drawing = MemoryDrawing::fromString($imageString); ``` ```php $drawing = MemoryDrawing::fromStream($imageStreamFromS3Bucket); ``` Note that this is a memory-intensive process, like all gd images; and also creates a temporary file. ## Reading Images from a worksheet A commonly asked question is how to retrieve the images from a workbook that has been loaded, and save them as individual image files to disk. The following code extracts images from the current active worksheet, and writes each as a separate file. ```php use PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing; $i = 0; foreach ($spreadsheet->getActiveSheet()->getDrawingCollection() as $drawing) { if ($drawing instanceof MemoryDrawing) { ob_start(); call_user_func( $drawing->getRenderingFunction(), $drawing->getImageResource() ); $imageContents = ob_get_contents(); ob_end_clean(); switch ($drawing->getMimeType()) { case MemoryDrawing::MIMETYPE_PNG : $extension = 'png'; break; case MemoryDrawing::MIMETYPE_GIF: $extension = 'gif'; break; case MemoryDrawing::MIMETYPE_JPEG : $extension = 'jpg'; break; } } else { if ($drawing->getPath()) { // Check if the source is a URL or a file path if ($drawing->getIsURL()) { $imageContents = file_get_contents($drawing->getPath()); $filePath = tempnam(sys_get_temp_dir(), 'Drawing'); file_put_contents($filePath , $imageContents); $mimeType = mime_content_type($filePath); // You could use the below to find the extension from mime type. // https://gist.github.com/alexcorvi/df8faecb59e86bee93411f6a7967df2c#gistcomment-2722664 $extension = File::mime2ext($mimeType); unlink($filePath); } else { $zipReader = fopen($drawing->getPath(),'r'); $imageContents = ''; while (!feof($zipReader)) { $imageContents .= fread($zipReader,1024); } fclose($zipReader); $extension = $drawing->getExtension(); } } } $myFileName = '00_Image_'.++$i.'.'.$extension; file_put_contents($myFileName,$imageContents); } ``` ## Add rich text to a cell Adding rich text to a cell can be done using `\PhpOffice\PhpSpreadsheet\RichText\RichText` instances. Here''s an example, which creates the following rich text string: > This invoice is ***payable within thirty days after the end of the > month*** unless specified otherwise on the invoice. ```php $richText = new \PhpOffice\PhpSpreadsheet\RichText\RichText(); $richText->createText('This invoice is '); $payable = $richText->createTextRun('payable within thirty days after the end of the month'); $payable->getFont()->setBold(true); $payable->getFont()->setItalic(true); $payable->getFont()->setColor( new \PhpOffice\PhpSpreadsheet\Style\Color( \PhpOffice\PhpSpreadsheet\Style\Color::COLOR_DARKGREEN ) ); $richText->createText(', unless specified otherwise on the invoice.'); $spreadsheet->getActiveSheet()->getCell('A18')->setValue($richText); ``` ## Define a named range PhpSpreadsheet supports the definition of named ranges. These can be defined using the following code: ```php // Add some data $spreadsheet->setActiveSheetIndex(0); $spreadsheet->getActiveSheet()->setCellValue('A1', 'Firstname:'); $spreadsheet->getActiveSheet()->setCellValue('A2', 'Lastname:'); $spreadsheet->getActiveSheet()->setCellValue('B1', 'Maarten'); $spreadsheet->getActiveSheet()->setCellValue('B2', 'Balliauw'); // Define named ranges $spreadsheet->addNamedRange( new \PhpOffice\PhpSpreadsheet\NamedRange('PersonFN', $spreadsheet->getActiveSheet(), '$B$1')); $spreadsheet->addNamedRange( new \PhpOffice\PhpSpreadsheet\NamedRange('PersonLN', $spreadsheet->getActiveSheet(), '$B$2')); ``` Optionally, a fourth parameter can be passed defining the named range local (i.e. only usable on the current worksheet). Named ranges are global by default. ## Define a named formula In addition to named ranges, PhpSpreadsheet also supports the definition of named formulas. These can be defined using the following code: ```php // Add some data $spreadsheet->setActiveSheetIndex(0); $worksheet = $spreadsheet->getActiveSheet(); $worksheet ->setCellValue('A1', 'Product') ->setCellValue('B1', 'Quantity') ->setCellValue('C1', 'Unit Price') ->setCellValue('D1', 'Price') ->setCellValue('E1', 'VAT') ->setCellValue('F1', 'Total'); // Define named formula $spreadsheet->addNamedFormula( new \PhpOffice\PhpSpreadsheet\NamedFormula('GERMAN_VAT_RATE', $worksheet, '=16.0%')); $spreadsheet->addNamedFormula( new \PhpOffice\PhpSpreadsheet\NamedFormula('CALCULATED_PRICE', $worksheet, '=$B1*$C1')); $spreadsheet->addNamedFormula( new \PhpOffice\PhpSpreadsheet\NamedFormula('GERMAN_VAT', $worksheet, '=$D1*GERMAN_VAT_RATE')); $spreadsheet->addNamedFormula( new \PhpOffice\PhpSpreadsheet\NamedFormula('TOTAL_INCLUDING_VAT', $worksheet, '=$D1+$E1')); $worksheet ->setCellValue('A2', 'Advanced Web Application Architecture') ->setCellValue('B2', 2) ->setCellValue('C2', 23.0) ->setCellValue('D2', '=CALCULATED_PRICE') ->setCellValue('E2', '=GERMAN_VAT') ->setCellValue('F2', '=TOTAL_INCLUDING_VAT'); $spreadsheet->getActiveSheet() ->setCellValue('A3', 'Object Design Style Guide') ->setCellValue('B3', 5) ->setCellValue('C3', 12.0) ->setCellValue('D3', '=CALCULATED_PRICE') ->setCellValue('E3', '=GERMAN_VAT') ->setCellValue('F3', '=TOTAL_INCLUDING_VAT'); $spreadsheet->getActiveSheet() ->setCellValue('A4', 'PHP For the Web') ->setCellValue('B4', 3) ->setCellValue('C4', 10.0) ->setCellValue('D4', '=CALCULATED_PRICE') ->setCellValue('E4', '=GERMAN_VAT') ->setCellValue('F4', '=TOTAL_INCLUDING_VAT'); // Use a relative named range to provide the totals for rows 2-4 $spreadsheet->addNamedRange( new \PhpOffice\PhpSpreadsheet\NamedRange('COLUMN_TOTAL', $worksheet, '=A$2:A$4') ); $spreadsheet->getActiveSheet() ->setCellValue('B6', '=SUBTOTAL(109,COLUMN_TOTAL)') ->setCellValue('D6', '=SUBTOTAL(109,COLUMN_TOTAL)') ->setCellValue('E6', '=SUBTOTAL(109,COLUMN_TOTAL)') ->setCellValue('F6', '=SUBTOTAL(109,COLUMN_TOTAL)'); ``` As with named ranges, an optional fourth parameter can be passed defining the named formula scope as local (i.e. only usable on the specified worksheet). Otherwise, named formulas are global by default. ## Redirect output to a client's web browser Sometimes, one really wants to output a file to a client''s browser, especially when creating spreadsheets on-the-fly. There are some easy steps that can be followed to do this: 1. Create your PhpSpreadsheet spreadsheet 2. Output HTTP headers for the type of document you wish to output 3. Use the `\PhpOffice\PhpSpreadsheet\Writer\*` of your choice, and save to `'php://output'` `\PhpOffice\PhpSpreadsheet\Writer\Xlsx` uses temporary storage when writing to `php://output`. By default, temporary files are stored in the script's working directory. When there is no access, it falls back to the operating system's temporary files location. **This may not be safe for unauthorized viewing!** Depending on the configuration of your operating system, temporary storage can be read by anyone using the same temporary storage folder. When confidentiality of your document is needed, it is recommended not to use `php://output`. ### HTTP headers Example of a script redirecting an Excel 2007 file to the client's browser: ```php /* Here there will be some code where you create $spreadsheet */ // redirect output to client browser header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'); header('Content-Disposition: attachment;filename="myfile.xlsx"'); header('Cache-Control: max-age=0'); $writer = \PhpOffice\PhpSpreadsheet\IOFactory::createWriter($spreadsheet, 'Xlsx'); $writer->save('php://output'); ``` Example of a script redirecting an Xls file to the client's browser: ```php /* Here there will be some code where you create $spreadsheet */ // redirect output to client browser header('Content-Type: application/vnd.ms-excel'); header('Content-Disposition: attachment;filename="myfile.xls"'); header('Cache-Control: max-age=0'); $writer = \PhpOffice\PhpSpreadsheet\IOFactory::createWriter($spreadsheet, 'Xls'); $writer->save('php://output'); ``` **Caution:** Make sure not to include any echo statements or output any other contents than the Excel file. There should be no whitespace before the opening `` tag (which can also be omitted to avoid problems). Make sure that your script is saved without a BOM (Byte-order mark) because this counts as echoing output. The same things apply to all included files. Failing to follow the above guidelines may result in corrupt Excel files arriving at the client browser, and/or that headers cannot be set by PHP (resulting in warning messages). ## Setting the default column width Default column width can be set using the following code: ```php $spreadsheet->getActiveSheet()->getDefaultColumnDimension()->setWidth(12); ``` Excel measures column width in its own proprietary units, based on the number of characters that will be displayed in the default font. If you want to set the default column width using a different UoM (Unit of Measure), then you can do so by telling PhpSpreadsheet what UoM the width value that you are setting is measured in. Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches), `cm` (centimeters) and `mm` (millimeters). ```php $spreadsheet->getActiveSheet()->getDefaultColumnDimension()->setWidth(400, 'pt'); ``` and PhpSpreadsheet will handle the internal conversion. ## Setting the default row height Default row height can be set using the following code: ```php $spreadsheet->getActiveSheet()->getDefaultRowDimension()->setRowHeight(15); ``` Excel measures row height in points, where 1 pt is 1/72 of an inch (or about 0.35mm). The default value is 12.75 pts; and the permitted range of values is between 0 and 409 pts, where 0 pts is a hidden row. If you want to set a row height using a different UoM (Unit of Measure), then you can do so by telling PhpSpreadsheet what UoM the height value that you are setting is measured in. Valid units are `pt` (points), `px` (pixels), `pc` (pica), `in` (inches), `cm` (centimeters) and `mm` (millimeters). ```php $spreadsheet->getActiveSheet()->getDefaultRowDimension()->setRowHeight(100, 'pt'); ``` ## Add a GD drawing to a worksheet There might be a situation where you want to generate an in-memory image using GD and add it to a `Spreadsheet` without first having to save this file to a temporary location. Here''s an example which generates an image in memory and adds it to the active worksheet: ```php // Generate an image $gdImage = @imagecreatetruecolor(120, 20) or die('Cannot Initialize new GD image stream'); $textColor = imagecolorallocate($gdImage, 255, 255, 255); imagestring($gdImage, 1, 5, 5, 'Created with PhpSpreadsheet', $textColor); // Add a drawing to the worksheet $drawing = new \PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing(); $drawing->setName('Sample image'); $drawing->setDescription('Sample image'); $drawing->setImageResource($gdImage); $drawing->setRenderingFunction(\PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing::RENDERING_JPEG); $drawing->setMimeType(\PhpOffice\PhpSpreadsheet\Worksheet\MemoryDrawing::MIMETYPE_DEFAULT); $drawing->setHeight(36); $drawing->setWorksheet($spreadsheet->getActiveSheet()); ``` ## Setting worksheet zoom level To set a worksheet's zoom level, the following code can be used: ```php $spreadsheet->getActiveSheet()->getSheetView()->setZoomScale(75); ``` Note that zoom level should be in range 10 - 400. ## Sheet tab color Sometimes you want to set a color for sheet tab. For example you can have a red sheet tab: ```php $worksheet->getTabColor()->setRGB('FF0000'); ``` ## Creating worksheets in a workbook If you need to create more worksheets in the workbook, here is how: ```php $worksheet1 = $spreadsheet->createSheet(); $worksheet1->setTitle('Another sheet'); ``` Think of `createSheet()` as the "Insert sheet" button in Excel. When you hit that button a new sheet is appended to the existing collection of worksheets in the workbook. ## Hidden worksheets (Sheet states) Set a worksheet to be **hidden** using this code: ```php $spreadsheet->getActiveSheet() ->setSheetState(\PhpOffice\PhpSpreadsheet\Worksheet\Worksheet::SHEETSTATE_HIDDEN); ``` Sometimes you may even want the worksheet to be **"very hidden"**. The available sheet states are : - `\PhpOffice\PhpSpreadsheet\Worksheet\Worksheet::SHEETSTATE_VISIBLE` - `\PhpOffice\PhpSpreadsheet\Worksheet\Worksheet::SHEETSTATE_HIDDEN` - `\PhpOffice\PhpSpreadsheet\Worksheet\Worksheet::SHEETSTATE_VERYHIDDEN` In Excel the sheet state "very hidden" can only be set programmatically, e.g. with Visual Basic Macro. It is not possible to make such a sheet visible via the user interface. ## Right-to-left worksheet Worksheets can be set individually whether column `A` should start at left or right side. Default is left. Here is how to set columns from right-to-left. ```php // right-to-left worksheet $spreadsheet->getActiveSheet()->setRightToLeft(true); ``` ================================================ FILE: docs/topics/settings.md ================================================ # Configuration Settings Once you have included the PhpSpreadsheet files in your script, but before instantiating a `Spreadsheet` object or loading a workbook file, there are a number of configuration options that can be set which will affect the subsequent behaviour of the script. ## Cell collection caching By default, PhpSpreadsheet holds all cell objects in memory, but you can specify alternatives to reduce memory consumption at the cost of speed. Read more about [memory saving](./memory_saving.md). To enable cell caching, you must provide your own implementation of cache like so: ```php $cache = new MyCustomPsr16Implementation(); \PhpOffice\PhpSpreadsheet\Settings::setCache($cache); ``` ## Language/Locale Some localisation elements have been included in PhpSpreadsheet. You can set a locale by changing the settings. To set the locale to Brazilian Portuguese you would use: ```php $locale = 'pt_br'; $validLocale = \PhpOffice\PhpSpreadsheet\Settings::setLocale($locale); if (!$validLocale) { echo 'Unable to set locale to ' . $locale . " - reverting to en_us" . PHP_EOL; } ``` - If Brazilian Portuguese language files aren't available, then Portuguese will be enabled instead - If Portuguese language files also aren't available, then the `setLocale` method will return `false`, and American English (en\_us) settings will be used throughout. More details of the features available once a locale has been set, including a list of the languages and locales currently supported, can be found in [Locale Settings for Formulas](./recipes.md#locale-settings-for-formulas). Additional localization elements (currency code, thousands separator, and decimal separator) are available in `PhpOffice\PhpSpreadsheet\Shared\StringHelper`: ```php StringHelper::setCurrencyCode('€'); StringHelper::setThousandsSeparator('.'); StringHelper::setDecimalSeparator(','); ``` You can use the Php function `setLocale` to try to set these values without knowing beforehand what symbols are needed. ```php StringHelper::setCurrencyCode(null); StringHelper::setThousandsSeparator(null); StringHelper::setDecimalSeparator(null); $result = setLocale(LC_ALL, 'pt_br.UTF-8'); ``` However, this function maintains its information at the process level, not the thread level, and its use is therefore discouraged. A less-troublesome replacement is available starting with PhpSpreadsheet 5.4. ```php $result = StringHelper::setLocale('pt_br'); // will restore defaults if argument is null ``` This will set the locale and the 3 StringHelper values all at once. It requires the `Intl` extension, which is not a requirement for PhpSpreadsheet as a whole. For that reason, it returns a boolean result, which will be `false` if `Intl` is not available, or if it does not consider the supplied locale to be valid. ================================================ FILE: docs/topics/tables.md ================================================ # Tables ## Introduction To make managing and analyzing a group of related data easier, you can turn a range of cells into an Excel table (previously known as an Excel list). ## Support Currently tables are supported in Xlsx reader and Html Writer To enable table formatting for Html writer, use: ```php $writer = new HtmlWriter($spreadsheet); $writer->setConditionalFormatting(true); ``` ================================================ FILE: docs/topics/worksheets.md ================================================ # Worksheets A worksheet is a collection of cells, formulae, images, graphs, etc. It holds all data necessary to represent a spreadsheet worksheet. When you load a workbook from a spreadsheet file, it will be loaded with all its existing worksheets (unless you specified that only certain sheets should be loaded). When you load from non-spreadsheet files (such as a CSV or HTML file) or from spreadsheet formats that don't identify worksheets by name (such as SYLK), then a single worksheet called "WorkSheet1" will be created containing the data from that file. When you instantiate a new workbook, PhpSpreadsheet will create it with a single worksheet called "WorkSheet1". The `getSheetCount()` method will tell you the number of worksheets in the workbook; while the `getSheetNames()` method will return a list of all worksheets in the workbook, indexed by the order in which their "tabs" would appear when opened in MS Excel (or other appropriate Spreadsheet program). Individual worksheets can be accessed by name, or by their index position in the workbook. The index position represents the order that each worksheet "tab" is shown when the workbook is opened in MS Excel (or other appropriate Spreadsheet program). To access a sheet by its index, use the `getSheet()` method. ```php // Get the second sheet in the workbook // Note that sheets are indexed from 0 $spreadsheet->getSheet(1); ``` Methods also exist allowing you to reorder the worksheets in the workbook. To access a sheet by name, use the `getSheetByName()` method, specifying the name of the worksheet that you want to access. ```php // Retrieve the worksheet called 'Worksheet 1' $spreadsheet->getSheetByName('Worksheet 1'); ``` Alternatively, one worksheet is always the currently active worksheet, and you can access that directly. The currently active worksheet is the one that will be active when the workbook is opened in MS Excel (or other appropriate Spreadsheet program). ```php // Retrieve the current active worksheet $spreadsheet->getActiveSheet(); ``` You can change the currently active sheet by index or by name using the `setActiveSheetIndex()` and `setActiveSheetIndexByName()` methods. ## Adding a new Worksheet You can add a new worksheet to the workbook using the `createSheet()` method of the `Spreadsheet` object. By default, this will be created as a new "last" sheet; but you can also specify an index position as an argument, and the worksheet will be inserted at that position, shuffling all subsequent worksheets in the collection down a place. ```php $spreadsheet->createSheet(); ``` A new worksheet created using this method will be called `Worksheet
My very first example of rich text
generated from html markup
This block contains an italicized word; while this block uses an underline.
I want to eat healthy food pizza.
';
$html2 = '
100°C is a hot temperature
10°F is cold
Roots:
'); $discriminantFormula = '=POWER(' . $postB . ',2) - (4 * ' . $postA . ' * ' . $postC . ')'; $discriminant = Calculation::getInstance()->calculateFormula($discriminantFormula); $discriminant = StringHelper::convertToString($discriminant); $r1Formula = '=IMDIV(IMSUM(-' . $postB . ',IMSQRT(' . $discriminant . ')),2 * ' . $postA . ')'; $r2Formula = '=IF(' . $discriminant . '=0,"Only one root",IMDIV(IMSUB(-' . $postB . ',IMSQRT(' . $discriminant . ')),2 * ' . $postA . '))'; /** @var string */ $output = Calculation::getInstance()->calculateFormula($r1Formula); $helper->log("$output"); /** @var string */ $output = Calculation::getInstance()->calculateFormula($r2Formula); $helper->log("$output"); $callEndTime = microtime(true); $helper->logEndingNotes(); } } ================================================ FILE: samples/Basic4/46_ReadHtml.php ================================================ load($html); $helper->logRead('Html', $html, $callStartTime); // Save $helper->write($objPHPExcel, __FILE__); ================================================ FILE: samples/Basic4/47_xlsfill.php ================================================ log('Read spreadsheet'); $reader = new Xls(); $spreadsheet = $reader->load(__DIR__ . '/../templates/47_xlsfill.xls'); // Save $helper->write($spreadsheet, __FILE__, ['Xls']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic4/47_xlsxfill.php ================================================ log('Read spreadsheet'); $reader = new Xlsx(); $spreadsheet = $reader->load(__DIR__ . '/../templates/47_xlsxfill.xlsx'); // Save $helper->write($spreadsheet, __FILE__, ['Xlsx']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic4/48_Image_move_size_with_cells.php ================================================ log('Create new Spreadsheet object'); $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); $sheet->getCell('A1')->setValue('twocell'); $sheet->getCell('A2')->setValue('twocell'); $sheet->getCell('A3')->setValue('onecell'); $sheet->getCell('A6')->setValue('absolute'); // Add a drawing to the worksheet $helper->log('Add a drawing to the worksheet two-cell anchor not resized'); $drawing = new Drawing(); $drawing->setName('PhpSpreadsheet'); $drawing->setDescription('PhpSpreadsheet'); $drawing->setPath(__DIR__ . '/../images/PhpSpreadsheet_logo.png'); // anchor type will be two-cell because Coordinates2 is set //$drawing->setAnchorType(Drawing::ANCHORTYPE_TWOCELL); $drawing->setCoordinates('B1'); $drawing->setCoordinates2('B1'); $drawing->setOffsetX2($drawing->getImageWidth()); $drawing->setOffsetY2($drawing->getImageHeight()); $drawing->setWorksheet($spreadsheet->getActiveSheet()); // Add a drawing to the worksheet $helper->log('Add a drawing to the worksheet two-cell anchor resized'); $drawing2 = new Drawing(); $drawing2->setName('PhpSpreadsheet'); $drawing2->setDescription('PhpSpreadsheet'); $drawing2->setPath(__DIR__ . '/../images/PhpSpreadsheet_logo.png'); // anchor type will be two-cell because Coordinates2 is set //$drawing->setAnchorType(Drawing::ANCHORTYPE_TWOCELL); $drawing2->setCoordinates('C2'); $drawing2->setCoordinates2('C2'); $drawing2->setOffsetX2($drawing->getImageWidth()); $drawing2->setOffsetY2($drawing->getImageHeight()); $drawing2->setWorksheet($spreadsheet->getActiveSheet()); $spreadsheet->getActiveSheet()->getColumnDimension('C')->setWidth($drawing->getImageWidth(), Dimension::UOM_PIXELS); $spreadsheet->getActiveSheet()->getRowDimension(2)->setRowHeight($drawing->getImageHeight(), Dimension::UOM_PIXELS); // Add a drawing to the worksheet one cell anchor $helper->log('Add a drawing to the worksheet one-cell anchor'); $drawing3 = new Drawing(); $drawing3->setName('PhpSpreadsheet'); $drawing3->setDescription('PhpSpreadsheet'); $drawing3->setPath(__DIR__ . '/../images/PhpSpreadsheet_logo.png'); // anchor type will be one-cell because Coordinates2 is not set //$drawing->setAnchorType(Drawing::ANCHORTYPE_ONECELL); $drawing3->setCoordinates('D3'); $drawing3->setWorksheet($spreadsheet->getActiveSheet()); // Add a drawing to the worksheet $helper->log('Add a drawing to the worksheet two-cell anchor resized absolute'); $drawing4 = new Drawing(); $drawing4->setName('PhpSpreadsheet'); $drawing4->setDescription('PhpSpreadsheet'); $drawing4->setPath(__DIR__ . '/../images/PhpSpreadsheet_logo.png'); // anchor type will be two-cell because Coordinates2 is set //$drawing->setAnchorType(Drawing::ANCHORTYPE_TWOCELL); $drawing4->setCoordinates('C6'); $drawing4->setCoordinates2('C6'); $drawing4->setOffsetX2($drawing->getImageWidth()); $drawing4->setOffsetY2($drawing->getImageHeight()); $drawing4->setWorksheet($spreadsheet->getActiveSheet()); $drawing4->setEditAs(Drawing::EDIT_AS_ABSOLUTE); //$spreadsheet->getActiveSheet()->getColumnDimension('C')->setWidth($drawing->getImageWidth(), Dimension::UOM_PIXELS); $spreadsheet->getActiveSheet()->getRowDimension(6)->setRowHeight($drawing->getImageHeight(), Dimension::UOM_PIXELS); $helper->write($spreadsheet, __FILE__, ['Xlsx']); ================================================ FILE: samples/Basic4/49_alignment.php ================================================ log('Create new Spreadsheet object'); $spreadsheet = new Spreadsheet(); $spreadsheet->getProperties()->setTitle('Alignment'); $sheet = $spreadsheet->getActiveSheet(); $hi = 'Hi There'; $ju = 'This is a longer than normal sentence'; $sheet->fromArray([ ['', 'default', 'bottom', 'top', 'center', 'justify', 'distributed'], ['default', $hi, $hi, $hi, $hi, $hi, $hi], ['left', $hi, $hi, $hi, $hi, $hi, $hi], ['right', $hi, $hi, $hi, $hi, $hi, $hi], ['center', $hi, $hi, $hi, $hi, $hi, $hi], ['justify', $ju, $ju, $ju, $ju, $ju, $ju], ['distributed', $ju, $ju, $ju, $ju, $ju, $ju], ]); $sheet->getColumnDimension('B')->setWidth(20); $sheet->getColumnDimension('C')->setWidth(20); $sheet->getColumnDimension('D')->setWidth(20); $sheet->getColumnDimension('E')->setWidth(20); $sheet->getColumnDimension('F')->setWidth(20); $sheet->getColumnDimension('G')->setWidth(20); $sheet->getRowDimension(2)->setRowHeight(30); $sheet->getRowDimension(3)->setRowHeight(30); $sheet->getRowDimension(4)->setRowHeight(30); $sheet->getRowDimension(5)->setRowHeight(30); $sheet->getRowDimension(6)->setRowHeight(40); $sheet->getRowDimension(7)->setRowHeight(40); $minRow = 2; $maxRow = 7; $minCol = 'B'; $maxCol = 'g'; $sheet->getStyle("C$minRow:C$maxRow") ->getAlignment() ->setVertical(Alignment::VERTICAL_BOTTOM); $sheet->getStyle("D$minRow:D$maxRow") ->getAlignment() ->setVertical(Alignment::VERTICAL_TOP); $sheet->getStyle("E$minRow:E$maxRow") ->getAlignment() ->setVertical(Alignment::VERTICAL_CENTER); $sheet->getStyle("F$minRow:F$maxRow") ->getAlignment() ->setVertical(Alignment::VERTICAL_JUSTIFY); $sheet->getStyle("G$minRow:G$maxRow") ->getAlignment() ->setVertical(Alignment::VERTICAL_DISTRIBUTED); $sheet->getStyle("{$minCol}3:{$maxCol}3") ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_LEFT); $sheet->getStyle("{$minCol}4:{$maxCol}4") ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_RIGHT); $sheet->getStyle("{$minCol}5:{$maxCol}5") ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_CENTER); $sheet->getStyle("{$minCol}6:{$maxCol}6") ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_JUSTIFY); $sheet->getStyle("{$minCol}7:{$maxCol}7") ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_DISTRIBUTED); $sheet->getCell('A9')->setValue('Center Continuous A9-C9'); $sheet->getStyle('A9:C9') ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_CENTER_CONTINUOUS); $sheet->getCell('A10')->setValue('Fill'); $sheet->getStyle('A10') ->getAlignment() ->setHorizontal(Alignment::HORIZONTAL_FILL); $sheet->setSelectedCells('A1'); $helper->write($spreadsheet, __FILE__, ['Xlsx', 'Html', 'Xls']); ================================================ FILE: samples/Basic5/50_xlsverticalbreak.php ================================================ log('Read spreadsheet'); $reader = new Xls(); $spreadsheet = $reader->load(__DIR__ . '/../templates/50_xlsverticalbreak.xls'); // Save $helper->write($spreadsheet, __FILE__, ['Xls']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic5/51_ProtectedSort.php ================================================ log('First sheet - protected, sorts not allowed'); $sheet = $spreadsheet->getActiveSheet(); $sheet->setTitle('sorttrue'); $sheet->getCell('A1')->setValue(10); $sheet->getCell('A2')->setValue(5); $sheet->getCell('B1')->setValue(15); $protection = $sheet->getProtection(); $protection->setPassword('testpassword'); $protection->setSheet(true); $protection->setInsertRows(true); $protection->setFormatCells(true); $protection->setObjects(true); $protection->setAutoFilter(false); $protection->setSort(true); $comment = $sheet->getComment('A1'); $text = new RichText(); $text->addText(new TextElement('Sort options should be grayed out. Sheet password to remove protections is testpassword for all sheets.')); $comment->setText($text)->setHeight('120pt')->setWidth('120pt'); $helper->log('Second sheet - protected, sorts allowed, but no permitted range defined'); $sheet = $spreadsheet->createSheet(); $sheet->setTitle('sortfalse'); $sheet->getCell('A1')->setValue(10); $sheet->getCell('A2')->setValue(5); $sheet->getCell('B1')->setValue(15); $protection = $sheet->getProtection(); $protection->setPassword('testpassword'); $protection->setSheet(true); $protection->setInsertRows(true); $protection->setFormatCells(true); $protection->setObjects(true); $protection->setAutoFilter(false); $protection->setSort(false); $comment = $sheet->getComment('A1'); $text = new RichText(); $text->addText(new TextElement('Sort options not grayed out, but no permissible sort range.')); $comment->setText($text)->setHeight('120pt')->setWidth('120pt'); $helper->log('Third sheet - protected, sorts allowed, but only on permitted range A:A, no range password needed'); $sheet = $spreadsheet->createSheet(); $sheet->setTitle('sortfalsenocolpw'); $sheet->getCell('A1')->setValue(10); $sheet->getCell('A2')->setValue(5); $sheet->getCell('C1')->setValue(15); $protection = $sheet->getProtection(); $protection->setPassword('testpassword'); $protection->setSheet(true); $protection->setInsertRows(true); $protection->setFormatCells(true); $protection->setObjects(true); $protection->setAutoFilter(false); $protection->setSort(false); $sheet->protectCells('A:A'); $comment = $sheet->getComment('A1'); $text = new RichText(); $text->addText(new TextElement('Column A may be sorted without a password. No sort for any other column.')); $comment->setText($text)->setHeight('120pt')->setWidth('120pt'); $helper->log('Fourth sheet - protected, sorts allowed, but only on permitted range A:A, and range password needed'); $sheet = $spreadsheet->createSheet(); $sheet->setTitle('sortfalsecolpw'); $sheet->getCell('A1')->setValue(10); $sheet->getCell('A2')->setValue(5); $sheet->getCell('C1')->setValue(15); $protection = $sheet->getProtection(); $protection->setPassword('testpassword'); $protection->setSheet(true); $protection->setInsertRows(true); $protection->setFormatCells(true); $protection->setObjects(true); $protection->setAutoFilter(false); $protection->setSort(false); $sheet->protectCells('A:A', 'sortpw', false, 'sortrange'); $comment = $sheet->getComment('A1'); $text = new RichText(); $text->addText(new TextElement('Column A may be sorted with password sortpw. No sort for any other column.')); $comment->setText($text)->setHeight('120pt')->setWidth('120pt'); // Save $helper->write($spreadsheet, __FILE__, ['Xls', 'Xlsx']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic5/52_Currency.php ================================================ log('First sheet - Accounting Wizard'); $sheet = $spreadsheet->getActiveSheet(); $sheet->setTitle('Accounting'); $sheet->getCell('A1')->setValue('Currency'); $sheet->getCell('B1')->setValue('Decimals'); $sheet->getCell('C1')->setValue('ThouSep'); $sheet->getCell('D1')->setValue('Lead'); $sheet->getCell('E1')->setValue('Spacing'); $sheet->getCell('F1')->setValue('Neg'); $sheet->getCell('G1')->setValue('Pos'); $sheet->getCell('H1')->setValue('Zero'); $sheet->getCell('I1')->setValue('Neg'); $sheet->getCell('J1')->setValue('Text'); $sheet->getCell('L1')->setValue('ActWiz$'); $sheet->getCell('M1')->setValue('ActWiz€Trl'); $sheet->freezePane('A2'); $sheet->getComment('E1')->getText()->createText('ignored, always true for Accounting'); $sheet->getComment('F1')->getText()->createText('ignored, always () for Accounting'); $sheet->getCell('A2')->setValue('AcctUSD'); $sheet->getCell('G2')->setValue(1234.56); $sheet->getCell('H2')->setValue(0); $sheet->getCell('I2')->setValue(-1234.56); $sheet->getCell('J2')->setValue('text'); $sheet->getStyle('G2:J2')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_ACCOUNTING_USD); $sheet->getCell('A3')->setValue('AcctEur'); $sheet->getCell('G3')->setValue(1234.56); $sheet->getCell('H3')->setValue(0); $sheet->getCell('I3')->setValue(-1234.56); $sheet->getCell('J3')->setValue('Text'); $sheet->getStyle('G3:J3')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_ACCOUNTING_EUR); $sheet->getCell('A4')->setValue('AcctWiz￥'); $sheet->getCell('E4')->setValue(true); $sheet->getCell('G4')->setValue(1234.56); $sheet->getCell('H4')->setValue(0); $sheet->getCell('I4')->setValue(-1234.56); $sheet->getCell('J4')->setValue('Text'); $sheet->getStyle('G4:J4')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('￥', currencySymbolSpacing: true))->format(), ], ] ); $sheet->getCell('A5')->setValue('StalePR￥'); $sheet->getCell('G5')->setValue(1234.56); $sheet->getCell('H5')->setValue(0); $sheet->getCell('I5')->setValue(-1234.56); $sheet->getCell('J5')->setValue('Text'); $sheet->getStyle('G5:J5')->getNumberFormat()->setFormatCode('_("￥"* #,##0.00_);_("￥"* -#,##0.00_);_("￥"* "-"??_);_(@_)'); $sheet->getCell('A6')->setValue('AcctWiz￥'); $sheet->getCell('E6')->setValue(true); $sheet->getCell('F6')->setValue(CurrencyNegative::minus->name); $sheet->getCell('G6')->setValue(1234.56); $sheet->getCell('H6')->setValue(0); $sheet->getCell('I6')->setValue(-1234.56); $sheet->getCell('J6')->setValue('Text'); $sheet->getStyle('G6:J6')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('￥', currencySymbolSpacing: true, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('A7')->setValue('AcctWiz￥'); $sheet->getCell('E7')->setValue(false); $sheet->getCell('F7')->setValue(CurrencyNegative::minus->name); $sheet->getCell('G7')->setValue(1234.56); $sheet->getCell('H7')->setValue(0); $sheet->getCell('I7')->setValue(-1234.56); $sheet->getCell('J7')->setValue('Text'); $sheet->getStyle('G7:J7')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('￥', currencySymbolSpacing: false, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('A8')->setValue('AcctWiz￥'); $sheet->getCell('E8')->setValue(false); $sheet->getCell('F8')->setValue(CurrencyNegative::parentheses->name); $sheet->getCell('G8')->setValue(1234.56); $sheet->getCell('H8')->setValue(0); $sheet->getCell('I8')->setValue(-1234.56); $sheet->getCell('J8')->setValue('Text'); $sheet->getStyle('G8:J8')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('￥', currencySymbolSpacing: false, negative: CurrencyNegative::parentheses))->format(), ], ] ); $sheet->getCell('A9')->setValue('AcctW HUF'); $sheet->getCell('E9')->setValue(true); $sheet->getCell('G9')->setValue(1234.56); $sheet->getCell('H9')->setValue(0); $sheet->getCell('I9')->setValue(-1234.56); $sheet->getCell('J9')->setValue('Text'); $sheet->getStyle('G9:J9')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('HUF', currencySymbolSpacing: true))->format(), ], ] ); $sheet->getCell('A10')->setValue('AcctW HUF'); $sheet->getCell('E10')->setValue(true); $sheet->getCell('F10')->setValue(CurrencyNegative::redParentheses->name); $sheet->getStyle('F10')->getFont()->getColor()->setRgb('FF0000'); $sheet->getCell('G10')->setValue(1234.56); $sheet->getCell('H10')->setValue(0); $sheet->getCell('I10')->setValue(-1234.56); $sheet->getCell('J10')->setValue('Text'); $sheet->getStyle('G10:J10')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('HUF', currencySymbolSpacing: true, negative: CurrencyNegative::redParentheses))->format(), ], ] ); $sheet->getCell('A11')->setValue('AcctW Kazakh'); $sheet->getCell('D11')->setValue(false); $sheet->getCell('G11')->setValue(1234.56); $sheet->getCell('H11')->setValue(0); $sheet->getCell('I11')->setValue(-1234.56); $sheet->getCell('J11')->setValue('Text'); $sheet->getStyle('G11:J11')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Accounting('₸', currencySymbolPosition: Accounting::TRAILING_SYMBOL))->format(), ], ] ); $sheet->getCell('A12')->setValue('AcctW $'); $sheet->getCell('B12')->setValue(3); $sheet->getCell('C12')->setValue(false); $sheet->getCell('D12')->setValue(false); $sheet->getCell('F12')->setValue(CurrencyNegative::redMinus->name); $sheet->getStyle('F12')->getFont()->getColor()->setRgb('FF0000'); $sheet->getCell('G12')->setValue(1234.56); $sheet->getCell('H12')->setValue(0); $sheet->getCell('I12')->setValue(-1234.56); $sheet->getCell('J12')->setValue('Text'); $format = new Accounting( '$', decimals: 3, thousandsSeparator: false, currencySymbolPosition: Accounting::TRAILING_SYMBOL, negative: CurrencyNegative::redMinus ); $sheet->getStyle('G12:J12')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => $format->format(), ], ] ); $sheet->getCell('L2')->setValue(1234.56); $sheet->getCell('L3')->setValue(0); $sheet->getCell('L4')->setValue(-1234.56); $format = new Accounting('$'); $sheet->getStyle('L2:L4')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => $format->format(), ], ] ); $sheet->getCell('M2')->setValue(1234.56); $sheet->getCell('M3')->setValue(0); $sheet->getCell('M4')->setValue(-1234.56); $format = new Accounting('€', currencySymbolPosition: Accounting::TRAILING_SYMBOL); $sheet->getStyle('M2:M4')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => $format->format(), ], ] ); $sheet->getColumnDimension('A')->setAutoSize(true); $sheet->getColumnDimension('F')->setAutoSize(true); $sheet->getColumnDimension('G')->setAutoSize(true); $sheet->getColumnDimension('I')->setAutoSize(true); $sheet->getColumnDimension('L')->setAutoSize(true); $sheet->getColumnDimension('M')->setAutoSize(true); $sheet->setSelectedCells('J1'); // second sheet $helper->log('Second sheet - Currency Wizard'); $sheet = $spreadsheet->createSheet(); $sheet->setTitle('Currency'); $sheet->getCell('A1')->setValue('Currency'); $sheet->getCell('B1')->setValue('Decimals'); $sheet->getCell('C1')->setValue('ThouSep'); $sheet->getCell('D1')->setValue('Lead'); $sheet->getCell('E1')->setValue('Spacing'); $sheet->getCell('F1')->setValue('Negative'); $sheet->getCell('G1')->setValue('Pos'); $sheet->getCell('H1')->setValue('Zero'); $sheet->getCell('I1')->setValue('Neg'); $sheet->getCell('J1')->setValue('Text'); $sheet->freezePane('A2'); $sheet->getComment('E1')->getText()->createText('ignored, always false for Currency'); $sheet->getCell('A2')->setValue('CurrUSD'); $sheet->getCell('G2')->setValue(1234.56); $sheet->getCell('H2')->setValue(0); $sheet->getCell('I2')->setValue(-1234.56); $sheet->getCell('J2')->setValue('text'); $sheet->getStyle('G2:J2')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_CURRENCY_USD); $sheet->getCell('A3')->setValue('CurrEur'); $sheet->getCell('G3')->setValue(1234.56); $sheet->getCell('H3')->setValue(0); $sheet->getCell('I3')->setValue(-1234.56); $sheet->getCell('J3')->setValue('Text'); $sheet->getStyle('G3:J3')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_CURRENCY_EUR); $sheet->getCell('A4')->setValue('CurrWiz￥'); $sheet->getCell('E4')->setValue(true); $sheet->getCell('G4')->setValue(1234.56); $sheet->getCell('H4')->setValue(0); $sheet->getCell('I4')->setValue(-1234.56); $sheet->getCell('J4')->setValue('Text'); $sheet->getStyle('G4:J4')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('￥', currencySymbolSpacing: true))->format(), ], ] ); $sheet->getCell('A5')->setValue('StalePR￥'); $sheet->getCell('G5')->setValue(1234.56); $sheet->getCell('H5')->setValue(0); $sheet->getCell('I5')->setValue(-1234.56); $sheet->getCell('J5')->setValue('Text'); $sheet->getStyle('G5:J5')->getNumberFormat()->setFormatCode('￥ #,##0'); $sheet->getCell('A6')->setValue('CurrWiz￥'); $sheet->getCell('E6')->setValue(true); $sheet->getCell('F6')->setValue(CurrencyNegative::minus->name); $sheet->getCell('G6')->setValue(1234.56); $sheet->getCell('H6')->setValue(0); $sheet->getCell('I6')->setValue(-1234.56); $sheet->getCell('J6')->setValue('Text'); $sheet->getStyle('G6:J6')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('￥', currencySymbolSpacing: true, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('A7')->setValue('CurrWiz￥'); $sheet->getCell('E7')->setValue(false); $sheet->getCell('F7')->setValue(CurrencyNegative::minus->name); $sheet->getCell('G7')->setValue(1234.56); $sheet->getCell('H7')->setValue(0); $sheet->getCell('I7')->setValue(-1234.56); $sheet->getCell('J7')->setValue('Text'); $sheet->getStyle('G7:J7')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('￥', currencySymbolSpacing: false, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('A8')->setValue('CurrWiz￥'); $sheet->getCell('E8')->setValue(false); $sheet->getCell('F8')->setValue(CurrencyNegative::parentheses->name); $sheet->getCell('G8')->setValue(1234.56); $sheet->getCell('H8')->setValue(0); $sheet->getCell('I8')->setValue(-1234.56); $sheet->getCell('J8')->setValue('Text'); $sheet->getStyle('G8:J8')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('￥', currencySymbolSpacing: false, negative: CurrencyNegative::parentheses))->format(), ], ] ); $sheet->getCell('A9')->setValue('CurrW HUF'); $sheet->getCell('E9')->setValue(true); $sheet->getCell('G9')->setValue(1234.56); $sheet->getCell('H9')->setValue(0); $sheet->getCell('I9')->setValue(-1234.56); $sheet->getCell('J9')->setValue('Text'); $sheet->getStyle('G9:J9')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('HUF', currencySymbolSpacing: true))->format(), ], ] ); $sheet->getCell('A10')->setValue('CurrW HUF'); $sheet->getCell('E10')->setValue(true); $sheet->getCell('F10')->setValue(CurrencyNegative::redParentheses->name); $sheet->getStyle('F10')->getFont()->getColor()->setRgb('FF0000'); $sheet->getCell('G10')->setValue(1234.56); $sheet->getCell('H10')->setValue(0); $sheet->getCell('I10')->setValue(-1234.56); $sheet->getCell('J10')->setValue('Text'); $sheet->getStyle('G10:J10')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('HUF', currencySymbolSpacing: true, negative: CurrencyNegative::redParentheses))->format(), ], ] ); $sheet->getCell('A11')->setValue('CurrW Kazakh'); $sheet->getCell('D11')->setValue(false); $sheet->getCell('G11')->setValue(1234.56); $sheet->getCell('H11')->setValue(0); $sheet->getCell('I11')->setValue(-1234.56); $sheet->getCell('J11')->setValue('Text'); $sheet->getStyle('G11:J11')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new Currency('₸', currencySymbolPosition: Accounting::TRAILING_SYMBOL))->format(), ], ] ); $sheet->getCell('A12')->setValue('CurrW $'); $sheet->getCell('B12')->setValue(3); $sheet->getCell('C12')->setValue(false); $sheet->getCell('D12')->setValue(false); $sheet->getCell('F12')->setValue(CurrencyNegative::redMinus->name); $sheet->getStyle('F12')->getFont()->getColor()->setRgb('FF0000'); $sheet->getCell('G12')->setValue(1234.56); $sheet->getCell('H12')->setValue(0); $sheet->getCell('I12')->setValue(-1234.56); $sheet->getCell('J12')->setValue('Text'); $format = new Currency( '$', decimals: 3, thousandsSeparator: false, currencySymbolPosition: Currency::TRAILING_SYMBOL, negative: CurrencyNegative::redMinus ); $sheet->getStyle('G12:J12')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => $format->format(), ], ] ); $sheet->getColumnDimension('A')->setAutoSize(true); $sheet->getColumnDimension('F')->setAutoSize(true); $sheet->getColumnDimension('G')->setAutoSize(true); $sheet->getColumnDimension('H')->setAutoSize(true); $sheet->getColumnDimension('I')->setAutoSize(true); $sheet->setSelectedCells('J1'); // third sheet $helper->log('Third sheet - CurrencyBase Wizard'); $sheet = $spreadsheet->createSheet(); $sheet->setTitle('CurrencyBase'); $sheet->getCell('A1')->setValue('Currency'); $sheet->getCell('B1')->setValue('Decimals'); $sheet->getCell('C1')->setValue('ThouSep'); $sheet->getCell('D1')->setValue('Lead'); $sheet->getCell('E1')->setValue('Spacing'); $sheet->getCell('F1')->setValue('Negative'); $sheet->getCell('G1')->setValue('Pos'); $sheet->getCell('H1')->setValue('Zero'); $sheet->getCell('I1')->setValue('Neg'); $sheet->getCell('J1')->setValue('Text'); $sheet->freezePane('A2'); $sheet->getCell('A2')->setValue('StaleAct￥'); $sheet->getCell('G2')->setValue(1234.56); $sheet->getCell('H2')->setValue(0); $sheet->getCell('I2')->setValue(-1234.56); $sheet->getCell('J2')->setValue('Text'); $sheet->getStyle('G2:J2')->getNumberFormat()->setFormatCode('_("￥"* #,##0.00_);_("￥"* -#,##0.00_);_("￥"* "-"??_);_(@_)'); $sheet->getCell('A3')->setValue('CurBase ￥'); $sheet->getCell('E3')->setValue(true); $sheet->getCell('F3')->setValue(CurrencyNegative::minus->name); $sheet->getCell('G3')->setValue(1234.56); $sheet->getCell('H3')->setValue(0); $sheet->getCell('I3')->setValue(-1234.56); $sheet->getCell('J3')->setValue('Text'); $sheet->getStyle('G3:J3')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new CurrencyBase('￥', currencySymbolSpacing: true, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('G4')->setValue(-1234.56); $sheet->getStyle('G4')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new CurrencyBase('￥', currencySymbolSpacing: true, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('G5')->setValue(0); $sheet->getStyle('G5')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new CurrencyBase('￥', currencySymbolSpacing: true, negative: CurrencyNegative::minus))->format(), ], ] ); $sheet->getCell('A6')->setValue('StaleCur￥'); $sheet->getCell('G6')->setValue(1234.56); $sheet->getCell('H6')->setValue(0); $sheet->getCell('I6')->setValue(-1234.56); $sheet->getCell('J6')->setValue('Text'); $sheet->getStyle('G6:J6')->getNumberFormat()->setFormatCode('￥ #,##0'); $sheet->getCell('A7')->setValue('CurBase ￥'); $sheet->getCell('B7')->setValue(0); $sheet->getCell('G7')->setValue(1234.56); $sheet->getCell('H7')->setValue(0); $sheet->getCell('I7')->setValue(-1234.56); $sheet->getCell('J7')->setValue('Text'); $sheet->getStyle('G7:J7')->applyFromArray( [ 'numberFormat' => [ 'formatCode' => (new CurrencyBase('￥', 0))->format(), ], ] ); $sheet->getColumnDimension('A')->setAutoSize(true); $sheet->getColumnDimension('F')->setAutoSize(true); $sheet->getColumnDimension('G')->setAutoSize(true); $sheet->getColumnDimension('H')->setAutoSize(true); $sheet->getColumnDimension('I')->setAutoSize(true); $sheet->setSelectedCells('J1'); $spreadsheet->setActiveSheetIndex(0); $helper->write($spreadsheet, __FILE__, ['Xls', 'Xlsx']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic5/53_ImageOpacity.php ================================================ getProperties()->setTitle('53_ImageOpacity'); $helper->log('Add image to spreadsheet 6 times with different opacities'); $sheet = $spreadsheet->getActiveSheet(); $sheet->setTitle('Squares different opacities'); $sheet->setShowGridLines(false); $drawing = new Drawing(); $drawing->setName('Blue Square opacity not specified'); $drawing->setPath($path); $drawing->setCoordinates('A1'); $drawing->setCoordinates2('B5'); $drawing->setWorksheet($sheet); $drawing = new Drawing(); $drawing->setName('Blue Square opacity 80%'); $drawing->setPath($path); $drawing->setCoordinates('C1'); $drawing->setCoordinates2('D5'); $drawing->setOpacity(80000); $drawing->setWorksheet($sheet); $drawing = new Drawing(); $drawing->setWorksheet($sheet); $drawing->setName('Blue Square opacity 60%'); $drawing->setPath($path); $drawing->setCoordinates('E1'); $drawing->setCoordinates2('F5'); $drawing->setOpacity(60000); $drawing = new Drawing(); $drawing->setName('Blue Square opacity 40%'); $drawing->setPath($path); $drawing->setCoordinates('A8'); $drawing->setCoordinates2('B12'); $drawing->setOpacity(40000); $drawing->setWorksheet($sheet); $drawing = new Drawing(); $drawing->setName('Blue Square opacity 20%'); $drawing->setPath($path); $drawing->setCoordinates('C8'); $drawing->setCoordinates2('D12'); $drawing->setOpacity(20000); $drawing->setWorksheet($sheet); $drawing = new Drawing(); $drawing->setWorksheet($sheet); $drawing->setName('Blue Square opacity 0%'); $drawing->setPath($path); $drawing->setCoordinates('E8'); $drawing->setCoordinates2('F12'); $drawing->setOpacity(0); // Save $helper->write($spreadsheet, __FILE__, ['Xlsx', 'Html', 'Dompdf', 'Mpdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic5/54_ImagesInAndOut.php ================================================ getProperties()->setTitle('53_ImageOpacity'); $sheet = $spreadsheet->getActiveSheet(); $sheet->setTitle('Images in-cell and out'); $sheet->setShowGridLines(false); $helper->log('Add in-cell image to spreadsheet'); $sheet->setCellValue('B1', 'inside'); $drawing = new Drawing(); $drawing->setName('Blue Square in-cell'); $drawing->setPath($path); $sheet->getCell('B2')->setValue($drawing); $helper->log('Add image over cell to spreadsheet'); $sheet->setCellValue('C1', 'outside'); $drawing = new Drawing(); $drawing->setName('Blue Square out-of-cell'); $drawing->setPath($path); $drawing->setCoordinates('C2'); $drawing->setCoordinates2('D6'); $drawing->setWorksheet($sheet); $helper->log('In-cell supported only for Xlsx'); $helper->write($spreadsheet, __FILE__, ['Xlsx']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic5/55_DefinedStyles.php ================================================ getActiveSheet(); $array = [ ['NUMBER', 1, NumberFormat::FORMAT_NUMBER], ['NUMBER_0', 1, NumberFormat::FORMAT_NUMBER_0], ['NUMBER_00', 1, NumberFormat::FORMAT_NUMBER_00], ['NUMBER_COMMA_SEPARATED1', 1234, NumberFormat::FORMAT_NUMBER_COMMA_SEPARATED1], ['NUMBER_COMMA_SEPARATED2', 1234, NumberFormat::FORMAT_NUMBER_COMMA_SEPARATED2], ['PERCENTAGE', 0.98, NumberFormat::FORMAT_PERCENTAGE], ['PERCENTAGE_0', 0.985, NumberFormat::FORMAT_PERCENTAGE_0], ['PERCENTAGE_00', 0.9856, NumberFormat::FORMAT_PERCENTAGE_00], ['DATE_YYYYMMDD', 46000, NumberFormat::FORMAT_DATE_YYYYMMDD], ['DATE_DDMMYYYY', 46000, NumberFormat::FORMAT_DATE_DDMMYYYY], ['DATE_DMYSLASH', 46000, NumberFormat::FORMAT_DATE_DMYSLASH], ['DATE_DMYMINUS', 46000, NumberFormat::FORMAT_DATE_DMYMINUS], ['DATE_DMMINUS', 46000, NumberFormat::FORMAT_DATE_DMMINUS], ['DATE_MYMINUS', 46000, NumberFormat::FORMAT_DATE_MYMINUS], ['DATE_XLSX14', 46000, NumberFormat::FORMAT_DATE_XLSX14], ['DATE_XLSX14_ACTUAL', 46000, NumberFormat::FORMAT_DATE_XLSX14_ACTUAL], ['DATE_XLSX15', 46000, NumberFormat::FORMAT_DATE_XLSX15], ['DATE_XLSX15_YYYY', 46000, NumberFormat::FORMAT_DATE_XLSX15_YYYY], ['DATE_XLSX16', 46000, NumberFormat::FORMAT_DATE_XLSX16], ['DATE_XLSX17', 46000, NumberFormat::FORMAT_DATE_XLSX17], ['DATE_XLSX22', 46000, NumberFormat::FORMAT_DATE_XLSX22], ['DATE_XLSX22_ACTUAL', 46000, NumberFormat::FORMAT_DATE_XLSX22_ACTUAL], ['DATE_DATETIME', 46000.25, NumberFormat::FORMAT_DATE_DATETIME], ['DATE_DATETIME_BETTER', 46000.25, NumberFormat::FORMAT_DATE_DATETIME_BETTER], ['DATE_TIME1', 46000.25, NumberFormat::FORMAT_DATE_TIME1], ['DATE_TIME2', 46000.25, NumberFormat::FORMAT_DATE_TIME2], ['DATE_TIME3', 46000.25, NumberFormat::FORMAT_DATE_TIME3], ['DATE_TIME4', 46000.25, NumberFormat::FORMAT_DATE_TIME4], ['DATE_TIME5', 46000.25, NumberFormat::FORMAT_DATE_TIME5], ['DATE_TIME6', 46000.25, NumberFormat::FORMAT_DATE_TIME6], ['DATE_TIME7', 46000.25, NumberFormat::FORMAT_DATE_TIME7], ['DATE_TIME8', 46000.25, NumberFormat::FORMAT_DATE_TIME8], [' DATE_TIME_INTERVAL_HMS', 0.0087731481481482, NumberFormat::FORMAT_DATE_TIME_INTERVAL_HMS], ['DATE_YYYYMMDDSLASH', 46000, NumberFormat::FORMAT_DATE_YYYYMMDDSLASH], ['DATE_LONG_DATE', 46000, NumberFormat::FORMAT_DATE_LONG_DATE], ['CURRENCY_USD_INTEGER', 1234.56, NumberFormat::FORMAT_CURRENCY_USD_INTEGER], ['CURRENCY_USD', 1234.56, NumberFormat::FORMAT_CURRENCY_USD], ['CURRENCY_EUR_INTEGER', 1234.56, NumberFormat::FORMAT_CURRENCY_EUR_INTEGER], ['CURRENCY_EUR', 1234.56, NumberFormat::FORMAT_CURRENCY_EUR], ['CURRENCY_GBP_INTEGER', 1234.56, NumberFormat::FORMAT_CURRENCY_GBP_INTEGER], ['CURRENCY_GBP', 1234.56, NumberFormat::FORMAT_CURRENCY_GBP], ['CURRENCY_YEN_YUAN_INTEGER', 1234.56, NumberFormat::FORMAT_CURRENCY_YEN_YUAN_INTEGER], ['CURRENCY_YEN_YUAN', 1234.56, NumberFormat::FORMAT_CURRENCY_YEN_YUAN], ['ACCOUNTING_USD', 1234.56, NumberFormat::FORMAT_CURRENCY_USD], ['ACCOUNTING_EUR', 1234.56, NumberFormat::FORMAT_CURRENCY_EUR], ['CUSTOM1', 1234.56, '0.000'], ['CUSTOM2', 1234.56, '"$"#,##0.00_);[Red]\("$"#,##0.00\)'], ]; $row = 0; $helper->log('Populate spreadsheet'); foreach ($array as $cells) { ++$row; $sheet->getCell("A$row")->setValue($cells[0]); $sheet->getCell("B$row")->setValue($cells[1]); if (!str_starts_with($cells[0], 'DATE')) { $sheet->getCell("C$row")->setValue(-$cells[1]); } $sheet->getStyle("B$row:C$row") ->getNumberFormat() ->setFormatCode($cells[2]); } $sheet->getColumnDimension('A')->setAutoSize(true); $sheet->getColumnDimension('B')->setAutoSize(true); $sheet->getColumnDimension('C')->setAutoSize(true); $sheet->setSelectedCells('A1'); function threeDecimalPlaces(Style $obj, string $name): void { $writer = $obj->getWriter(); $writer->startElement('number:number-style'); $writer->writeAttribute('style:name', $name); $writer->startElement('number:number'); $writer->writeAttribute('number:decimal-places', '3'); $writer->writeAttribute('number:min-decimal-places', '3'); $writer->writeAttribute('number:min-integer-digits', '1'); $writer->endElement(); // number:number $writer->endElement(); // number:number-style } function redBrackets(Style $obj, string $name): void { $writer = $obj->getWriter(); $writer->startElement('number:currency-style'); $writer->writeAttribute('style:name', $name . 'P0'); $writer->writeElement('number:currency-symbol', '$'); $writer->startElement('number:number'); $writer->writeAttribute('number:decimal-places', '2'); $writer->writeAttribute('number:min-decimal-places', '2'); $writer->writeAttribute('number:min-integer-digits', '1'); $writer->writeAttribute('number:grouping', 'true'); $writer->endElement(); // number:number $writer->writeElement('number:text', ' '); $writer->endElement(); // number:currency-style $writer->startElement('number:currency-style'); $writer->writeAttribute('style:name', $name); $writer->startElement('style:text-properties'); $writer->writeAttribute('fo:color', '#FF0000'); $writer->endElement(); // style:text-properties $writer->writeElement('number:text', '($'); $writer->startElement('number:number'); $writer->writeAttribute('number:decimal-places', '2'); $writer->writeAttribute('number:min-decimal-places', '2'); $writer->writeAttribute('number:min-integer-digits', '1'); $writer->writeAttribute('number:grouping', 'true'); $writer->endElement(); // number:number $writer->writeElement('number:text', ')'); $writer->startElement('style:map'); $writer->writeAttribute('style:condition', 'value()>=0'); $writer->writeAttribute('style:apply-style-name', $name . 'P0'); $writer->endElement(); // style:map $writer->endElement(); // number:currency-style } function writeAdditional(BaseWriter $writer): void { if (method_exists($writer, 'useAdditionalNumberFormats')) { $array = [ '0.000' => threeDecimalPlaces(...), '"$"#,##0.00_);[Red]\("$"#,##0.00\)' => redBrackets(...), ]; $writer->useAdditionalNumberFormats($array); } } $helper->write($spreadsheet, __FILE__, ['Xlsx', 'Ods'], writerCallback: writeAdditional(...)); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Basic5/56_OdsToISO8601.php ================================================ open($infile) !== true) { throw new Exception("unable to open zip $infile"); } $files = ['content.xml', 'styles.xml']; $modified = false; foreach ($files as $file) { $data = $zip->getFromName($file); if ($data === false) { throw new Exception("unable to read member $file"); } $newData = str_replace('
getPageHeading();
================================================
FILE: samples/HexEtcConversions/BIN2DEC.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[101],
[110110],
[1000000],
[11111111],
[100010101],
[110001100],
[111111111],
[1111111111],
[1100110011],
[1000000000],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=BIN2DEC(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Binary ' . $worksheet->getCell("A$row")->getValueString()
. ' is decimal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/BIN2HEX.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[101],
[110110],
[1000000],
[11111111],
[100010101],
[110001100],
[111111111],
[1111111111],
[1100110011],
[1000000000],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=BIN2HEX(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Binary ' . $worksheet->getCell("A$row")->getValueString()
. ' is hexadecimal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/BIN2OCT.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[101],
[110110],
[1000000],
[11111111],
[100010101],
[110001100],
[111111111],
[1111111111],
[1100110011],
[1000000000],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=BIN2OCT(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Binary ' . $worksheet->getCell("A$row")->getValueString()
. ' is octal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/DEC2BIN.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[-255],
[-123],
[-15],
[-1],
[5],
[7],
[19],
[51],
[121],
[256],
[511],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=DEC2BIN(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Decimal ' . $worksheet->getCell("A$row")->getValueString()
. ' is binary ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/DEC2HEX.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[-255],
[-123],
[-15],
[-1],
[5],
[7],
[19],
[51],
[121],
[256],
[511],
[12345678],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=DEC2HEX(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Decimal ' . $worksheet->getCell("A$row")->getValueString()
. ' is hexadecimal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/DEC2OCT.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[-255],
[-123],
[-15],
[-1],
[5],
[7],
[19],
[51],
[121],
[256],
[511],
[12345678],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=DEC2OCT(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Decimal ' . $worksheet->getCell("A$row")->getValueString()
. ' is octal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/HEX2BIN.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[3],
[8],
[42],
[99],
['A2'],
['F0'],
['100'],
['128'],
['1AB'],
['1FF'],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=HEX2BIN(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Hexadecimal ' . $worksheet->getCell("A$row")->getValueString()
. ' is binary ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/HEX2DEC.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
['08'],
['42'],
['A2'],
['400'],
['1000'],
['1234'],
['ABCD'],
['C3B0'],
['FFFFFFFFF'],
['FFFFFFFFFF'],
['FFFFFFF800'],
['FEDCBA9876'],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=HEX2DEC(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Hexadecimal ' . $worksheet->getCell("A$row")->getValueString()
. ' is decimal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/HEX2OCT.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
['08'],
['42'],
['A2'],
['400'],
['100'],
['1234'],
['ABCD'],
['C3B0'],
['FFFFFFFFFF'],
['FFFFFFF800'],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=HEX2OCT(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Hexadecimal ' . $worksheet->getCell("A$row")->getValueString()
. ' is octal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/OCT2BIN.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[3],
[7],
[42],
[70],
[72],
[77],
[100],
[127],
[177],
[456],
[567],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=OCT2BIN(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Octal ' . $worksheet->getCell("A$row")->getValueString()
. ' is binary ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/OCT2DEC.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[3],
[7],
[42],
[70],
[72],
[77],
[100],
[127],
[177],
[456],
[4567],
[7777700001],
[7777776543],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=OCT2DEC(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Octal ' . $worksheet->getCell("A$row")->getValueString()
. ' is decimal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/HexEtcConversions/OCT2HEX.php
================================================
titles($category, $functionName, $description);
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
// Add some data
$testData = [
[3],
[12],
[42],
[70],
[72],
[77],
[100],
[127],
[177],
[456],
[4567],
[7777700001],
[7777776543],
];
$testDataCount = count($testData);
$worksheet->fromArray($testData, null, 'A1', true);
for ($row = 1; $row <= $testDataCount; ++$row) {
$worksheet->setCellValue('B' . $row, '=OCT2HEX(A' . $row . ')');
}
// Test the formulae
for ($row = 1; $row <= $testDataCount; ++$row) {
$helper->log(
"(B$row): "
. 'Octal ' . $worksheet->getCell("A$row")->getValueString()
. ' is hexadecimal ' . $worksheet->getCell("B$row")->getCalculatedValueString()
);
}
================================================
FILE: samples/Html/html_01_Basic_Conditional_Formatting.php
================================================
isCli() ? ('samples/templates/' . $inputFileName) : ('> $original */
function displaySortedCols(array $original, Sample $helper): void
{
$sorted = $original;
$sortExcelCols = new SortExcelCols();
$helper->log('Sort by least significant column (descending)');
$sortExcelCols->sortArray($sorted, arrayCol: 2, ascending: -1);
$helper->log('Sort by middle column (ascending)');
$sortExcelCols->sortArray($sorted, arrayCol: 1, ascending: 1);
$helper->log('Sort by most significant column (descending)');
$sortExcelCols->sortArray($sorted, arrayCol: 0, ascending: -1);
$outArray = [['Original', '', '', 'Sorted', '', '']];
$count = count($original);
/** @var string[][] $sorted */
for ($i = 0; $i < $count; ++$i) {
$outArray[] = [
$original[$i][0],
$original[$i][1],
$original[$i][2],
$sorted[$i][0],
$sorted[$i][1],
$sorted[$i][2],
];
}
$helper->displayGrid($outArray, TextGridRightAlign::floatOrInt);
}
displaySortedCols($array, $helper);
================================================
FILE: samples/LookupRef/VLOOKUP.php
================================================
log('Searches for a value in the top row of a table or an array of values,
and then returns a value in the same column from a row you specify
in the table or array.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$data = [
['ID', 'First Name', 'Last Name', 'Salary'],
[72, 'Emily', 'Smith', 64901],
[66, 'James', 'Anderson', 70855],
[14, 'Mia', 'Clark', 188657],
[30, 'John', 'Lewis', 97566],
[53, 'Jessica', 'Walker', 58339],
[56, 'Mark', 'Reed', 125180],
[79, 'Richard', 'Lopez', 91632],
];
$worksheet->fromArray($data, null, 'B2');
$lookupFields = [
['ID', 53, 66, 56],
['Name'],
['Salary'],
];
$worksheet->fromArray($lookupFields, null, 'G3');
$worksheet->getCell('H4')->setValue('=VLOOKUP(H3, B3:E9, 2, FALSE) & " " & VLOOKUP(H3, B3:E9, 3, FALSE)');
$worksheet->getCell('I4')->setValue('=VLOOKUP(I3, B3:E9, 2, FALSE) & " " & VLOOKUP(I3, B3:E9, 3, FALSE)');
$worksheet->getCell('J4')->setValue('=VLOOKUP(J3, B3:E9, 2, FALSE) & " " & VLOOKUP(J3, B3:E9, 3, FALSE)');
$worksheet->getCell('H5')->setValue('=VLOOKUP(H3, B3:E9, 4, FALSE)');
$worksheet->getCell('I5')->setValue('=VLOOKUP(I3, B3:E9, 4, FALSE)');
$worksheet->getCell('J5')->setValue('=VLOOKUP(J3, B3:E9, 4, FALSE)');
for ($column = 'H'; $column !== 'K'; StringHelper::stringIncrement($column)) {
for ($row = 4; $row <= 5; ++$row) {
$cell = $worksheet->getCell("{$column}{$row}");
$helper->log("{$column}{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
}
================================================
FILE: samples/Pdf/21_Pdf_Domdf.php
================================================
log('Hide grid lines');
$spreadsheet->getActiveSheet()->setShowGridLines(false);
$helper->log('Set orientation to landscape');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE);
$className = PhpOffice\PhpSpreadsheet\Writer\Pdf\Dompdf::class;
$helper->log("Write to PDF format using {$className}");
IOFactory::registerWriter('Pdf', $className);
// Save
$helper->write($spreadsheet, __FILE__, ['Pdf']);
================================================
FILE: samples/Pdf/21_Pdf_TCPDF.php
================================================
log('Hide grid lines');
$spreadsheet->getActiveSheet()->setShowGridLines(false);
$helper->log('Set orientation to landscape');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE);
$className = PhpOffice\PhpSpreadsheet\Writer\Pdf\Tcpdf::class;
$helper->log("Write to PDF format using {$className}");
IOFactory::registerWriter('Pdf', $className);
// Save
$helper->write($spreadsheet, __FILE__, ['Pdf']);
================================================
FILE: samples/Pdf/21_Pdf_mPDF.php
================================================
log('Hide grid lines');
$spreadsheet->getActiveSheet()->setShowGridLines(false);
$helper->log('Set orientation to landscape');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE);
$className = PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf::class;
$helper->log("Write to PDF format using {$className}");
IOFactory::registerWriter('Pdf', $className);
// Save
$helper->write($spreadsheet, __FILE__, ['Pdf']);
================================================
FILE: samples/Pdf/21a_Pdf.php
================================================
log('Hide grid lines');
$spreadsheet->getActiveSheet()->setShowGridLines(false);
$helper->log('Set orientation to landscape');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE);
$spreadsheet->setActiveSheetIndex(0)->setPrintGridlines(true);
// Issue 2299 - mpdf can't handle hide rows without kludge
$spreadsheet->getActiveSheet()->getRowDimension(2)->setVisible(false);
function changeGridlines(string $html): string
{
return str_replace('{border: 1px solid black;}', '{border: 2px dashed red;}', $html);
}
$helper->log('Write to Mpdf');
IOFactory::registerWriter('Pdf', Mpdf::class);
$helper->write(
$spreadsheet,
__FILE__,
['Pdf'],
false,
function (Mpdf $writer): void {
$writer->setEmbedImages(true);
$writer->setEditHtmlCallback('changeGridlines');
}
);
================================================
FILE: samples/Pdf/21b_Pdf.php
================================================
.*~ms';
$bodyrepl = <<
'; } $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21f_Drawing.php ================================================ getActiveSheet(); $sheet->getCell('A1')->setValue('A1'); $sheet->getCell('B1')->setValue('B'); $sheet->getCell('C1')->setValue('C'); $sheet->getCell('D1')->setValue('D'); $sheet->getCell('E1')->setValue('E'); $sheet->getCell('F1')->setValue('F'); $sheet->getCell('G1')->setValue('G'); $sheet->getCell('A2')->setValue('A2'); $sheet->getCell('A3')->setValue('A3'); $sheet->getCell('A4')->setValue('A4'); $sheet->getCell('A5')->setValue('A5'); $sheet->getCell('A6')->setValue('A6'); $sheet->getCell('A7')->setValue('A7'); $sheet->getCell('A8')->setValue('A8'); $helper->log('Add drawing to worksheet'); $drawing = new Drawing(); $drawing->setName('Blue Square'); $path = __DIR__ . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'images/blue_square.png'; $drawing->setPath($path); $drawing->setResizeProportional(false); $drawing->setWidth(320); $drawing->setCoordinates('B2'); $drawing->setCoordinates2('G6'); $drawing->setWorksheet($sheet, true); $helper->log('Merge drawing cells for Pdf'); $spreadsheet->mergeDrawingCellsForPdf(); $helper->log('Write to Mpdf'); $helper->write($spreadsheet, __FILE__, ['Mpdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21g_Direction.php ================================================ getActiveSheet(); $sheet1 = $spreadsheet->getActiveSheet(); $sheet2 = $spreadsheet->createSheet(); $sheet3 = $spreadsheet->createSheet(); $cells = [ ['a1', 'b1', 'c1'], ['a2', 'b2', 'c2'], ]; $sheet1->fromArray($cells); $sheet1->setRightToLeft(true); $sheet2->fromArray($cells); $sheet3->fromArray($cells); $sheet3->setRightToLeft(true); $helper->log('Write to html, mpdf, tcpdf'); // Save $helper->write($spreadsheet, __FILE__, ['Html', 'Mpdf', 'Tcpdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21h_DirectionMultiple.php ================================================ getActiveSheet(); $sheet1 = $spreadsheet->getActiveSheet(); $sheet2 = $spreadsheet->createSheet(); $sheet3 = $spreadsheet->createSheet(); $cells = [ ['a1', 'b1', 'c1'], ['a2', 'b2', 'c2'], ]; $sheet1->fromArray($cells); $sheet1->setRightToLeft(true); $sheet2->fromArray($cells); $sheet3->fromArray($cells); $sheet3->setRightToLeft(true); $helper->log('Write to html, mpdf'); // Save $helper->write( $spreadsheet, __FILE__, ['Html', 'Mpdf'], writerCallback: function (HtmlWriter $writer): void { $writer->writeAllSheets(); } ); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/Dompdf_Canvas_Headers.php ================================================ getCanvas()->page_script(function ( int $pageNumber, int $pageCount, Canvas $canvas, FontMetrics $fontMetrics ): void { // Get font metrics for dynamic content like page numbers $fontName = 'helvetica'; // note lowercase $fontType = 'bold'; // note lowercase $font = $fontMetrics->getFont($fontName, $fontType) ?? throw new Exception("no font metrics for $fontName $fontType"); // Example text placement (adjust coordinates and font as needed) if ($pageNumber === 1) { $header = 'Dompdf First Page'; } elseif ($pageNumber % 2 === 0) { $header = 'Dompdf Even Page'; } else { $header = 'Dompdf Odd Page'; } $text = "$header Page $pageNumber of $pageCount"; $canvas->text(40, 20, $text, $font, 12); }); } } $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); $counter = 0; /** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */ $helper->log('Populate spreadsheet'); for ($row = 1; $row < 1001; ++$row) { $sheet->getCell("A$row")->setValue(++$counter); // Add many styles by using slight variations of font color for each. $sheet->getCell("A$row")->getStyle()->getFont() ->getColor()->setRgb(sprintf('%06x', $counter)); $sheet->getCell("B$row")->setValue(++$counter); $sheet->getCell("C$row")->setValue(++$counter); } $helper->log('Write to Dompdf with headers added by page_script'); IOFactory::registerWriter('Pdf', Dompdf_Canvas_Headers::class); $helper->write($spreadsheet, __FILE__, ['Pdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/Dompdf_Custom_Headers.php ================================================ header { position: fixed; top: -0.5in; /* Position in top margin area */ height: 0.5in; width: 100%; text-align: center; } footer { position: fixed; bottom: -0.5in; /* Position in bottom margin area */ height: 0.5in; width: 100%; text-align: right; } .pagenum:before {content: counter(page);} EOF; $endhead = ''; $html = str_replace($endhead, "$headerFooter$endhead", $html); $bodystring = ''; $bodyrepl = <<
Dompdf Fixed header
EOF;
return str_replace($bodystring, $bodyrepl, $html);
}
$spreadsheet = new Spreadsheet();
$sheet = $spreadsheet->getActiveSheet();
$counter = 0;
/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
$helper->log('Populate spreadsheet');
for ($row = 1; $row < 1001; ++$row) {
$sheet->getCell("A$row")->setValue(++$counter);
// Add many styles by using slight variations of font color for each.
$sheet->getCell("A$row")->getStyle()->getFont()
->getColor()->setRgb(sprintf('%06x', $counter));
$sheet->getCell("B$row")->setValue(++$counter);
$sheet->getCell("C$row")->setValue(++$counter);
}
$helper->log('Write to Dompdf');
IOFactory::registerWriter('Pdf', Dompdf::class);
$helper->write(
$spreadsheet,
__FILE__,
['Pdf'],
false,
function (Dompdf $writer): void {
$writer->setEditHtmlCallback('addHeadersFootersDompdf2000');
}
);
$spreadsheet->disconnectWorksheets();
================================================
FILE: samples/Pdf/Mpdf_Custom_Headers.php
================================================
/';
$simulatedBodyStart = Mpdf::SIMULATED_BODY_START;
$bodyrepl = <<
$simulatedBodyStart
EOF;
return preg_replace($bodystring, $bodyrepl, $html) ?? throw new SpreadsheetException('preg 2 failed');
}
$spreadsheet = new Spreadsheet();
$sheet = $spreadsheet->getActiveSheet();
$counter = 0;
/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
$helper->log('Populate spreadsheet');
for ($row = 1; $row < 1001; ++$row) {
$sheet->getCell("A$row")->setValue(++$counter);
// Add many styles by using slight variations of font color for each.
$sheet->getCell("A$row")->getStyle()->getFont()
->getColor()->setRgb(sprintf('%06x', $counter));
$sheet->getCell("B$row")->setValue(++$counter);
$sheet->getCell("C$row")->setValue(++$counter);
}
$helper->log('Write to Mpdf');
IOFactory::registerWriter('Pdf', Mpdf::class);
$helper->write(
$spreadsheet,
__FILE__,
['Pdf'],
false,
function (Mpdf $writer): void {
$writer->setEditHtmlCallback('addHeadersFootersMpdf2000');
}
);
$spreadsheet->disconnectWorksheets();
================================================
FILE: samples/Pdf/Tcpdf_Custom_Headers.php
================================================
defines();
return new Tcpdf2Class($orientation, $unit, $paperSize);
}
}
// Override vendor class.
class Tcpdf2Class extends VendorTcpdf // phpcs:ignore
{
// Page header
public function Header(): void // phpcs:ignore
{
// Position at 15 mm from top
$this->setY(15);
// Set font
$this->setFont('helvetica', 'B', 12);
// Title
$pageNum = $this->getPage();
if ($pageNum === 1) {
$this->Cell(0, 15, 'Tcpdf first header', 0, 0, 'C', false, '', 0, false, 'M', 'M');
} elseif ($pageNum % 2 === 0) {
$this->Cell(0, 15, 'Tcpdf even header', 0, 0, 'C', false, '', 0, false, 'M', 'M');
} else {
$this->Cell(0, 15, 'Tcpdf odd header', 0, 0, 'C', false, '', 0, false, 'M', 'M');
}
}
// Page footer
public function Footer(): void // phpcs:ignore
{
// Position at 15 mm from bottom
$this->setY(-15);
// Set font
$this->setFont('helvetica', 'I', 8);
// Page number
$this->Cell(0, 10, 'Page ' . $this->getAliasNumPage() . '/' . $this->getAliasNbPages(), 0, 0, 'C', false, '', 0, false, 'T', 'M');
}
}
$spreadsheet = new Spreadsheet();
$sheet = $spreadsheet->getActiveSheet();
$counter = 0;
/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
$helper->log('Populate spreadsheet');
for ($row = 1; $row < 1001; ++$row) {
$sheet->getCell("A$row")->setValue(++$counter);
// Add many styles by using slight variations of font color for each.
$sheet->getCell("A$row")->getStyle()->getFont()
->getColor()->setRgb(sprintf('%06x', $counter));
$sheet->getCell("B$row")->setValue(++$counter);
$sheet->getCell("C$row")->setValue(++$counter);
}
$helper->log('Write to Tcpdf with headers and footers');
IOFactory::registerWriter('Pdf', Tcpdf2::class);
$helper->write($spreadsheet, __FILE__, ['Pdf']);
$spreadsheet->disconnectWorksheets();
================================================
FILE: samples/Reader/01_Simple_file_reader_using_IOFactory.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory to identify the format');
$spreadsheet = IOFactory::load($inputFileName);
$sheetData = $spreadsheet->getActiveSheet()->toArray(null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/02_Simple_file_reader_using_a_specified_reader.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using ' . Xls::class);
$reader = new Xls();
$spreadsheet = $reader->load($inputFileName);
$sheetData = $spreadsheet->getActiveSheet()->toArray(null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/03_Simple_file_reader_using_the_IOFactory_to_return_a_reader.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$reader = IOFactory::createReader($inputFileType);
$spreadsheet = $reader->load($inputFileName);
$sheetData = $spreadsheet->getActiveSheet()->toArray(null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/04_Simple_file_reader_using_the_IOFactory_to_identify_a_reader_to_use.php
================================================
log('File ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' has been identified as an ' . $inputFileType . ' file');
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with the identified reader type');
$reader = IOFactory::createReader($inputFileType);
$spreadsheet = $reader->load($inputFileName);
$sheetData = $spreadsheet->getActiveSheet()->toArray(null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/05_Simple_file_reader_using_the_read_data_only_option.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$reader = IOFactory::createReader($inputFileType);
$helper->log('Turning Formatting off for Load');
$reader->setReadDataOnly(true);
$spreadsheet = $reader->load($inputFileName);
$sheetData = $spreadsheet->getActiveSheet()->toArray(null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/06_Simple_file_reader_loading_all_worksheets.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$reader = IOFactory::createReader($inputFileType);
$helper->log('Loading all WorkSheets');
$reader->setLoadAllSheets();
$spreadsheet = $reader->load($inputFileName);
$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
$loadedSheetNames = $spreadsheet->getSheetNames();
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log($sheetIndex . ' -> ' . $loadedSheetName);
}
================================================
FILE: samples/Reader/07_Simple_file_reader_loading_a_single_named_worksheet.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$reader = IOFactory::createReader($inputFileType);
$helper->log('Loading Sheet "' . $sheetname . '" only');
$reader->setLoadSheetsOnly($sheetname);
$spreadsheet = $reader->load($inputFileName);
$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
$loadedSheetNames = $spreadsheet->getSheetNames();
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log($sheetIndex . ' -> ' . $loadedSheetName);
}
================================================
FILE: samples/Reader/08_Simple_file_reader_loading_several_named_worksheets.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$reader = IOFactory::createReader($inputFileType);
$helper->log('Loading Sheets "' . implode('" and "', $sheetnames) . '" only');
$reader->setLoadSheetsOnly($sheetnames);
$spreadsheet = $reader->load($inputFileName);
$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
$loadedSheetNames = $spreadsheet->getSheetNames();
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log($sheetIndex . ' -> ' . $loadedSheetName);
}
================================================
FILE: samples/Reader/09_Simple_file_reader_using_a_read_filter.php
================================================
= 9 && $row <= 15) {
if (in_array($columnAddress, range('A', 'E'))) {
return true;
}
}
return false;
}
}
$filterSubset = new MyReadFilter();
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$helper->log('Filter range is A9:E15');
$reader = IOFactory::createReader($inputFileType);
$helper->log('Loading Sheet "' . $sheetname . '" only');
$reader->setLoadSheetsOnly($sheetname);
$helper->log('Loading Sheet using filter');
$reader->setReadFilter($filterSubset);
$spreadsheet = $reader->load($inputFileName);
$activeRange = $spreadsheet->getActiveSheet()->calculateWorksheetDataDimension();
$sheetData = $spreadsheet->getActiveSheet()->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/10_Simple_file_reader_using_a_configurable_read_filter.php
================================================
$columns */
public function __construct(
private int $startRow,
private int $endRow,
private array $columns
) {
}
public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool
{
if ($row >= $this->startRow && $row <= $this->endRow) {
if (in_array($columnAddress, $this->columns)) {
return true;
}
}
return false;
}
}
$filterSubset = new MyReadFilter(9, 15, range('G', 'K'));
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
$helper->log('Filter range is G9:K15');
$reader = IOFactory::createReader($inputFileType);
$helper->log('Loading Sheet "' . $sheetname . '" only');
$reader->setLoadSheetsOnly($sheetname);
$helper->log('Loading Sheet using configurable filter');
$reader->setReadFilter($filterSubset);
$spreadsheet = $reader->load($inputFileName);
$activeRange = $spreadsheet->getActiveSheet()->calculateWorksheetDataDimension();
$sheetData = $spreadsheet->getActiveSheet()->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData);
================================================
FILE: samples/Reader/11_Reading_a_workbook_in_chunks_using_a_configurable_read_filter_version_1.php
================================================
startRow = $startRow;
$this->endRow = $startRow + $chunkSize;
}
public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool
{
// Only read the heading row, and the rows that were configured in the constructor
if (($row == 1) || ($row >= $this->startRow && $row < $this->endRow)) {
return true;
}
return false;
}
}
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
// Create a new Reader of the type defined in $inputFileType
$reader = IOFactory::createReader($inputFileType);
// Define how many rows we want for each "chunk"
$chunkSize = 20;
// Loop to read our worksheet in "chunk size" blocks
for ($startRow = 2; $startRow <= 240; $startRow += $chunkSize) {
$helper->log('Loading WorkSheet using configurable filter for headings row 1 and for rows ' . $startRow . ' to ' . ($startRow + $chunkSize - 1));
// Create a new Instance of our Read Filter, passing in the limits on which rows we want to read
$chunkFilter = new ChunkReadFilter($startRow, $chunkSize);
// Tell the Reader that we want to use the new Read Filter that we've just Instantiated
$reader->setReadFilter($chunkFilter);
// Load only the rows that match our filter from $inputFileName to a PhpSpreadsheet Object
$spreadsheet = $reader->load($inputFileName);
$sheet = $spreadsheet->getActiveSheet();
// Do some processing here
$activeRange = $sheet->calculateWorksheetDataDimension();
$sheet->getStyle($activeRange)->getNumberFormat()
->setFormatCode('0.000');
$sheetData = $sheet->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData, true);
}
================================================
FILE: samples/Reader/12_Reading_a_workbook_in_chunks_using_a_configurable_read_filter_version_2.php
================================================
startRow = $startRow;
$this->endRow = $startRow + $chunkSize;
}
public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool
{
// Only read the heading row, and the rows that are configured in $this->_startRow and $this->_endRow
if (($row == 1) || ($row >= $this->startRow && $row < $this->endRow)) {
return true;
}
return false;
}
}
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory with a defined reader type of ' . $inputFileType);
// Create a new Reader of the type defined in $inputFileType
$reader = IOFactory::createReader($inputFileType);
// Define how many rows we want to read for each "chunk"
$chunkSize = 20;
// Create a new Instance of our Read Filter
$chunkFilter = new ChunkReadFilter();
// Tell the Reader that we want to use the Read Filter that we've Instantiated
$reader->setReadFilter($chunkFilter);
// Loop to read our worksheet in "chunk size" blocks
for ($startRow = 2; $startRow <= 240; $startRow += $chunkSize) {
$helper->log('Loading WorkSheet using configurable filter for headings row 1 and for rows ' . $startRow . ' to ' . ($startRow + $chunkSize - 1));
// Tell the Read Filter, the limits on which rows we want to read this iteration
$chunkFilter->setRows($startRow, $chunkSize);
// Load only the rows that match our filter from $inputFileName to a PhpSpreadsheet Object
$spreadsheet = $reader->load($inputFileName);
$sheet = $spreadsheet->getActiveSheet();
// Do some processing here
$activeRange = $sheet->calculateWorksheetDataDimension();
$sheet->getStyle($activeRange)->getNumberFormat()
->setFormatCode('0.000');
$sheetData = $sheet->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData, true);
}
================================================
FILE: samples/Reader2/13_Simple_file_reader_for_multiple_CSV_files.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' into WorkSheet #1 using Csv Reader');
$spreadsheet = $reader->load($inputFileName);
$spreadsheet->getActiveSheet()->setTitle(pathinfo($inputFileName, PATHINFO_BASENAME));
foreach ($inputFileNames as $sheet => $inputFileName) {
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' into WorkSheet #' . ($sheet + 2) . ' using Csv Reader');
$reader->setSheetIndex($sheet + 1);
$reader->loadIntoExisting($inputFileName, $spreadsheet);
$spreadsheet->getActiveSheet()->setTitle(pathinfo($inputFileName, PATHINFO_BASENAME));
}
$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
$loadedSheetNames = $spreadsheet->getSheetNames();
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log('Worksheet #' . $sheetIndex . ' -> ' . $loadedSheetName . '');
$spreadsheet->setActiveSheetIndexByName($loadedSheetName);
$sheet = $spreadsheet->getActiveSheet();
$activeRange = $sheet->calculateWorksheetDataDimension();
$sheet->getStyle($activeRange)->getNumberFormat()
->setFormatCode('0.000');
$sheetData = $sheet->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData, true);
}
================================================
FILE: samples/Reader2/14_Reading_a_large_CSV_file_in_chunks_to_split_across_multiple_worksheets.php
================================================
startRow = $startRow;
$this->endRow = $startRow + $chunkSize;
}
public function readCell(string $columnAddress, int $row, string $worksheetName = ''): bool
{
// Only read the heading row, and the rows that are configured in $this->_startRow and $this->_endRow
if (($row == 1) || ($row >= $this->startRow && $row < $this->endRow)) {
return true;
}
return false;
}
}
$helper->log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using Csv reader');
// Create a new Reader of the type defined in $inputFileType
$reader = new Csv();
// Define how many rows we want to read for each "chunk"
$chunkSize = 100;
// Create a new Instance of our Read Filter
$chunkFilter = new ChunkReadFilter();
// Tell the Reader that we want to use the Read Filter that we've Instantiated
// and that we want to store it in contiguous rows/columns
$reader->setReadFilter($chunkFilter);
$reader->setContiguous(true);
// Instantiate a new PhpSpreadsheet object manually
$spreadsheet = new Spreadsheet();
// Set a sheet index
$sheet = 0;
// Loop to read our worksheet in "chunk size" blocks
/** $startRow is set to 2 initially because we always read the headings in row #1 * */
for ($startRow = 2; $startRow <= 240; $startRow += $chunkSize) {
$helper->log('Loading WorkSheet #' . ($sheet + 1) . ' using configurable filter for headings row 1 and for rows ' . $startRow . ' to ' . ($startRow + $chunkSize - 1));
// Tell the Read Filter, the limits on which rows we want to read this iteration
$chunkFilter->setRows($startRow, $chunkSize);
// Increment the worksheet index pointer for the Reader
$reader->setSheetIndex($sheet);
// Load only the rows that match our filter into a new worksheet in the PhpSpreadsheet Object
$reader->loadIntoExisting($inputFileName, $spreadsheet);
// Set the worksheet title (to reference the "sheet" of data that we've loaded)
// and increment the sheet index as well
$spreadsheet->getActiveSheet()->setTitle('Country Data #' . (++$sheet));
}
$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
$loadedSheetNames = $spreadsheet->getSheetNames();
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log('Worksheet #' . $sheetIndex . ' -> ' . $loadedSheetName . '');
$spreadsheet->setActiveSheetIndexByName($loadedSheetName);
$sheet = $spreadsheet->getActiveSheet();
$activeRange = $sheet->calculateWorksheetDataDimension();
$sheet->getStyle($activeRange)->getNumberFormat()
->setFormatCode('0.000');
$sheetData = $sheet->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData, true);
}
================================================
FILE: samples/Reader2/15_Simple_file_reader_for_tab_separated_value_file_using_the_Advanced_Value_Binder.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' into WorkSheet #1 using Csv reader');
$reader->setDelimiter("\t");
$spreadsheet = $reader->load($inputFileName);
$spreadsheet->getActiveSheet()->setTitle(pathinfo($inputFileName, PATHINFO_BASENAME));
$helper->log($spreadsheet->getSheetCount() . ' worksheet' . (($spreadsheet->getSheetCount() == 1) ? '' : 's') . ' loaded');
$loadedSheetNames = $spreadsheet->getSheetNames();
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log('Worksheet #' . $sheetIndex . ' -> ' . $loadedSheetName . ' (Formatted)');
$spreadsheet->setActiveSheetIndexByName($loadedSheetName);
$activeRange = $spreadsheet->getActiveSheet()->calculateWorksheetDataDimension();
$sheetData = $spreadsheet->getActiveSheet()->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData);
}
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log('Worksheet #' . $sheetIndex . ' -> ' . $loadedSheetName . ' (Unformatted)');
$spreadsheet->setActiveSheetIndexByName($loadedSheetName);
$activeRange = $spreadsheet->getActiveSheet()->calculateWorksheetDataDimension();
$sheetData = $spreadsheet->getActiveSheet()->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData);
}
foreach ($loadedSheetNames as $sheetIndex => $loadedSheetName) {
$helper->log('Worksheet #' . $sheetIndex . ' -> ' . $loadedSheetName . ' (Raw)');
$spreadsheet->setActiveSheetIndexByName($loadedSheetName);
$activeRange = $spreadsheet->getActiveSheet()->calculateWorksheetDataDimension();
$sheetData = $spreadsheet->getActiveSheet()->rangeToArray($activeRange, null, true, true, true);
$helper->displayGrid($sheetData);
}
================================================
FILE: samples/Reader2/16_Handling_loader_exceptions_using_TryCatch.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using IOFactory to identify the format');
try {
$spreadsheet = IOFactory::load($inputFileName);
} catch (ReaderException $e) {
$helper->log('Error loading file "' . pathinfo($inputFileName, PATHINFO_BASENAME) . '": ' . $e->getMessage());
}
================================================
FILE: samples/Reader2/17_Simple_file_reader_loading_several_named_worksheets.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' using Xls reader');
$reader = new Xls();
// Read the list of Worksheet Names from the Workbook file
$helper->log('Read the list of Worksheets in the WorkBook');
$worksheetNames = $reader->listWorksheetNames($inputFileName);
$helper->log('There are ' . count($worksheetNames) . ' worksheet' . ((count($worksheetNames) == 1) ? '' : 's') . ' in the workbook');
foreach ($worksheetNames as $worksheetName) {
$helper->log($worksheetName);
}
================================================
FILE: samples/Reader2/18_Reading_list_of_worksheets_without_loading_entire_file.php
================================================
log('Loading file ' . pathinfo($inputFileName, PATHINFO_BASENAME) . ' information using Xls reader');
$reader = new Xls();
$worksheetNames = $reader->listWorksheetNames($inputFileName);
$helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log( "\$wizard = new Wizard\\Accounting('{$_POST['currency']}', {$_POST['decimals']}, Wizard\\Number::" . (isset($_POST['thousands']) ? 'WITH_THOUSANDS_SEPARATOR' : 'WITHOUT_THOUSANDS_SEPARATOR') . ', Wizard\Currency::' . (((bool) $_POST['position']) ? 'LEADING_SYMBOL' : 'TRAILING_SYMBOL') . ');' ); $helper->log('$mask = $wizard->format();'); $helper->log('
echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Currency.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } $negatives = [ CurrencyNegative::minus, CurrencyNegative::redMinus, CurrencyNegative::parentheses, CurrencyNegative::redParentheses, ]; $negativesString = [ 'CurrencyNegative::minus', 'CurrencyNegative::redMinus', 'CurrencyNegative::parentheses', 'CurrencyNegative::redParentheses', ]; $currencies = [ '$' => 'US Dollars ($)', '€' => 'Euro (€)', '¥' => 'Japanese Yen (¥)', '£' => 'Pound Sterling (£)', '₹' => 'Rupee (₹)', '₽' => 'Rouble (₽)', ]; $postNegative = StringHelper::convertPostToString('negative'); if (!in_array($postNegative, ['0', '1', '2', '3'], true)) { $postNegative = '0'; } $postNegative = (int) $postNegative; ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } elseif (!in_array($_POST['currency'], array_keys($currencies), true)) { $helper->log('Unrecognized currency symbol'); } else { try { $negative = $negatives[$postNegative]; $wizard = new Wizard\Currency($_POST['currency'], (int) $_POST['decimals'], isset($_POST['thousands']), (bool) $_POST['position']); $wizard->setNegative($negative); $mask = $wizard->format(); $example = (string) NumberFormat::toFormattedString((float) $_POST['number'], $mask, [HtmlWriter::class, 'formatColorStatic']); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\CurrencyNegative;'); $helper->log( "\$wizard = new Wizard\\Currency('{$_POST['currency']}', {$_POST['decimals']}, Wizard\\Number::" . (isset($_POST['thousands']) ? 'WITH_THOUSANDS_SEPARATOR' : 'WITHOUT_THOUSANDS_SEPARATOR') . ', Wizard\Currency::' . (((bool) $_POST['position']) ? 'LEADING_SYMBOL' : 'TRAILING_SYMBOL') . ');' ); $helper->log('$wizard->setNegative(' . $negativesString[$postNegative] . ');'); $helper->log('$mask = $wizard->format();'); $helper->log('
echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Number.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } else { try { $wizard = new Wizard\Number((int) $_POST['decimals'], isset($_POST['thousands'])); $mask = $wizard->format(); $example = NumberFormat::toFormattedString((float) $_POST['number'], $mask); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log( "\$mask = Wizard\\Number({$_POST['decimals']}, Wizard\\Number::" . (isset($_POST['thousands']) ? 'WITH_THOUSANDS_SEPARATOR' : 'WITHOUT_THOUSANDS_SEPARATOR') . ');
' ); $helper->log('echo (string) $mask;'); $helper->log('
Mask:'); $helper->log($mask); $helper->log('Example:'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Percentage.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } else { try { $wizard = new Wizard\Percentage((int) $_POST['decimals']); $mask = $wizard->format(); $example = (string) NumberFormat::toFormattedString((float) $_POST['number'], $mask); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log("\$mask = Wizard\\Percentage({$_POST['decimals']});
"); $helper->log('echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Scientific.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } else { try { $wizard = new Wizard\Scientific((int) $_POST['decimals']); $mask = $wizard->format(); $example = (string) NumberFormat::toFormattedString((float) $_POST['number'], $mask); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log("\$mask = Wizard\\Scientific({$_POST['decimals']});
"); $helper->log('echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/bootstrap/css/phpspreadsheet.css ================================================ body { padding-top: 20px; padding-bottom: 20px; } .navbar { margin-bottom: 20px; } .navbar + h1 { margin-top: 70px; } .passed { color: #339900; } .failed { color: #ff0000; } ================================================ FILE: samples/download.php ================================================ getTemporaryFolder(), $filename, $filetype); $downloader->download(); } catch (Exception $e) { exit($e->getMessage()); } ================================================ FILE: samples/index.php ================================================ version_compare(PHP_VERSION, '8.1', '>='), 'PHP extension XML' => extension_loaded('xml'), 'PHP extension xmlwriter' => extension_loaded('xmlwriter'), 'PHP extension mbstring' => extension_loaded('mbstring'), 'PHP extension ZipArchive' => extension_loaded('zip'), 'PHP extension GD (optional)' => extension_loaded('gd'), 'PHP extension dom (optional)' => extension_loaded('dom'), ]; /** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */ if (!$helper->isCli()) { ?>
Requirement check';
echo 'Competency List
================================================
FILE: samples/templates/Excel2003XMLTest.xml
================================================
3
#000000
4
#0000ff
5
#008000
6
#00ccff
7
#800080
8
#993366
9
#c0c0c0
10
#c47512
11
#ccffcc
12
#ddbc7d
13
#ff0000
14
#ff00ff
15
#ff6600
16
#ff9900
17
#ff99cc
18
#ffff00
9000
13860
240
75
False
False
================================================
FILE: samples/templates/Mpdf2.php
================================================
$config Configuration array
*/
protected function createExternalWriterInstance($config): \Mpdf\Mpdf
{
/** @var string[][] */
$defaultConfig = (new \Mpdf\Config\ConfigVariables())->getDefaults();
$fontDirs = $defaultConfig['fontDir'];
$newFontDirectory = __DIR__;
$config['fontDir'] = array_merge($fontDirs, [$newFontDirectory]);
/** @var string[][][] */
$defaultFontConfig = (new \Mpdf\Config\FontVariables())->getDefaults();
// Note that Mpdf config uses lower-case fontdata
// even though it uses camel-case fontDir.
$fontdata = $defaultFontConfig['fontdata'];
$fontFile = 'ShadowsIntoLight-Regular.ttf';
$config['fontdata'] = $fontdata + [ // lowercase letters only in font key
'shadowsintolight' => [
'R' => $fontFile,
],
];
return new \Mpdf\Mpdf($config);
}
}
================================================
FILE: samples/templates/ShadowsIntoLight.OFL.txt
================================================
Copyright (c) 2010, Kimberly Geswein (kimberlygeswein.com)
This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL
-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.
The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.
DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.
"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).
"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).
"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.
"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.
PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:
1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.
2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.
3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.
5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.
TERMINATION
This license becomes null and void if any of the above conditions are
not met.
DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.
================================================
FILE: samples/templates/SylkTest.slk
================================================
ID;PWXL;N;E
P;PGeneral
P;P0
P;P0.00
P;P#,##0
P;P#,##0.00
P;P#,##0;;\-#,##0
P;P#,##0;;[Red]\-#,##0
P;P#,##0.00;;\-#,##0.00
P;P#,##0.00;;[Red]\-#,##0.00
P;P"$"#,##0;;\-"$"#,##0
P;P"$"#,##0;;[Red]\-"$"#,##0
P;P"$"#,##0.00;;\-"$"#,##0.00
P;P"$"#,##0.00;;[Red]\-"$"#,##0.00
P;P0%
P;P0.00%
P;P0.00E+00
P;P##0.0E+0
P;P#\ ?/?
P;P#\ ??/??
P;Pdd/mm/yyyy
P;Pdd\-mmm\-yy
P;Pdd\-mmm
P;Pmmm\-yy
P;Ph:mm\ AM/PM
P;Ph:mm:ss\ AM/PM
P;Phh:mm
P;Phh:mm:ss
P;Pdd/mm/yyyy\ hh:mm
P;Pmm:ss
P;Pmm:ss.0
P;P@
P;P[h]:mm:ss
P;P_-"$"* #,##0_-;;\-"$"* #,##0_-;;_-"$"* "-"_-;;_-@_-
P;P_-* #,##0_-;;\-* #,##0_-;;_-* "-"_-;;_-@_-
P;P_-"$"* #,##0.00_-;;\-"$"* #,##0.00_-;;_-"$"* "-"??_-;;_-@_-
P;P_-* #,##0.00_-;;\-* #,##0.00_-;;_-* "-"??_-;;_-@_-
P;FArial;M200
P;FArial;M200
P;FArial;M200
P;FArial;M200
P;EArial;M200
P;EArial;M200
P;EArial;M200
P;EArial;M200;SB
P;EArial;M200;SBI
P;EArial;M200;SI
P;EArial;M200;SU
P;EArial;M200;L11
P;EArial;M200;SB
P;EArial;M200
P;EArial;M200;SI
P;EArial;M200;SBI
P;EArial;M200;SBU
P;EArial;M220;SBIU
P;EArial;M200
P;EArial;M200;SI
F;P0;DG0G8;M255
B;Y18;X10;D0 0 17 9
O;L;D;V0;K47;G100 0.001
F;W1 1 17
F;W4 6 6
F;M270;R9
F;M270;R12
F;M270;R17
F;M270;R18
F;SM12;Y1;X1
C;K"Test String 1"
F;SM19;X2
C;K1
F;SM19;X3
C;K5
F;SIDM18;X5
C;K"A"
F;SDM17;X6
C;K"E"
C;X8;K6;ERC[-6]+RC[-5]
C;X10;K"AE";ERC[-5]&RC[-4]
F;SSM0;Y2;X1
C;K"Test - String 2"
C;X2;K2
F;SM19;X3
C;K6
C;X5;K"B"
C;X6;K"F"
C;X8;K8;ERC[-6]+RC[-5]
C;X10;K"BF";ERC[-5]&RC[-4]
C;Y3;X1;K"Test #3"
F;SM19;X2
C;K3
F;SM19;X3
C;K7
F;SDM13;X5
C;K"C"
F;SIDM16;X6
C;K"G"
C;X8;K10;ERC[-6]+RC[-5]
C;X10;K"CG";ERC[-5]&RC[-4]
F;SM11;Y4;X1
C;K"Test with (;;) in string"
C;X2;K4
F;SM19;X3
C;K8
F;SIM15;X5
C;K"D"
C;X6;K"H"
C;X8;K12;ERC[-6]+RC[-5]
C;X10;K"DH";ERC[-5]&RC[-4]
C;Y5;X8;K10;ESUM(R[-4]C[-6]:R[-1]C[-6])
C;X9;K26;ESUM(R[-4]C[-6]:R[-1]C[-6])
C;X10;K36;ESUM(R[-4]C[-8]:R[-1]C[-7])
C;Y6;X2;K1.23
C;X3;KTRUE
F;P19;FG0G;X4
C;Y7;X2;K2.34
C;X3;KFALSE
C;Y8;X2;K3.45
C;Y9;X2;K2.34;EMEDIAN(R[-3]C:R[-1]C)
F;Y9;X1
F;X2
F;X3
F;X4
F;X5
F;X6
F;X7
F;X8
F;X9
F;X10
F;P19;FG0G;Y10;X1
C;K22269
F;STM0;X3
C;K"TOP"
F;P17;FG0G;Y11;X1
C;K1.5
F;Y12
F;X2
F;SBM0;X3
C;K"BOTTOM"
F;X4
F;X5
F;X6
F;X7
F;X8
F;X9
F;X10
F;SLM0;Y14;X3
C;K"LEFT"
F;SRM0;Y16
C;K"RIGHT"
F;Y17
F;SLRTBM0;Y18
C;K"BOX"
E
================================================
FILE: samples/templates/chartSpreadsheet.php
================================================
getActiveSheet();
$worksheet->fromArray(
[
['', 2010, 2011, 2012],
['Q1', 12, 15, 21],
['Q2', 56, 73, 86],
['Q3', 52, 61, 69],
['Q4', 30, 32, 0],
]
);
// Set the Labels for each data series we want to plot
// Datatype
// Cell reference for data
// Format Code
// Number of datapoints in series
// Data values
// Data Marker
$dataSeriesLabels = [
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_STRING, 'Worksheet!$B$1', null, 1), // 2010
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_STRING, 'Worksheet!$C$1', null, 1), // 2011
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_STRING, 'Worksheet!$D$1', null, 1), // 2012
];
// Set the X-Axis Labels
// Datatype
// Cell reference for data
// Format Code
// Number of datapoints in series
// Data values
// Data Marker
$xAxisTickValues = [
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_STRING, 'Worksheet!$A$2:$A$5', null, 4), // Q1 to Q4
];
// Set the Data values for each data series we want to plot
// Datatype
// Cell reference for data
// Format Code
// Number of datapoints in series
// Data values
// Data Marker
$dataSeriesValues = [
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_NUMBER, 'Worksheet!$B$2:$B$5', null, 4),
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_NUMBER, 'Worksheet!$C$2:$C$5', null, 4),
new DataSeriesValues(DataSeriesValues::DATASERIES_TYPE_NUMBER, 'Worksheet!$D$2:$D$5', null, 4),
];
// Build the dataseries
$series = new DataSeries(
DataSeries::TYPE_BARCHART, // plotType
DataSeries::GROUPING_CLUSTERED, // plotGrouping
range(0, count($dataSeriesValues) - 1), // plotOrder
$dataSeriesLabels, // plotLabel
$xAxisTickValues, // plotCategory
$dataSeriesValues // plotValues
);
// Set additional dataseries parameters
// Make it a horizontal bar rather than a vertical column graph
$series->setPlotDirection(DataSeries::DIRECTION_BAR);
// Set the series in the plot area
$plotArea = new PlotArea(null, [$series]);
// Set the chart legend
$legend = new ChartLegend(ChartLegend::POSITION_RIGHT, null, false);
$title = new Title('Test Bar Chart');
$yAxisLabel = new Title('Value ($k)');
// Create the chart
$chart = new Chart(
'chart1', // name
$title, // title
$legend, // legend
$plotArea, // plotArea
true, // plotVisibleOnly
DataSeries::EMPTY_AS_GAP, // displayBlanksAs
null, // xAxisLabel
$yAxisLabel // yAxisLabel
);
// Set the position where the chart should appear in the worksheet
$chart->setTopLeftPosition('A7');
$chart->setBottomRightPosition('H20');
// Add the chart to the worksheet
$worksheet->addChart($chart);
/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
$helper->renderChart($chart, __FILE__);
return $spreadsheet;
================================================
FILE: samples/templates/excel2003.short.bad.xml
================================================
3
#000000
9000
13860
240
75
False
False
================================================
FILE: samples/templates/excel2003.xml
================================================
Xml2003 Workbook
Test Gnumeric Workbook Subject
Mark Baker
PHPExcel Xml Reader Test Keywords
Some comments about the PHPExcel Gnumeric Reader
Owen Leibman
2010-09-02T20:48:39Z
2010-09-03T21:48:39Z
PHPExcel Xml Reader Test Category
Maarten Balliauw
PHPExcel
https://github.com/PHPOffice/PhpSpreadsheet
16.00
AbCd1234
2019-01-31T07:00:00Z
1
3
2
3.14159
8964
23040
32767
32767
False
False
600
600
3
3
18
10
False
False
600
600
3
8
R1C9:R15C11
False
False
================================================
FILE: samples/templates/largeSpreadsheet.php
================================================
log('Create new Spreadsheet object');
$spreadsheet = new Spreadsheet();
// Set document properties
$helper->log('Set properties');
$spreadsheet->getProperties()->setCreator('Maarten Balliauw')
->setLastModifiedBy('Maarten Balliauw')
->setTitle('Office 2007 XLSX Test Document')
->setSubject('Office 2007 XLSX Test Document')
->setDescription('Test document for Office 2007 XLSX, generated using PHP classes.')
->setKeywords('office 2007 openxml php')
->setCategory('Test result file');
// Create a first sheet
$helper->log('Add data');
$spreadsheet->setActiveSheetIndex(0);
$spreadsheet->getActiveSheet()->setCellValue('A1', 'Firstname');
$spreadsheet->getActiveSheet()->setCellValue('B1', 'Lastname');
$spreadsheet->getActiveSheet()->setCellValue('C1', 'Phone');
$spreadsheet->getActiveSheet()->setCellValue('D1', 'Fax');
$spreadsheet->getActiveSheet()->setCellValue('E1', 'Is Client ?');
// Hide "Phone" and "fax" column
$helper->log("Hide 'Phone' and 'fax' columns");
$spreadsheet->getActiveSheet()->getColumnDimension('C')->setVisible(false);
$spreadsheet->getActiveSheet()->getColumnDimension('D')->setVisible(false);
// Set outline levels
$helper->log('Set outline levels');
$spreadsheet->getActiveSheet()->getColumnDimension('E')->setOutlineLevel(1)
->setVisible(false)
->setCollapsed(true);
// Freeze panes
$helper->log('Freeze panes');
$spreadsheet->getActiveSheet()->freezePane('A2');
// Rows to repeat at top
$helper->log('Rows to repeat at top');
$spreadsheet->getActiveSheet()->getPageSetup()->setRowsToRepeatAtTopByStartAndEnd(1, 1);
// Add data
for ($i = 2; $i <= 5000; ++$i) {
$spreadsheet->getActiveSheet()->setCellValue('A' . $i, "FName $i")
->setCellValue('B' . $i, "LName $i")
->setCellValue('C' . $i, "PhoneNo $i")
->setCellValue('D' . $i, "FaxNo $i")
->setCellValue('E' . $i, true);
}
return $spreadsheet;
================================================
FILE: samples/templates/sampleSpreadsheet.php
================================================
log('Create new Spreadsheet object');
$spreadsheet = new Spreadsheet();
// Set document properties
$helper->log('Set document properties');
$spreadsheet->getProperties()->setCreator('Maarten Balliauw')
->setLastModifiedBy('Maarten Balliauw')
->setTitle('Office 2007 XLSX Test Document')
->setSubject('Office 2007 XLSX Test Document')
->setDescription('Test document for Office 2007 XLSX, generated using PHP classes.')
->setKeywords('office 2007 openxml php')
->setCategory('Test result file');
// Create a first sheet, representing sales data
$helper->log('Add some data');
$spreadsheet->setActiveSheetIndex(0);
$spreadsheet->getActiveSheet()->setCellValue('B1', 'Invoice');
$date = new DateTime('now');
$date->setTime(0, 0, 0);
$spreadsheet->getActiveSheet()->setCellValue('D1', Date::PHPToExcel($date));
$spreadsheet->getActiveSheet()->getStyle('D1')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_DATE_XLSX15);
$spreadsheet->getActiveSheet()->setCellValue('E1', '#12566');
$spreadsheet->getActiveSheet()->setCellValue('A3', 'Product Id');
$spreadsheet->getActiveSheet()->setCellValue('B3', 'Description');
$spreadsheet->getActiveSheet()->setCellValue('C3', 'Price');
$spreadsheet->getActiveSheet()->setCellValue('D3', 'Amount');
$spreadsheet->getActiveSheet()->setCellValue('E3', 'Total');
$spreadsheet->getActiveSheet()->setCellValue('A4', '1001');
$spreadsheet->getActiveSheet()->setCellValue('B4', 'PHP for dummies');
$spreadsheet->getActiveSheet()->setCellValue('C4', '20');
$spreadsheet->getActiveSheet()->setCellValue('D4', '1');
$spreadsheet->getActiveSheet()->setCellValue('E4', '=IF(D4<>"",C4*D4,"")');
$spreadsheet->getActiveSheet()->setCellValue('A5', '1012');
$spreadsheet->getActiveSheet()->setCellValue('B5', 'OpenXML for dummies');
$spreadsheet->getActiveSheet()->setCellValue('C5', '22');
$spreadsheet->getActiveSheet()->setCellValue('D5', '2');
$spreadsheet->getActiveSheet()->setCellValue('E5', '=IF(D5<>"",C5*D5,"")');
$spreadsheet->getActiveSheet()->setCellValue('E6', '=IF(D6<>"",C6*D6,"")');
$spreadsheet->getActiveSheet()->setCellValue('E7', '=IF(D7<>"",C7*D7,"")');
$spreadsheet->getActiveSheet()->setCellValue('E8', '=IF(D8<>"",C8*D8,"")');
$spreadsheet->getActiveSheet()->setCellValue('E9', '=IF(D9<>"",C9*D9,"")');
$spreadsheet->getActiveSheet()->setCellValue('D11', 'Total excl.:');
$spreadsheet->getActiveSheet()->setCellValue('E11', '=SUM(E4:E9)');
$spreadsheet->getActiveSheet()->setCellValue('D12', 'VAT:');
$spreadsheet->getActiveSheet()->setCellValue('E12', '=E11*0.21');
$spreadsheet->getActiveSheet()->setCellValue('D13', 'Total incl.:');
$spreadsheet->getActiveSheet()->setCellValue('E13', '=E11+E12');
// Add comment
$helper->log('Add comments');
$spreadsheet->getActiveSheet()->getComment('E11')->setAuthor('PhpSpreadsheet');
$commentRichText = $spreadsheet->getActiveSheet()->getComment('E11')->getText()->createTextRun('PhpSpreadsheet:');
$commentRichText->getFontOrThrow()->setBold(true);
$spreadsheet->getActiveSheet()->getComment('E11')->getText()->createTextRun("\r\n");
$spreadsheet->getActiveSheet()->getComment('E11')->getText()->createTextRun('Total amount on the current invoice, excluding VAT.');
$spreadsheet->getActiveSheet()->getComment('E12')->setAuthor('PhpSpreadsheet');
$commentRichText = $spreadsheet->getActiveSheet()->getComment('E12')->getText()->createTextRun('PhpSpreadsheet:');
$commentRichText->getFontOrThrow()->setBold(true);
$spreadsheet->getActiveSheet()->getComment('E12')->getText()->createTextRun("\r\n");
$spreadsheet->getActiveSheet()->getComment('E12')->getText()->createTextRun('Total amount of VAT on the current invoice.');
$spreadsheet->getActiveSheet()->getComment('E13')->setAuthor('PhpSpreadsheet');
$commentRichText = $spreadsheet->getActiveSheet()->getComment('E13')->getText()->createTextRun('PhpSpreadsheet:');
$commentRichText->getFontOrThrow()->setBold(true);
$spreadsheet->getActiveSheet()->getComment('E13')->getText()->createTextRun("\r\n");
$spreadsheet->getActiveSheet()->getComment('E13')->getText()->createTextRun('Total amount on the current invoice, including VAT.');
$spreadsheet->getActiveSheet()->getComment('E13')->setWidth('100pt');
$spreadsheet->getActiveSheet()->getComment('E13')->setHeight('100pt');
$spreadsheet->getActiveSheet()->getComment('E13')->setMarginLeft('150pt');
$spreadsheet->getActiveSheet()->getComment('E13')->getFillColor()->setRGB('EEEEEE');
// Add rich-text string
$helper->log('Add rich-text string');
$richText = new RichText();
$richText->createText('This invoice is ');
$payable = $richText->createTextRun('payable within thirty days after the end of the month');
$payable->getFontOrThrow()->setBold(true);
$payable->getFontOrThrow()->setItalic(true);
$payable->getFontOrThrow()->setColor(new Color(Color::COLOR_DARKGREEN));
$richText->createText(', unless specified otherwise on the invoice.');
$spreadsheet->getActiveSheet()->getCell('A18')->setValue($richText);
// Merge cells
$helper->log('Merge cells');
$spreadsheet->getActiveSheet()->mergeCells('A18:E22');
$spreadsheet->getActiveSheet()->mergeCells('A28:B28'); // Just to test...
$spreadsheet->getActiveSheet()->unmergeCells('A28:B28'); // Just to test...
// Protect cells
$helper->log('Protect cells');
$spreadsheet->getActiveSheet()->getProtection()->setSheet(true); // Needs to be set to true in order to enable any worksheet protection!
$spreadsheet->getActiveSheet()->protectCells('A3:E13', 'PhpSpreadsheet');
// Set cell number formats
$helper->log('Set cell number formats');
$spreadsheet->getActiveSheet()->getStyle('E4:E13')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_CURRENCY_EUR_INTEGER);
// Set column widths
$helper->log('Set column widths');
$spreadsheet->getActiveSheet()->getColumnDimension('B')->setAutoSize(true);
$spreadsheet->getActiveSheet()->getColumnDimension('D')->setWidth(12);
$spreadsheet->getActiveSheet()->getColumnDimension('E')->setWidth(12);
// Set fonts
$helper->log('Set fonts');
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setName('Candara');
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setSize(20);
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setBold(true);
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setUnderline(Font::UNDERLINE_SINGLE);
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->getColor()->setARGB(Color::COLOR_WHITE);
$spreadsheet->getActiveSheet()->getStyle('D1')->getFont()->getColor()->setARGB(Color::COLOR_WHITE);
$spreadsheet->getActiveSheet()->getStyle('E1')->getFont()->getColor()->setARGB(Color::COLOR_WHITE);
$spreadsheet->getActiveSheet()->getStyle('D13')->getFont()->setBold(true);
$spreadsheet->getActiveSheet()->getStyle('E13')->getFont()->setBold(true);
// Set alignments
$helper->log('Set alignments');
$spreadsheet->getActiveSheet()->getStyle('D11')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('D12')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('D13')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('A18')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_JUSTIFY);
$spreadsheet->getActiveSheet()->getStyle('A18')->getAlignment()->setVertical(Alignment::VERTICAL_CENTER);
$spreadsheet->getActiveSheet()->getStyle('B5')->getAlignment()->setShrinkToFit(true);
// Set thin black border outline around column
$helper->log('Set thin black border outline around column');
$styleThinBlackBorderOutline = [
'borders' => [
'outline' => [
'borderStyle' => Border::BORDER_THIN,
'color' => ['argb' => 'FF000000'],
],
],
];
$spreadsheet->getActiveSheet()->getStyle('A4:E10')->applyFromArray($styleThinBlackBorderOutline);
// Set thick brown border outline around "Total"
$helper->log('Set thick brown border outline around Total');
$styleThickBrownBorderOutline = [
'borders' => [
'outline' => [
'borderStyle' => Border::BORDER_THICK,
'color' => ['argb' => 'FF993300'],
],
],
];
$spreadsheet->getActiveSheet()->getStyle('D13:E13')->applyFromArray($styleThickBrownBorderOutline);
// Set fills
$helper->log('Set fills');
$spreadsheet->getActiveSheet()->getStyle('A1:E1')->getFill()->setFillType(Fill::FILL_SOLID);
$spreadsheet->getActiveSheet()->getStyle('A1:E1')->getFill()->getStartColor()->setARGB('FF808080');
// Set style for header row using alternative method
$helper->log('Set style for header row using alternative method');
$spreadsheet->getActiveSheet()->getStyle('A3:E3')->applyFromArray(
[
'font' => [
'bold' => true,
],
'alignment' => [
'horizontal' => Alignment::HORIZONTAL_RIGHT,
],
'borders' => [
'top' => [
'borderStyle' => Border::BORDER_THIN,
],
],
'fill' => [
'fillType' => Fill::FILL_GRADIENT_LINEAR,
'rotation' => 90,
'startColor' => [
'argb' => 'FFA0A0A0',
],
'endColor' => [
'argb' => 'FFFFFFFF',
],
],
]
);
$spreadsheet->getActiveSheet()->getStyle('A3')->applyFromArray(
[
'alignment' => [
'horizontal' => Alignment::HORIZONTAL_LEFT,
],
'borders' => [
'left' => [
'borderStyle' => Border::BORDER_THIN,
],
],
]
);
$spreadsheet->getActiveSheet()->getStyle('B3')->applyFromArray(
[
'alignment' => [
'horizontal' => Alignment::HORIZONTAL_LEFT,
],
]
);
$spreadsheet->getActiveSheet()->getStyle('E3')->applyFromArray(
[
'borders' => [
'right' => [
'borderStyle' => Border::BORDER_THIN,
],
],
]
);
// Unprotect a cell
$helper->log('Unprotect a cell');
$spreadsheet->getActiveSheet()->getStyle('B1')->getProtection()->setLocked(Protection::PROTECTION_UNPROTECTED);
// Add a hyperlink to the sheet
$helper->log('Add a hyperlink to an external website');
$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.example.com');
$spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setUrl('https://www.example.com');
$spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setTooltip('Navigate to website');
$spreadsheet->getActiveSheet()->getStyle('E26')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('E26')->getFont()->setHyperlinkTheme();
$helper->log('Add a hyperlink to another cell on a different worksheet within the workbook');
$spreadsheet->getActiveSheet()->setCellValue('E27', 'Terms and conditions');
$spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setUrl("sheet://'Terms and conditions'!A1");
$spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setTooltip('Review terms and conditions');
$spreadsheet->getActiveSheet()->getStyle('E27')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('E27')->getFont()->setHyperlinkTheme();
// Add a drawing to the worksheet
$helper->log('Add a drawing to the worksheet');
$drawing = new Drawing();
$drawing->setName('Logo');
$drawing->setDescription('Logo');
$drawing->setPath(__DIR__ . '/../images/officelogo.jpg');
$drawing->setHeight(36);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Add a drawing to the worksheet
$helper->log('Add a drawing to the worksheet');
$drawing = new Drawing();
$drawing->setName('Paid');
$drawing->setDescription('Paid');
$drawing->setPath(__DIR__ . '/../images/paid.png');
$drawing->setCoordinates('B15');
$drawing->setOffsetX(110);
$drawing->setRotation(25);
$drawing->getShadow()->setVisible(true);
$drawing->getShadow()->setDirection(45);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Add a drawing to the worksheet
$helper->log('Add a drawing to the worksheet');
$drawing = new Drawing();
$drawing->setName('PhpSpreadsheet logo');
$drawing->setDescription('PhpSpreadsheet logo');
$drawing->setPath(__DIR__ . '/../images/PhpSpreadsheet_logo.png');
$drawing->setHeight(36);
$drawing->setCoordinates('D24');
$drawing->setOffsetX(10);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Play around with inserting and removing rows and columns
$helper->log('Play around with inserting and removing rows and columns');
$spreadsheet->getActiveSheet()->insertNewRowBefore(6, 10);
$spreadsheet->getActiveSheet()->removeRow(6, 10);
$spreadsheet->getActiveSheet()->insertNewColumnBefore('E', 5);
$spreadsheet->getActiveSheet()->removeColumn('E', 5);
// Set header and footer. When no different headers for odd/even are used, odd header is assumed.
$helper->log('Set header/footer');
$spreadsheet->getActiveSheet()->getHeaderFooter()->setOddHeader('&L&BInvoice&RPrinted on &D');
$spreadsheet->getActiveSheet()->getHeaderFooter()->setOddFooter('&L&B' . $spreadsheet->getProperties()->getTitle() . '&RPage &P of &N');
// Set page orientation and size
$helper->log('Set page orientation and size');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_PORTRAIT);
$spreadsheet->getActiveSheet()->getPageSetup()->setPaperSize(PageSetup::PAPERSIZE_A4);
// Rename first worksheet
$helper->log('Rename first worksheet');
$spreadsheet->getActiveSheet()->setTitle('Invoice');
// Create a new worksheet, after the default sheet
$helper->log('Create a second Worksheet object');
$spreadsheet->createSheet();
// Llorem ipsum...
$sLloremIpsum = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vivamus eget ante. Sed cursus nunc semper tortor. Aliquam luctus purus non elit. Fusce vel elit commodo sapien dignissim dignissim. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Curabitur accumsan magna sed massa. Nullam bibendum quam ac ipsum. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin augue. Praesent malesuada justo sed orci. Pellentesque lacus ligula, sodales quis, ultricies a, ultricies vitae, elit. Sed luctus consectetuer dolor. Vivamus vel sem ut nisi sodales accumsan. Nunc et felis. Suspendisse semper viverra odio. Morbi at odio. Integer a orci a purus venenatis molestie. Nam mattis. Praesent rhoncus, nisi vel mattis auctor, neque nisi faucibus sem, non dapibus elit pede ac nisl. Cras turpis.';
// Add some data to the second sheet, resembling some different data types
$helper->log('Add some data');
$spreadsheet->setActiveSheetIndex(1);
$spreadsheet->getActiveSheet()->setCellValue('A1', 'Terms and conditions');
$spreadsheet->getActiveSheet()->setCellValue('A3', $sLloremIpsum);
$spreadsheet->getActiveSheet()->setCellValue('A4', $sLloremIpsum);
$spreadsheet->getActiveSheet()->setCellValue('A5', $sLloremIpsum);
$spreadsheet->getActiveSheet()->setCellValue('A6', $sLloremIpsum);
// Set the worksheet tab color
$helper->log('Set the worksheet tab color');
$spreadsheet->getActiveSheet()->getTabColor()->setARGB('FF0094FF');
// Set alignments
$helper->log('Set alignments');
$spreadsheet->getActiveSheet()->getStyle('A3:A6')->getAlignment()->setWrapText(true);
// Set column widths
$helper->log('Set column widths');
$spreadsheet->getActiveSheet()->getColumnDimension('A')->setWidth(80);
// Set fonts
$helper->log('Set fonts');
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setName('Candara');
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setSize(20);
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setBold(true);
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setUnderline(Font::UNDERLINE_SINGLE);
$spreadsheet->getActiveSheet()->getStyle('A3:A6')->getFont()->setSize(8);
// Add a drawing to the worksheet
$helper->log('Add a drawing to the worksheet');
$drawing = new Drawing();
$drawing->setName('Terms and conditions');
$drawing->setDescription('Terms and conditions');
$drawing->setPath(__DIR__ . '/../images/termsconditions.jpg');
$drawing->setCoordinates('B14');
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Set page orientation and size
$helper->log('Set page orientation and size');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE);
$spreadsheet->getActiveSheet()->getPageSetup()->setPaperSize(PageSetup::PAPERSIZE_A4);
// Rename second worksheet
$helper->log('Rename second worksheet');
$spreadsheet->getActiveSheet()->setTitle('Terms and conditions');
// Set active sheet index to the first sheet, so Excel opens this as the first sheet
$spreadsheet->setActiveSheetIndex(0);
return $spreadsheet;
================================================
FILE: samples/templates/sampleSpreadsheet2.php
================================================
log('Create new Spreadsheet object');
$spreadsheet = new Spreadsheet();
// Set document properties
$helper->log('Set document properties');
$spreadsheet->getProperties()->setCreator('Maarten Balliauw')
->setLastModifiedBy('Maarten Balliauw')
->setTitle('Office 2007 XLSX Test Document')
->setSubject('Office 2007 XLSX Test Document')
->setDescription('Test document for Office 2007 XLSX, generated using PHP classes.')
->setKeywords('office 2007 openxml php')
->setCategory('Test result file');
// Create a first sheet, representing sales data
$helper->log('Add some data');
$spreadsheet->setActiveSheetIndex(0);
$spreadsheet->getActiveSheet()->setCellValue('B1', 'Invoice');
$date = new DateTime('now');
$date->setTime(0, 0, 0);
$spreadsheet->getActiveSheet()->setCellValue('D1', Date::PHPToExcel($date));
$spreadsheet->getActiveSheet()->getStyle('D1')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_DATE_XLSX15);
$spreadsheet->getActiveSheet()->setCellValue('E1', '#12566');
$spreadsheet->getActiveSheet()->setCellValue('A3', 'Product Id');
$spreadsheet->getActiveSheet()->setCellValue('B3', 'Description');
$spreadsheet->getActiveSheet()->setCellValue('C3', 'Price');
$spreadsheet->getActiveSheet()->setCellValue('D3', 'Amount');
$spreadsheet->getActiveSheet()->setCellValue('E3', 'Total');
$spreadsheet->getActiveSheet()->setCellValue('A4', '1001');
$spreadsheet->getActiveSheet()->setCellValue('B4', 'PHP for dummies');
$spreadsheet->getActiveSheet()->setCellValue('C4', '20');
$spreadsheet->getActiveSheet()->setCellValue('D4', '1');
$spreadsheet->getActiveSheet()->setCellValue('E4', '=IF(D4<>"",C4*D4,"")');
$spreadsheet->getActiveSheet()->setCellValue('A5', '1012');
$spreadsheet->getActiveSheet()->setCellValue('B5', 'OpenXML for dummies');
$spreadsheet->getActiveSheet()->setCellValue('C5', '22');
$spreadsheet->getActiveSheet()->setCellValue('D5', '2');
$spreadsheet->getActiveSheet()->setCellValue('E5', '=IF(D5<>"",C5*D5,"")');
$spreadsheet->getActiveSheet()->setCellValue('E6', '=IF(D6<>"",C6*D6,"")');
$spreadsheet->getActiveSheet()->setCellValue('E7', '=IF(D7<>"",C7*D7,"")');
$spreadsheet->getActiveSheet()->setCellValue('E8', '=IF(D8<>"",C8*D8,"")');
$spreadsheet->getActiveSheet()->setCellValue('E9', '=IF(D9<>"",C9*D9,"")');
$spreadsheet->getActiveSheet()->setCellValue('D11', 'Total excl.:');
$spreadsheet->getActiveSheet()->setCellValue('E11', '=SUM(E4:E9)');
$spreadsheet->getActiveSheet()->setCellValue('D12', 'VAT:');
$spreadsheet->getActiveSheet()->setCellValue('E12', '=E11*0.21');
$spreadsheet->getActiveSheet()->setCellValue('D13', 'Total incl.:');
$spreadsheet->getActiveSheet()->setCellValue('E13', '=E11+E12');
// Add comment
$helper->log('Add comments');
$spreadsheet->getActiveSheet()->getComment('E11')->setAuthor('PhpSpreadsheet');
$commentRichText = $spreadsheet->getActiveSheet()->getComment('E11')->getText()->createTextRun('PhpSpreadsheet:');
$commentRichText->getFontOrThrow()->setBold(true);
$spreadsheet->getActiveSheet()->getComment('E11')->getText()->createTextRun("\r\n");
$spreadsheet->getActiveSheet()->getComment('E11')->getText()->createTextRun('Total amount on the current invoice, excluding VAT.');
$spreadsheet->getActiveSheet()->getComment('E12')->setAuthor('PhpSpreadsheet');
$commentRichText = $spreadsheet->getActiveSheet()->getComment('E12')->getText()->createTextRun('PhpSpreadsheet:');
$commentRichText->getFontOrThrow()->setBold(true);
$spreadsheet->getActiveSheet()->getComment('E12')->getText()->createTextRun("\r\n");
$spreadsheet->getActiveSheet()->getComment('E12')->getText()->createTextRun('Total amount of VAT on the current invoice.');
$spreadsheet->getActiveSheet()->getComment('E13')->setAuthor('PhpSpreadsheet');
$commentRichText = $spreadsheet->getActiveSheet()->getComment('E13')->getText()->createTextRun('PhpSpreadsheet:');
$commentRichText->getFontOrThrow()->setBold(true);
$spreadsheet->getActiveSheet()->getComment('E13')->getText()->createTextRun("\r\n");
$spreadsheet->getActiveSheet()->getComment('E13')->getText()->createTextRun('Total amount on the current invoice, including VAT.');
$spreadsheet->getActiveSheet()->getComment('E13')->setWidth('100pt');
$spreadsheet->getActiveSheet()->getComment('E13')->setHeight('100pt');
$spreadsheet->getActiveSheet()->getComment('E13')->setMarginLeft('150pt');
$spreadsheet->getActiveSheet()->getComment('E13')->getFillColor()->setRGB('EEEEEE');
// Add rich-text string
$helper->log('Add rich-text string');
$richText = new RichText();
$richText->createText('This invoice is ');
$payable = $richText->createTextRun('payable within thirty days after the end of the month');
$payable->getFontOrThrow()->setBold(true);
$payable->getFontOrThrow()->setItalic(true);
$payable->getFontOrThrow()->setColor(new Color(Color::COLOR_DARKGREEN));
$richText->createText(', unless specified otherwise on the invoice.');
$spreadsheet->getActiveSheet()->getCell('A18')->setValue($richText);
// Merge cells
$helper->log('Merge cells');
$spreadsheet->getActiveSheet()->mergeCells('A18:E22');
$spreadsheet->getActiveSheet()->mergeCells('A28:B28'); // Just to test...
$spreadsheet->getActiveSheet()->unmergeCells('A28:B28'); // Just to test...
// Protect cells
$helper->log('Protect cells');
$spreadsheet->getActiveSheet()->getProtection()->setSheet(true); // Needs to be set to true in order to enable any worksheet protection!
$spreadsheet->getActiveSheet()->protectCells('A3:E13', 'PhpSpreadsheet');
// Set cell number formats
$helper->log('Set cell number formats');
$spreadsheet->getActiveSheet()->getStyle('E4:E13')->getNumberFormat()->setFormatCode(NumberFormat::FORMAT_CURRENCY_EUR_INTEGER);
// Set column widths
$helper->log('Set column widths');
$spreadsheet->getActiveSheet()->getColumnDimension('B')->setAutoSize(true);
$spreadsheet->getActiveSheet()->getColumnDimension('D')->setWidth(12);
$spreadsheet->getActiveSheet()->getColumnDimension('E')->setWidth(12);
// Set fonts
$helper->log('Set fonts');
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setName('Candara');
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setSize(20);
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setBold(true);
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->setUnderline(Font::UNDERLINE_SINGLE);
$spreadsheet->getActiveSheet()->getStyle('B1')->getFont()->getColor()->setARGB(Color::COLOR_WHITE);
$spreadsheet->getActiveSheet()->getStyle('D1')->getFont()->getColor()->setARGB(Color::COLOR_WHITE);
$spreadsheet->getActiveSheet()->getStyle('E1')->getFont()->getColor()->setARGB(Color::COLOR_WHITE);
$spreadsheet->getActiveSheet()->getStyle('D13')->getFont()->setBold(true);
$spreadsheet->getActiveSheet()->getStyle('E13')->getFont()->setBold(true);
// Set alignments
$helper->log('Set alignments');
$spreadsheet->getActiveSheet()->getStyle('D11')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('D12')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('D13')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('A18')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_JUSTIFY);
$spreadsheet->getActiveSheet()->getStyle('A18')->getAlignment()->setVertical(Alignment::VERTICAL_CENTER);
$spreadsheet->getActiveSheet()->getStyle('B5')->getAlignment()->setShrinkToFit(true);
// Set thin black border outline around column
$helper->log('Set thin black border outline around column');
$styleThinBlackBorderOutline = [
'borders' => [
'outline' => [
'borderStyle' => Border::BORDER_THIN,
'color' => ['argb' => 'FF000000'],
],
],
];
$spreadsheet->getActiveSheet()->getStyle('A4:E10')->applyFromArray($styleThinBlackBorderOutline);
// Set thick brown border outline around "Total"
$helper->log('Set thick brown border outline around Total');
$styleThickBrownBorderOutline = [
'borders' => [
'outline' => [
'borderStyle' => Border::BORDER_THICK,
'color' => ['argb' => 'FF993300'],
],
],
];
$spreadsheet->getActiveSheet()->getStyle('D13:E13')->applyFromArray($styleThickBrownBorderOutline);
// Set fills
$helper->log('Set fills');
$spreadsheet->getActiveSheet()->getStyle('A1:E1')->getFill()->setFillType(Fill::FILL_SOLID);
$spreadsheet->getActiveSheet()->getStyle('A1:E1')->getFill()->getStartColor()->setARGB('FF808080');
// Set style for header row using alternative method
$helper->log('Set style for header row using alternative method');
$spreadsheet->getActiveSheet()->getStyle('A3:E3')->applyFromArray(
[
'font' => [
'bold' => true,
],
'alignment' => [
'horizontal' => Alignment::HORIZONTAL_RIGHT,
],
'borders' => [
'top' => [
'borderStyle' => Border::BORDER_THIN,
],
],
'fill' => [
'fillType' => Fill::FILL_GRADIENT_LINEAR,
'rotation' => 90,
'startColor' => [
'argb' => 'FFA0A0A0',
],
'endColor' => [
'argb' => 'FFFFFFFF',
],
],
]
);
$spreadsheet->getActiveSheet()->getStyle('A3')->applyFromArray(
[
'alignment' => [
'horizontal' => Alignment::HORIZONTAL_LEFT,
],
'borders' => [
'left' => [
'borderStyle' => Border::BORDER_THIN,
],
],
]
);
$spreadsheet->getActiveSheet()->getStyle('B3')->applyFromArray(
[
'alignment' => [
'horizontal' => Alignment::HORIZONTAL_LEFT,
],
]
);
$spreadsheet->getActiveSheet()->getStyle('E3')->applyFromArray(
[
'borders' => [
'right' => [
'borderStyle' => Border::BORDER_THIN,
],
],
]
);
// Unprotect a cell
$helper->log('Unprotect a cell');
$spreadsheet->getActiveSheet()->getStyle('B1')->getProtection()->setLocked(Protection::PROTECTION_UNPROTECTED);
// Add a hyperlink to the sheet
$helper->log('Add a hyperlink to an external website');
$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.example.com');
$spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setUrl('https://www.example.com');
$spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setTooltip('Navigate to website');
$spreadsheet->getActiveSheet()->getStyle('E26')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('E26')->getFont()->setHyperlinkTheme();
$helper->log('Add a hyperlink to another cell on a different worksheet within the workbook');
$spreadsheet->getActiveSheet()->setCellValue('E27', 'Terms and conditions');
$spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setUrl("sheet://'Terms and conditions'!A1");
$spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setTooltip('Review terms and conditions');
$spreadsheet->getActiveSheet()->getStyle('E27')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
$spreadsheet->getActiveSheet()->getStyle('E27')->getFont()->setHyperlinkTheme();
// Add a drawing to the worksheet
$helper->log('Add a drawing to the worksheet');
$drawing = new Drawing();
$drawing->setName('Logo');
$drawing->setDescription('Logo');
$drawing->setPath(__DIR__ . '/../images/officelogo.jpg');
$drawing->setHeight(36);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Add a drawing to the worksheet
$helper->log('Add a drawing to the worksheet');
$drawing = new Drawing();
$drawing->setName('Paid');
$drawing->setDescription('Paid');
$drawing->setPath(__DIR__ . '/../images/paid.png');
$drawing->setCoordinates('B15');
$drawing->setOffsetX(110);
$drawing->setRotation(25);
$drawing->getShadow()->setVisible(true);
$drawing->getShadow()->setDirection(45);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Add a drawing to the worksheet
$helper->log('Add a drawing with Japanese file name to the worksheet');
$drawing = new Drawing();
$drawing->setName('PhpSpreadsheet logo');
$drawing->setDescription('PhpSpreadsheet logo');
$drawing->setPath(__DIR__ . '/../images/サンプル.png');
$drawing->setHeight(36);
$drawing->setCoordinates('D24');
$drawing->setOffsetX(10);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Play around with inserting and removing rows and columns
$helper->log('Play around with inserting and removing rows and columns');
$spreadsheet->getActiveSheet()->insertNewRowBefore(6, 10);
$spreadsheet->getActiveSheet()->removeRow(6, 10);
$spreadsheet->getActiveSheet()->insertNewColumnBefore('E', 5);
$spreadsheet->getActiveSheet()->removeColumn('E', 5);
// Set header and footer. When no different headers for odd/even are used, odd header is assumed.
$helper->log('Set header/footer');
$spreadsheet->getActiveSheet()->getHeaderFooter()->setOddHeader('&L&BInvoice&RPrinted on &D');
$spreadsheet->getActiveSheet()->getHeaderFooter()->setOddFooter('&L&B' . $spreadsheet->getProperties()->getTitle() . '&RPage &P of &N');
// Set page orientation and size
$helper->log('Set page orientation and size');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_PORTRAIT);
$spreadsheet->getActiveSheet()->getPageSetup()->setPaperSize(PageSetup::PAPERSIZE_A4);
// Rename first worksheet
$helper->log('Rename first worksheet');
$spreadsheet->getActiveSheet()->setTitle('Invoice');
// Create a new worksheet, after the default sheet
$helper->log('Create a second Worksheet object');
$spreadsheet->createSheet();
// Llorem ipsum...
$sLloremIpsum = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vivamus eget ante. Sed cursus nunc semper tortor. Aliquam luctus purus non elit. Fusce vel elit commodo sapien dignissim dignissim. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Curabitur accumsan magna sed massa. Nullam bibendum quam ac ipsum. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin augue. Praesent malesuada justo sed orci. Pellentesque lacus ligula, sodales quis, ultricies a, ultricies vitae, elit. Sed luctus consectetuer dolor. Vivamus vel sem ut nisi sodales accumsan. Nunc et felis. Suspendisse semper viverra odio. Morbi at odio. Integer a orci a purus venenatis molestie. Nam mattis. Praesent rhoncus, nisi vel mattis auctor, neque nisi faucibus sem, non dapibus elit pede ac nisl. Cras turpis.';
// Add some data to the second sheet, resembling some different data types
$helper->log('Add some data');
$spreadsheet->setActiveSheetIndex(1);
$spreadsheet->getActiveSheet()->setCellValue('A1', 'Terms and conditions');
$spreadsheet->getActiveSheet()->setCellValue('A3', $sLloremIpsum);
$spreadsheet->getActiveSheet()->setCellValue('A4', $sLloremIpsum);
$spreadsheet->getActiveSheet()->setCellValue('A5', $sLloremIpsum);
$spreadsheet->getActiveSheet()->setCellValue('A6', $sLloremIpsum);
// Set the worksheet tab color
$helper->log('Set the worksheet tab color');
$spreadsheet->getActiveSheet()->getTabColor()->setARGB('FF0094FF');
// Set alignments
$helper->log('Set alignments');
$spreadsheet->getActiveSheet()->getStyle('A3:A6')->getAlignment()->setWrapText(true);
// Set column widths
$helper->log('Set column widths');
$spreadsheet->getActiveSheet()->getColumnDimension('A')->setWidth(80);
// Set fonts
$helper->log('Set fonts');
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setName('Candara');
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setSize(20);
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setBold(true);
$spreadsheet->getActiveSheet()->getStyle('A1')->getFont()->setUnderline(Font::UNDERLINE_SINGLE);
$spreadsheet->getActiveSheet()->getStyle('A3:A6')->getFont()->setSize(8);
// Add a drawing to the worksheet
$helper->log('Add a drawing with space and # in filename to the worksheet');
$drawing = new Drawing();
$drawing->setName('Terms and conditions');
$drawing->setDescription('Terms and conditions');
$drawing->setPath(__DIR__ . '/../images/terms con#ditions.jpg');
$drawing->setCoordinates('B14');
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Repeat drawing to the worksheet
$helper->log('Repeat drawing from other worksheet on this one');
$drawing = new Drawing();
$drawing->setName('PhpSpreadsheet logo');
$drawing->setDescription('PhpSpreadsheet logo');
$drawing->setPath(__DIR__ . '/../images/サンプル.png');
$drawing->setHeight(36);
$drawing->setCoordinates('B18');
$drawing->setOffsetX(10);
$drawing->setWorksheet($spreadsheet->getActiveSheet());
// Set page orientation and size
$helper->log('Set page orientation and size');
$spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE);
$spreadsheet->getActiveSheet()->getPageSetup()->setPaperSize(PageSetup::PAPERSIZE_A4);
// Rename second worksheet
$helper->log('Rename second worksheet');
$spreadsheet->getActiveSheet()->setTitle('Terms and conditions');
// Set active sheet index to the first sheet, so Excel opens this as the first sheet
$spreadsheet->setActiveSheetIndex(0);
return $spreadsheet;
================================================
FILE: src/PhpSpreadsheet/Calculation/ArrayEnabled.php
================================================
initialise($arguments);
}
/**
* Handles array argument processing when the function accepts a single argument that can be an array argument.
* Example use for:
* DAYOFMONTH() or FACT().
*
* @param mixed[] $values
*
* @return mixed[]
*/
protected static function evaluateSingleArgumentArray(callable $method, array $values): array
{
$result = [];
foreach ($values as $value) {
$result[] = $method($value);
}
return $result;
}
/**
* Handles array argument processing when the function accepts multiple arguments,
* and any of them can be an array argument.
* Example use for:
* ROUND() or DATE().
*
* @return mixed[]
*/
protected static function evaluateArrayArguments(callable $method, mixed ...$arguments): array
{
self::initialiseHelper($arguments);
$arguments = self::$arrayArgumentHelper->arguments();
return ArrayArgumentProcessor::processArguments(self::$arrayArgumentHelper, $method, ...$arguments);
}
/**
* Handles array argument processing when the function accepts multiple arguments,
* but only the first few (up to limit) can be an array arguments.
* Example use for:
* NETWORKDAYS() or CONCATENATE(), where the last argument is a matrix (or a series of values) that need
* to be treated as a such rather than as an array arguments.
*
* @return mixed[]
*/
protected static function evaluateArrayArgumentsSubset(callable $method, int $limit, mixed ...$arguments): array
{
self::initialiseHelper(array_slice($arguments, 0, $limit));
$trailingArguments = array_slice($arguments, $limit);
$arguments = self::$arrayArgumentHelper->arguments();
$arguments = array_merge($arguments, $trailingArguments);
return ArrayArgumentProcessor::processArguments(self::$arrayArgumentHelper, $method, ...$arguments);
}
private static function testFalse(mixed $value): bool
{
return $value === false;
}
/**
* Handles array argument processing when the function accepts multiple arguments,
* but only the last few (from start) can be an array arguments.
* Example use for:
* Z.TEST() or INDEX(), where the first argument 1 is a matrix that needs to be treated as a dataset
* rather than as an array argument.
*
* @return mixed[]
*/
protected static function evaluateArrayArgumentsSubsetFrom(callable $method, int $start, mixed ...$arguments): array
{
$arrayArgumentsSubset = array_combine(
range($start, count($arguments) - $start),
array_slice($arguments, $start)
);
if (self::testFalse($arrayArgumentsSubset)) {
return ['#VALUE!'];
}
self::initialiseHelper($arrayArgumentsSubset);
$leadingArguments = array_slice($arguments, 0, $start);
$arguments = self::$arrayArgumentHelper->arguments();
$arguments = array_merge($leadingArguments, $arguments);
return ArrayArgumentProcessor::processArguments(self::$arrayArgumentHelper, $method, ...$arguments);
}
/**
* Handles array argument processing when the function accepts multiple arguments,
* and any of them can be an array argument except for the one specified by ignore.
* Example use for:
* HLOOKUP() and VLOOKUP(), where argument 1 is a matrix that needs to be treated as a database
* rather than as an array argument.
*
* @return mixed[]
*/
protected static function evaluateArrayArgumentsIgnore(callable $method, int $ignore, mixed ...$arguments): array
{
$leadingArguments = array_slice($arguments, 0, $ignore);
$ignoreArgument = array_slice($arguments, $ignore, 1);
$trailingArguments = array_slice($arguments, $ignore + 1);
self::initialiseHelper(array_merge($leadingArguments, [[null]], $trailingArguments));
$arguments = self::$arrayArgumentHelper->arguments();
array_splice($arguments, $ignore, 1, $ignoreArgument);
return ArrayArgumentProcessor::processArguments(self::$arrayArgumentHelper, $method, ...$arguments);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/BinaryComparison.php
================================================
'' && $operand1[0] == Calculation::FORMULA_STRING_QUOTE) {
$operand1 = Calculation::unwrapResult($operand1);
}
if (ErrorValue::isError($operand1, true)) {
/** @var string $operand1 */
return $operand1;
}
if (is_string($operand2) && $operand2 > '' && $operand2[0] == Calculation::FORMULA_STRING_QUOTE) {
$operand2 = Calculation::unwrapResult($operand2);
}
if (ErrorValue::isError($operand2, true)) {
/** @var string $operand2 */
return $operand2;
}
// Use case-insensitive comparison if not OpenOffice mode
if (Functions::getCompatibilityMode() != Functions::COMPATIBILITY_OPENOFFICE) {
if (is_string($operand1)) {
$operand1 = StringHelper::strToUpper($operand1);
}
if (is_string($operand2)) {
$operand2 = StringHelper::strToUpper($operand2);
}
}
$useLowercaseFirstComparison = is_string($operand1)
&& is_string($operand2)
&& Functions::getCompatibilityMode() === Functions::COMPATIBILITY_OPENOFFICE;
return self::evaluateComparison($operand1, $operand2, $operator, $useLowercaseFirstComparison);
}
private static function evaluateComparison(mixed $operand1, mixed $operand2, string $operator, bool $useLowercaseFirstComparison): bool
{
return match ($operator) {
'=' => self::equal($operand1, $operand2),
'>' => self::greaterThan($operand1, $operand2, $useLowercaseFirstComparison),
'<' => self::lessThan($operand1, $operand2, $useLowercaseFirstComparison),
'>=' => self::greaterThanOrEqual($operand1, $operand2, $useLowercaseFirstComparison),
'<=' => self::lessThanOrEqual($operand1, $operand2, $useLowercaseFirstComparison),
'<>' => self::notEqual($operand1, $operand2),
default => throw new Exception('Unsupported binary comparison operator'),
};
}
private static function equal(mixed $operand1, mixed $operand2): bool
{
if (is_numeric($operand1) && is_numeric($operand2)) {
$result = (abs($operand1 - $operand2) < self::DELTA);
} elseif (($operand1 === null && is_numeric($operand2)) || ($operand2 === null && is_numeric($operand1))) {
$result = $operand1 == $operand2;
} else {
$result = self::strcmpAllowNull($operand1, $operand2) == 0;
}
return $result;
}
private static function greaterThanOrEqual(mixed $operand1, mixed $operand2, bool $useLowercaseFirstComparison): bool
{
if (is_numeric($operand1) && is_numeric($operand2)) {
$result = ((abs($operand1 - $operand2) < self::DELTA) || ($operand1 > $operand2));
} elseif (($operand1 === null && is_numeric($operand2)) || ($operand2 === null && is_numeric($operand1))) {
$result = $operand1 >= $operand2;
} elseif ($useLowercaseFirstComparison) {
$result = self::strcmpLowercaseFirst($operand1, $operand2) >= 0;
} else {
$result = self::strcmpAllowNull($operand1, $operand2) >= 0;
}
return $result;
}
private static function lessThanOrEqual(mixed $operand1, mixed $operand2, bool $useLowercaseFirstComparison): bool
{
if (is_numeric($operand1) && is_numeric($operand2)) {
$result = ((abs($operand1 - $operand2) < self::DELTA) || ($operand1 < $operand2));
} elseif (($operand1 === null && is_numeric($operand2)) || ($operand2 === null && is_numeric($operand1))) {
$result = $operand1 <= $operand2;
} elseif ($useLowercaseFirstComparison) {
$result = self::strcmpLowercaseFirst($operand1, $operand2) <= 0;
} else {
$result = self::strcmpAllowNull($operand1, $operand2) <= 0;
}
return $result;
}
private static function greaterThan(mixed $operand1, mixed $operand2, bool $useLowercaseFirstComparison): bool
{
return self::lessThanOrEqual($operand1, $operand2, $useLowercaseFirstComparison) !== true;
}
private static function lessThan(mixed $operand1, mixed $operand2, bool $useLowercaseFirstComparison): bool
{
return self::greaterThanOrEqual($operand1, $operand2, $useLowercaseFirstComparison) !== true;
}
private static function notEqual(mixed $operand1, mixed $operand2): bool
{
return self::equal($operand1, $operand2) !== true;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Calculation.php
================================================
=:`-]*)|(\'(?:[^\']|\'[^!])+?\')|(\"(?:[^\"]|\"[^!])+?\"))!)?\$?\b([a-z]{1,3})\$?(\d{1,7})(?![\w.])';
// Used only to detect spill operator #
const CALCULATION_REGEXP_CELLREF_SPILL = '/' . self::CALCULATION_REGEXP_CELLREF . '#/i';
// Cell reference (with or without a sheet reference) ensuring absolute/relative
const CALCULATION_REGEXP_CELLREF_RELATIVE = '((([^\s\(,!&%^\/\*\+<>=:`-]*)|(\'(?:[^\']|\'[^!])+?\')|(\"(?:[^\"]|\"[^!])+?\"))!)?(\$?\b[a-z]{1,3})(\$?\d{1,7})(?![\w.])';
const CALCULATION_REGEXP_COLUMN_RANGE = '(((([^\s\(,!&%^\/\*\+<>=:`-]*)|(\'(?:[^\']|\'[^!])+?\')|(\".(?:[^\"]|\"[^!])?\"))!)?(\$?[a-z]{1,3})):(?![.*])';
const CALCULATION_REGEXP_ROW_RANGE = '(((([^\s\(,!&%^\/\*\+<>=:`-]*)|(\'(?:[^\']|\'[^!])+?\')|(\"(?:[^\"]|\"[^!])+?\"))!)?(\$?[1-9][0-9]{0,6})):(?![.*])';
// Cell reference (with or without a sheet reference) ensuring absolute/relative
// Cell ranges ensuring absolute/relative
const CALCULATION_REGEXP_COLUMNRANGE_RELATIVE = '(\$?[a-z]{1,3}):(\$?[a-z]{1,3})';
const CALCULATION_REGEXP_ROWRANGE_RELATIVE = '(\$?\d{1,7}):(\$?\d{1,7})';
// Defined Names: Named Range of cells, or Named Formulae
const CALCULATION_REGEXP_DEFINEDNAME = '((([^\s,!&%^\/\*\+<>=-]*)|(\'(?:[^\']|\'[^!])+?\')|(\"(?:[^\"]|\"[^!])+?\"))!)?([_\p{L}][_\p{L}\p{N}\.]*)';
// Structured Reference (Fully Qualified and Unqualified)
const CALCULATION_REGEXP_STRUCTURED_REFERENCE = '([\p{L}_\\\][\p{L}\p{N}\._]+)?(\[(?:[^\d\]+-])?)';
// Error
const CALCULATION_REGEXP_ERROR = '\#[A-Z][A-Z0_\/]*[!\?]?';
/** constants */
const RETURN_ARRAY_AS_ERROR = 'error';
const RETURN_ARRAY_AS_VALUE = 'value';
const RETURN_ARRAY_AS_ARRAY = 'array';
/** Preferable to use instance variable instanceArrayReturnType rather than this static property. */
private static string $returnArrayAsType = self::RETURN_ARRAY_AS_VALUE;
/** Preferable to use this instance variable rather than static returnArrayAsType */
private ?string $instanceArrayReturnType = null;
/**
* Instance of this class.
*/
private static ?Calculation $instance = null;
/**
* Instance of the spreadsheet this Calculation Engine is using.
*/
private ?Spreadsheet $spreadsheet;
/**
* Calculation cache.
*
* @var mixed[]
*/
private array $calculationCache = [];
/**
* Calculation cache enabled.
*/
private bool $calculationCacheEnabled = true;
private BranchPruner $branchPruner;
protected bool $branchPruningEnabled = true;
/**
* List of operators that can be used within formulae
* The true/false value indicates whether it is a binary operator or a unary operator.
*/
private const CALCULATION_OPERATORS = [
'+' => true, '-' => true, '*' => true, '/' => true,
'^' => true, '&' => true, '%' => false, '~' => false,
'>' => true, '<' => true, '=' => true, '>=' => true,
'<=' => true, '<>' => true, '∩' => true, '∪' => true,
':' => true,
];
/**
* List of binary operators (those that expect two operands).
*/
private const BINARY_OPERATORS = [
'+' => true, '-' => true, '*' => true, '/' => true,
'^' => true, '&' => true, '>' => true, '<' => true,
'=' => true, '>=' => true, '<=' => true, '<>' => true,
'∩' => true, '∪' => true, ':' => true,
];
/**
* The debug log generated by the calculation engine.
*/
private Logger $debugLog;
private bool $suppressFormulaErrors = false;
private bool $processingAnchorArray = false;
/**
* Error message for any error that was raised/thrown by the calculation engine.
*/
public ?string $formulaError = null;
/**
* An array of the nested cell references accessed by the calculation engine, used for the debug log.
*/
private CyclicReferenceStack $cyclicReferenceStack;
/** @var mixed[] */
private array $cellStack = [];
/**
* Current iteration counter for cyclic formulae
* If the value is 0 (or less) then cyclic formulae will throw an exception,
* otherwise they will iterate to the limit defined here before returning a result.
*/
private int $cyclicFormulaCounter = 1;
private string $cyclicFormulaCell = '';
/**
* Number of iterations for cyclic formulae.
*/
public int $cyclicFormulaCount = 1;
/**
* Excel constant string translations to their PHP equivalents
* Constant conversion from text name/value to actual (datatyped) value.
*/
private const EXCEL_CONSTANTS = [
'TRUE' => true,
'FALSE' => false,
'NULL' => null,
];
public static function keyInExcelConstants(string $key): bool
{
return array_key_exists($key, self::EXCEL_CONSTANTS);
}
public static function getExcelConstants(string $key): bool|null
{
return self::EXCEL_CONSTANTS[$key];
}
/**
* Internal functions used for special control purposes.
*
* @var array|string>>
*/
private static array $controlFunctions = [
'MKMATRIX' => [
'argumentCount' => '*',
'functionCall' => [Internal\MakeMatrix::class, 'make'],
],
'NAME.ERROR' => [
'argumentCount' => '*',
'functionCall' => [ExcelError::class, 'NAME'],
],
'WILDCARDMATCH' => [
'argumentCount' => '2',
'functionCall' => [Internal\WildcardMatch::class, 'compare'],
],
];
public function __construct(?Spreadsheet $spreadsheet = null)
{
$this->spreadsheet = $spreadsheet;
$this->cyclicReferenceStack = new CyclicReferenceStack();
$this->debugLog = new Logger($this->cyclicReferenceStack);
$this->branchPruner = new BranchPruner($this->branchPruningEnabled);
}
/**
* Get an instance of this class.
*
* @param ?Spreadsheet $spreadsheet Injected spreadsheet for working with a PhpSpreadsheet Spreadsheet object,
* or NULL to create a standalone calculation engine
*/
public static function getInstance(?Spreadsheet $spreadsheet = null): self
{
if ($spreadsheet !== null) {
return $spreadsheet->getCalculationEngine();
}
if (!self::$instance) {
self::$instance = new self();
}
return self::$instance;
}
/**
* Intended for use only via a destructor.
*
* @internal
*/
public static function getInstanceOrNull(?Spreadsheet $spreadsheet = null): ?self
{
if ($spreadsheet !== null) {
return $spreadsheet->getCalculationEngineOrNull();
}
return null;
}
/**
* Flush the calculation cache for any existing instance of this class
* but only if a Calculation instance exists.
*/
public function flushInstance(): void
{
$this->clearCalculationCache();
$this->branchPruner->clearBranchStore();
}
/**
* Get the Logger for this calculation engine instance.
*/
public function getDebugLog(): Logger
{
return $this->debugLog;
}
/**
* __clone implementation. Cloning should not be allowed in a Singleton!
*/
final public function __clone()
{
throw new Exception('Cloning the calculation engine is not allowed!');
}
/**
* Set the Array Return Type (Array or Value of first element in the array).
*
* @param string $returnType Array return type
*
* @return bool Success or failure
*/
public static function setArrayReturnType(string $returnType): bool
{
if (
($returnType == self::RETURN_ARRAY_AS_VALUE)
|| ($returnType == self::RETURN_ARRAY_AS_ERROR)
|| ($returnType == self::RETURN_ARRAY_AS_ARRAY)
) {
self::$returnArrayAsType = $returnType;
return true;
}
return false;
}
/**
* Return the Array Return Type (Array or Value of first element in the array).
*
* @return string $returnType Array return type
*/
public static function getArrayReturnType(): string
{
return self::$returnArrayAsType;
}
/**
* Set the Instance Array Return Type (Array or Value of first element in the array).
*
* @param string $returnType Array return type
*
* @return bool Success or failure
*/
public function setInstanceArrayReturnType(string $returnType): bool
{
if (
($returnType == self::RETURN_ARRAY_AS_VALUE)
|| ($returnType == self::RETURN_ARRAY_AS_ERROR)
|| ($returnType == self::RETURN_ARRAY_AS_ARRAY)
) {
$this->instanceArrayReturnType = $returnType;
return true;
}
return false;
}
/**
* Return the Array Return Type (Array or Value of first element in the array).
*
* @return string $returnType Array return type for instance if non-null, otherwise static property
*/
public function getInstanceArrayReturnType(): string
{
return $this->instanceArrayReturnType ?? self::$returnArrayAsType;
}
/**
* Is calculation caching enabled?
*/
public function getCalculationCacheEnabled(): bool
{
return $this->calculationCacheEnabled;
}
/**
* Enable/disable calculation cache.
*/
public function setCalculationCacheEnabled(bool $calculationCacheEnabled): self
{
$this->calculationCacheEnabled = $calculationCacheEnabled;
$this->clearCalculationCache();
return $this;
}
/**
* Enable calculation cache.
*/
public function enableCalculationCache(): void
{
$this->setCalculationCacheEnabled(true);
}
/**
* Disable calculation cache.
*/
public function disableCalculationCache(): void
{
$this->setCalculationCacheEnabled(false);
}
/**
* Clear calculation cache.
*/
public function clearCalculationCache(): void
{
$this->calculationCache = [];
}
/**
* Clear calculation cache for a specified worksheet.
*/
public function clearCalculationCacheForWorksheet(string $worksheetName): void
{
if (isset($this->calculationCache[$worksheetName])) {
unset($this->calculationCache[$worksheetName]);
}
}
/**
* Rename calculation cache for a specified worksheet.
*/
public function renameCalculationCacheForWorksheet(string $fromWorksheetName, string $toWorksheetName): void
{
if (isset($this->calculationCache[$fromWorksheetName])) {
$this->calculationCache[$toWorksheetName] = &$this->calculationCache[$fromWorksheetName];
unset($this->calculationCache[$fromWorksheetName]);
}
}
public function getBranchPruningEnabled(): bool
{
return $this->branchPruningEnabled;
}
public function setBranchPruningEnabled(mixed $enabled): self
{
$this->branchPruningEnabled = (bool) $enabled;
$this->branchPruner = new BranchPruner($this->branchPruningEnabled);
return $this;
}
public function enableBranchPruning(): void
{
$this->setBranchPruningEnabled(true);
}
public function disableBranchPruning(): void
{
$this->setBranchPruningEnabled(false);
}
/**
* Wrap string values in quotes.
*/
public static function wrapResult(mixed $value): mixed
{
if (is_string($value)) {
// Error values cannot be "wrapped"
if (Preg::isMatch('/^' . self::CALCULATION_REGEXP_ERROR . '$/i', $value, $match)) {
// Return Excel errors "as is"
return $value;
}
// Return strings wrapped in quotes
return self::FORMULA_STRING_QUOTE . $value . self::FORMULA_STRING_QUOTE;
} elseif ((is_float($value)) && ((is_nan($value)) || (is_infinite($value)))) {
// Convert numeric errors to NaN error
return ExcelError::NAN();
}
return $value;
}
/**
* Remove quotes used as a wrapper to identify string values.
*/
public static function unwrapResult(mixed $value): mixed
{
if (is_string($value)) {
if ((isset($value[0])) && ($value[0] == self::FORMULA_STRING_QUOTE) && (substr($value, -1) == self::FORMULA_STRING_QUOTE)) {
return substr($value, 1, -1);
}
// Convert numeric errors to NAN error
} elseif ((is_float($value)) && ((is_nan($value)) || (is_infinite($value)))) {
return ExcelError::NAN();
}
return $value;
}
/**
* Calculate cell value (using formula from a cell ID)
* Retained for backward compatibility.
*
* @param ?Cell $cell Cell to calculate
*/
public function calculate(?Cell $cell = null): mixed
{
try {
return $this->calculateCellValue($cell);
} catch (\Exception $e) {
throw new Exception($e->getMessage());
}
}
/**
* Calculate the value of a cell formula.
*
* @param ?Cell $cell Cell to calculate
* @param bool $resetLog Flag indicating whether the debug log should be reset or not
*/
public function calculateCellValue(?Cell $cell = null, bool $resetLog = true): mixed
{
if ($cell === null) {
return null;
}
if ($resetLog) {
// Initialise the logging settings if requested
$this->formulaError = null;
$this->debugLog->clearLog();
$this->cyclicReferenceStack->clear();
$this->cyclicFormulaCounter = 1;
}
// Execute the calculation for the cell formula
$this->cellStack[] = [
'sheet' => $cell->getWorksheet()->getTitle(),
'cell' => $cell->getCoordinate(),
];
$cellAddressAttempted = false;
$cellAddress = null;
try {
$value = $cell->getValue();
if (is_string($value) && $cell->getDataType() === DataType::TYPE_FORMULA) {
$value = Preg::replaceCallback(
self::CALCULATION_REGEXP_CELLREF_SPILL,
fn (array $matches) => 'ANCHORARRAY(' . substr($matches[0], 0, -1) . ')',
$value
);
}
$result = self::unwrapResult($this->_calculateFormulaValue($value, $cell->getCoordinate(), $cell)); //* @phpstan-ignore-line
if ($this->spreadsheet === null) {
throw new Exception('null spreadsheet in calculateCellValue');
}
$cellAddressAttempted = true;
$cellAddress = array_pop($this->cellStack);
if ($cellAddress === null) {
throw new Exception('null cellAddress in calculateCellValue');
}
/** @var array{sheet: string, cell: string} $cellAddress */
$testSheet = $this->spreadsheet->getSheetByName($cellAddress['sheet']);
if ($testSheet === null) {
throw new Exception('worksheet not found in calculateCellValue');
}
$testSheet->getCell($cellAddress['cell']);
} catch (\Exception $e) {
if (!$cellAddressAttempted) {
$cellAddress = array_pop($this->cellStack);
}
if ($this->spreadsheet !== null && is_array($cellAddress) && array_key_exists('sheet', $cellAddress)) {
$sheetName = $cellAddress['sheet'] ?? null;
$testSheet = is_string($sheetName) ? $this->spreadsheet->getSheetByName($sheetName) : null;
if ($testSheet !== null && array_key_exists('cell', $cellAddress)) {
/** @var array{cell: string} $cellAddress */
$testSheet->getCell($cellAddress['cell']);
}
}
throw new Exception($e->getMessage(), $e->getCode(), $e);
}
if (is_array($result) && $this->getInstanceArrayReturnType() !== self::RETURN_ARRAY_AS_ARRAY) {
$testResult = Functions::flattenArray($result);
if ($this->getInstanceArrayReturnType() == self::RETURN_ARRAY_AS_ERROR) {
return ExcelError::VALUE();
}
$result = array_shift($testResult);
}
if ($result === null && $cell->getWorksheet()->getSheetView()->getShowZeros()) {
return 0;
} elseif ((is_float($result)) && ((is_nan($result)) || (is_infinite($result)))) {
return ExcelError::NAN();
}
return $result;
}
/**
* Validate and parse a formula string.
*
* @param string $formula Formula to parse
*
* @return array|bool
*/
public function parseFormula(string $formula): array|bool
{
$formula = Preg::replaceCallback(
self::CALCULATION_REGEXP_CELLREF_SPILL,
fn (array $matches) => 'ANCHORARRAY(' . substr($matches[0], 0, -1) . ')',
$formula
);
// Basic validation that this is indeed a formula
// We return an empty array if not
$formula = trim($formula);
if ((!isset($formula[0])) || ($formula[0] != '=')) {
return [];
}
$formula = ltrim(substr($formula, 1));
if (!isset($formula[0])) {
return [];
}
// Parse the formula and return the token stack
return $this->internalParseFormula($formula);
}
/**
* Calculate the value of a formula.
*
* @param string $formula Formula to parse
* @param ?string $cellID Address of the cell to calculate
* @param ?Cell $cell Cell to calculate
*/
public function calculateFormula(string $formula, ?string $cellID = null, ?Cell $cell = null): mixed
{
// Initialise the logging settings
$this->formulaError = null;
$this->debugLog->clearLog();
$this->cyclicReferenceStack->clear();
$resetCache = $this->getCalculationCacheEnabled();
if ($this->spreadsheet !== null && $cellID === null && $cell === null) {
$cellID = 'A1';
$cell = $this->spreadsheet->getActiveSheet()->getCell($cellID);
} else {
// Disable calculation cacheing because it only applies to cell calculations, not straight formulae
// But don't actually flush any cache
$this->calculationCacheEnabled = false;
}
// Execute the calculation
try {
$result = self::unwrapResult($this->_calculateFormulaValue($formula, $cellID, $cell));
} catch (\Exception $e) {
throw new Exception($e->getMessage());
}
if ($this->spreadsheet === null) {
// Reset calculation cacheing to its previous state
$this->calculationCacheEnabled = $resetCache;
}
return $result;
}
public function getValueFromCache(string $cellReference, mixed &$cellValue): bool
{
$this->debugLog->writeDebugLog('Testing cache value for cell %s', $cellReference);
// Is calculation cacheing enabled?
// If so, is the required value present in calculation cache?
if (($this->calculationCacheEnabled) && (isset($this->calculationCache[$cellReference]))) {
$this->debugLog->writeDebugLog('Retrieving value for cell %s from cache', $cellReference);
// Return the cached result
$cellValue = $this->calculationCache[$cellReference];
return true;
}
return false;
}
public function saveValueToCache(string $cellReference, mixed $cellValue): void
{
if ($this->calculationCacheEnabled) {
$this->calculationCache[$cellReference] = $cellValue;
}
}
/**
* Parse a cell formula and calculate its value.
*
* @param string $formula The formula to parse and calculate
* @param ?string $cellID The ID (e.g. A3) of the cell that we are calculating
* @param ?Cell $cell Cell to calculate
* @param bool $ignoreQuotePrefix If set to true, evaluate the formyla even if the referenced cell is quote prefixed
*/
public function _calculateFormulaValue(string $formula, ?string $cellID = null, ?Cell $cell = null, bool $ignoreQuotePrefix = false): mixed
{
$cellValue = null;
// Quote-Prefixed cell values cannot be formulae, but are treated as strings
if ($cell !== null && $ignoreQuotePrefix === false && $cell->getStyle()->getQuotePrefix() === true) {
return self::wrapResult((string) $formula);
}
// https://www.reddit.com/r/excel/comments/chr41y/cmd_formula_stopped_working_since_last_update/
if (preg_match('/^=\s*cmd\s*\|/miu', $formula) !== 0) {
return ExcelError::REF(); // returns #BLOCKED in newer versions
}
// Basic validation that this is indeed a formula
// We simply return the cell value if not
$formula = trim($formula);
if ($formula === '' || $formula[0] !== '=') {
return self::wrapResult($formula);
}
$formula = ltrim(substr($formula, 1));
if (!isset($formula[0])) {
return self::wrapResult($formula);
}
$pCellParent = ($cell !== null) ? $cell->getWorksheet() : null;
$wsTitle = ($pCellParent !== null) ? $pCellParent->getTitle() : "\x00Wrk";
$wsCellReference = $wsTitle . '!' . $cellID;
if (($cellID !== null) && ($this->getValueFromCache($wsCellReference, $cellValue))) {
return $cellValue;
}
$this->debugLog->writeDebugLog('Evaluating formula for cell %s', $wsCellReference);
if (($wsTitle[0] !== "\x00") && ($this->cyclicReferenceStack->onStack($wsCellReference))) {
if ($this->cyclicFormulaCount <= 0) {
$this->cyclicFormulaCell = '';
return $this->raiseFormulaError('Cyclic Reference in Formula');
} elseif ($this->cyclicFormulaCell === $wsCellReference) {
++$this->cyclicFormulaCounter;
if ($this->cyclicFormulaCounter >= $this->cyclicFormulaCount) {
$this->cyclicFormulaCell = '';
return $cellValue;
}
} elseif ($this->cyclicFormulaCell == '') {
if ($this->cyclicFormulaCounter >= $this->cyclicFormulaCount) {
return $cellValue;
}
$this->cyclicFormulaCell = $wsCellReference;
}
}
$this->debugLog->writeDebugLog('Formula for cell %s is %s', $wsCellReference, $formula);
// Parse the formula onto the token stack and calculate the value
$this->cyclicReferenceStack->push($wsCellReference);
$cellValue = $this->processTokenStack($this->internalParseFormula($formula, $cell), $cellID, $cell);
$this->cyclicReferenceStack->pop();
// Save to calculation cache
if ($cellID !== null) {
$this->saveValueToCache($wsCellReference, $cellValue);
}
// Return the calculated value
return $cellValue;
}
/**
* Ensure that paired matrix operands are both matrices and of the same size.
*
* @param mixed $operand1 First matrix operand
*
* @param-out mixed[] $operand1
*
* @param mixed $operand2 Second matrix operand
*
* @param-out mixed[] $operand2
*
* @param int $resize Flag indicating whether the matrices should be resized to match
* and (if so), whether the smaller dimension should grow or the
* larger should shrink.
* 0 = no resize
* 1 = shrink to fit
* 2 = extend to fit
*
* @return mixed[]
*/
public static function checkMatrixOperands(mixed &$operand1, mixed &$operand2, int $resize = 1): array
{
// Examine each of the two operands, and turn them into an array if they aren't one already
// Note that this function should only be called if one or both of the operand is already an array
if (!is_array($operand1)) {
if (is_array($operand2)) {
[$matrixRows, $matrixColumns] = self::getMatrixDimensions($operand2);
$operand1 = array_fill(0, $matrixRows, array_fill(0, $matrixColumns, $operand1));
$resize = 0;
} else {
$operand1 = [$operand1];
$operand2 = [$operand2];
}
} elseif (!is_array($operand2)) {
[$matrixRows, $matrixColumns] = self::getMatrixDimensions($operand1);
$operand2 = array_fill(0, $matrixRows, array_fill(0, $matrixColumns, $operand2));
$resize = 0;
}
[$matrix1Rows, $matrix1Columns] = self::getMatrixDimensions($operand1);
[$matrix2Rows, $matrix2Columns] = self::getMatrixDimensions($operand2);
if ($resize === 3) {
$resize = 2;
} elseif (($matrix1Rows == $matrix2Columns) && ($matrix2Rows == $matrix1Columns)) {
$resize = 1;
}
if ($resize == 2) {
// Given two matrices of (potentially) unequal size, convert the smaller in each dimension to match the larger
self::resizeMatricesExtend($operand1, $operand2, $matrix1Rows, $matrix1Columns, $matrix2Rows, $matrix2Columns);
} elseif ($resize == 1) {
// Given two matrices of (potentially) unequal size, convert the larger in each dimension to match the smaller
/** @var mixed[][] $operand1 */
/** @var mixed[][] $operand2 */
self::resizeMatricesShrink($operand1, $operand2, $matrix1Rows, $matrix1Columns, $matrix2Rows, $matrix2Columns);
}
[$matrix1Rows, $matrix1Columns] = self::getMatrixDimensions($operand1);
[$matrix2Rows, $matrix2Columns] = self::getMatrixDimensions($operand2);
return [$matrix1Rows, $matrix1Columns, $matrix2Rows, $matrix2Columns];
}
/**
* Read the dimensions of a matrix, and re-index it with straight numeric keys starting from row 0, column 0.
*
* @param mixed[] $matrix matrix operand
*
* @return int[] An array comprising the number of rows, and number of columns
*/
public static function getMatrixDimensions(array &$matrix): array
{
$matrixRows = count($matrix);
$matrixColumns = 0;
foreach ($matrix as $rowKey => $rowValue) {
if (!is_array($rowValue)) {
$matrix[$rowKey] = [$rowValue];
$matrixColumns = max(1, $matrixColumns);
} else {
$matrix[$rowKey] = array_values($rowValue);
$matrixColumns = max(count($rowValue), $matrixColumns);
}
}
$matrix = array_values($matrix);
return [$matrixRows, $matrixColumns];
}
/**
* Ensure that paired matrix operands are both matrices of the same size.
*
* @param mixed[][] $matrix1 First matrix operand
* @param mixed[][] $matrix2 Second matrix operand
* @param int $matrix1Rows Row size of first matrix operand
* @param int $matrix1Columns Column size of first matrix operand
* @param int $matrix2Rows Row size of second matrix operand
* @param int $matrix2Columns Column size of second matrix operand
*/
private static function resizeMatricesShrink(array &$matrix1, array &$matrix2, int $matrix1Rows, int $matrix1Columns, int $matrix2Rows, int $matrix2Columns): void
{
if (($matrix2Columns < $matrix1Columns) || ($matrix2Rows < $matrix1Rows)) {
if ($matrix2Rows < $matrix1Rows) {
for ($i = $matrix2Rows; $i < $matrix1Rows; ++$i) {
unset($matrix1[$i]);
}
}
if ($matrix2Columns < $matrix1Columns) {
for ($i = 0; $i < $matrix1Rows; ++$i) {
for ($j = $matrix2Columns; $j < $matrix1Columns; ++$j) {
unset($matrix1[$i][$j]);
}
}
}
}
if (($matrix1Columns < $matrix2Columns) || ($matrix1Rows < $matrix2Rows)) {
if ($matrix1Rows < $matrix2Rows) {
for ($i = $matrix1Rows; $i < $matrix2Rows; ++$i) {
unset($matrix2[$i]);
}
}
if ($matrix1Columns < $matrix2Columns) {
for ($i = 0; $i < $matrix2Rows; ++$i) {
for ($j = $matrix1Columns; $j < $matrix2Columns; ++$j) {
unset($matrix2[$i][$j]);
}
}
}
}
}
/**
* Ensure that paired matrix operands are both matrices of the same size.
*
* @param mixed[] $matrix1 First matrix operand
* @param mixed[] $matrix2 Second matrix operand
* @param int $matrix1Rows Row size of first matrix operand
* @param int $matrix1Columns Column size of first matrix operand
* @param int $matrix2Rows Row size of second matrix operand
* @param int $matrix2Columns Column size of second matrix operand
*/
private static function resizeMatricesExtend(array &$matrix1, array &$matrix2, int $matrix1Rows, int $matrix1Columns, int $matrix2Rows, int $matrix2Columns): void
{
if (($matrix2Columns < $matrix1Columns) || ($matrix2Rows < $matrix1Rows)) {
if ($matrix2Columns < $matrix1Columns) {
for ($i = 0; $i < $matrix2Rows; ++$i) {
/** @var mixed[][] $matrix2 */
$x = ($matrix2Columns === 1) ? $matrix2[$i][0] : null;
for ($j = $matrix2Columns; $j < $matrix1Columns; ++$j) {
$matrix2[$i][$j] = $x;
}
}
}
if ($matrix2Rows < $matrix1Rows) {
$x = ($matrix2Rows === 1) ? $matrix2[0] : array_fill(0, $matrix2Columns, null);
for ($i = $matrix2Rows; $i < $matrix1Rows; ++$i) {
$matrix2[$i] = $x;
}
}
}
if (($matrix1Columns < $matrix2Columns) || ($matrix1Rows < $matrix2Rows)) {
if ($matrix1Columns < $matrix2Columns) {
for ($i = 0; $i < $matrix1Rows; ++$i) {
/** @var mixed[][] $matrix1 */
$x = ($matrix1Columns === 1) ? $matrix1[$i][0] : null;
for ($j = $matrix1Columns; $j < $matrix2Columns; ++$j) {
$matrix1[$i][$j] = $x;
}
}
}
if ($matrix1Rows < $matrix2Rows) {
$x = ($matrix1Rows === 1) ? $matrix1[0] : array_fill(0, $matrix2Columns, null);
for ($i = $matrix1Rows; $i < $matrix2Rows; ++$i) {
$matrix1[$i] = $x;
}
}
}
}
/**
* Format details of an operand for display in the log (based on operand type).
*
* @param mixed $value First matrix operand
*/
private function showValue(mixed $value): mixed
{
if ($this->debugLog->getWriteDebugLog()) {
$testArray = Functions::flattenArray($value);
if (count($testArray) == 1) {
$value = array_pop($testArray);
}
if (is_array($value)) {
$returnMatrix = [];
$pad = $rpad = ', ';
foreach ($value as $row) {
if (is_array($row)) {
$returnMatrix[] = implode($pad, array_map([$this, 'showValue'], $row));
$rpad = '; ';
} else {
$returnMatrix[] = $this->showValue($row);
}
}
return '{ ' . implode($rpad, $returnMatrix) . ' }';
} elseif (is_string($value) && (trim($value, self::FORMULA_STRING_QUOTE) == $value)) {
return self::FORMULA_STRING_QUOTE . $value . self::FORMULA_STRING_QUOTE;
} elseif (is_bool($value)) {
return ($value) ? self::$localeBoolean['TRUE'] : self::$localeBoolean['FALSE'];
} elseif ($value === null) {
return self::$localeBoolean['NULL'];
}
}
return Functions::flattenSingleValue($value);
}
/**
* Format type and details of an operand for display in the log (based on operand type).
*
* @param mixed $value First matrix operand
*/
private function showTypeDetails(mixed $value): ?string
{
if ($this->debugLog->getWriteDebugLog()) {
$testArray = Functions::flattenArray($value);
if (count($testArray) == 1) {
$value = array_pop($testArray);
}
if ($value === null) {
return 'a NULL value';
} elseif (is_float($value)) {
$typeString = 'a floating point number';
} elseif (is_int($value)) {
$typeString = 'an integer number';
} elseif (is_bool($value)) {
$typeString = 'a boolean';
} elseif (is_array($value)) {
$typeString = 'a matrix';
} else {
/** @var string $value */
if ($value == '') {
return 'an empty string';
} elseif ($value[0] == '#') {
return 'a ' . $value . ' error';
}
$typeString = 'a string';
}
return $typeString . ' with a value of ' . StringHelper::convertToString($this->showValue($value));
}
return null;
}
private const MATRIX_REPLACE_FROM = [self::FORMULA_OPEN_MATRIX_BRACE, ';', self::FORMULA_CLOSE_MATRIX_BRACE];
private const MATRIX_REPLACE_TO = ['MKMATRIX(MKMATRIX(', '),MKMATRIX(', '))'];
/**
* @return false|string False indicates an error
*/
private function convertMatrixReferences(string $formula): false|string
{
// Convert any Excel matrix references to the MKMATRIX() function
if (str_contains($formula, self::FORMULA_OPEN_MATRIX_BRACE)) {
// If there is the possibility of braces within a quoted string, then we don't treat those as matrix indicators
if (str_contains($formula, self::FORMULA_STRING_QUOTE)) {
// So instead we skip replacing in any quoted strings by only replacing in every other array element after we've exploded
// the formula
$temp = explode(self::FORMULA_STRING_QUOTE, $formula);
// Open and Closed counts used for trapping mismatched braces in the formula
$openCount = $closeCount = 0;
$notWithinQuotes = false;
foreach ($temp as &$value) {
// Only count/replace in alternating array entries
$notWithinQuotes = $notWithinQuotes === false;
if ($notWithinQuotes === true) {
$openCount += substr_count($value, self::FORMULA_OPEN_MATRIX_BRACE);
$closeCount += substr_count($value, self::FORMULA_CLOSE_MATRIX_BRACE);
$value = str_replace(self::MATRIX_REPLACE_FROM, self::MATRIX_REPLACE_TO, $value);
}
}
unset($value);
// Then rebuild the formula string
$formula = implode(self::FORMULA_STRING_QUOTE, $temp);
} else {
// If there's no quoted strings, then we do a simple count/replace
$openCount = substr_count($formula, self::FORMULA_OPEN_MATRIX_BRACE);
$closeCount = substr_count($formula, self::FORMULA_CLOSE_MATRIX_BRACE);
$formula = str_replace(self::MATRIX_REPLACE_FROM, self::MATRIX_REPLACE_TO, $formula);
}
// Trap for mismatched braces and trigger an appropriate error
if ($openCount < $closeCount) {
if ($openCount > 0) {
return $this->raiseFormulaError("Formula Error: Mismatched matrix braces '}'");
}
return $this->raiseFormulaError("Formula Error: Unexpected '}' encountered");
} elseif ($openCount > $closeCount) {
if ($closeCount > 0) {
return $this->raiseFormulaError("Formula Error: Mismatched matrix braces '{'");
}
return $this->raiseFormulaError("Formula Error: Unexpected '{' encountered");
}
}
return $formula;
}
/**
* Comparison (Boolean) Operators.
* These operators work on two values, but always return a boolean result.
*/
private const COMPARISON_OPERATORS = ['>' => true, '<' => true, '=' => true, '>=' => true, '<=' => true, '<>' => true];
/**
* Operator Precedence.
* This list includes all valid operators, whether binary (including boolean) or unary (such as %).
* Array key is the operator, the value is its precedence.
*/
private const OPERATOR_PRECEDENCE = [
':' => 9, // Range
'∩' => 8, // Intersect
'∪' => 7, // Union
'~' => 6, // Negation
'%' => 5, // Percentage
'^' => 4, // Exponentiation
'*' => 3, '/' => 3, // Multiplication and Division
'+' => 2, '-' => 2, // Addition and Subtraction
'&' => 1, // Concatenation
'>' => 0, '<' => 0, '=' => 0, '>=' => 0, '<=' => 0, '<>' => 0, // Comparison
];
/** @param string[] $matches */
private static function unionForComma(array $matches): string
{
return $matches[1] . str_replace(',', '∪', $matches[2]);
}
private const CELL_OR_CELLRANGE_OR_DEFINED_NAME
= '(?:'
. self::CALCULATION_REGEXP_CELLREF // cell address
. '(?::' . self::CALCULATION_REGEXP_CELLREF . ')?' // optional range address, non-capturing
. '|' . self::CALCULATION_REGEXP_DEFINEDNAME
. ')'
;
public const UNIONABLE_COMMAS = '/((?:[,(]|^)\s*)' // comma or open paren or start of string, followed by optional whitespace
. '([(]' // open paren
. self::CELL_OR_CELLRANGE_OR_DEFINED_NAME // cell address
. '(?:\s*,\s*' // optioonal whitespace, comma, optional whitespace, non-capturing
. self::CELL_OR_CELLRANGE_OR_DEFINED_NAME // cell address
. ')+' // one or more occurrences
. '\s*[)])/i'; // optional whitespace, end paren
/**
* @return array|false
*/
private function internalParseFormula(string $formula, ?Cell $cell = null): bool|array
{
if (($formula = $this->convertMatrixReferences(trim($formula))) === false) {
return false;
}
$oldFormula = $formula;
$formula = Preg::replaceCallback(self::UNIONABLE_COMMAS, self::unionForComma(...), $formula); // @phpstan-ignore-line
if ($oldFormula !== $formula) {
$this->debugLog->writeDebugLog('Reformulated as %s', $formula);
}
$phpSpreadsheetFunctions = &self::getFunctionsAddress();
// If we're using cell caching, then $pCell may well be flushed back to the cache (which detaches the parent worksheet),
// so we store the parent worksheet so that we can re-attach it when necessary
$pCellParent = ($cell !== null) ? $cell->getWorksheet() : null;
$regexpMatchString = '/^((?' . self::CALCULATION_REGEXP_STRING
. ')|(?' . self::CALCULATION_REGEXP_FUNCTION
. ')|(?' . self::CALCULATION_REGEXP_CELLREF
. ')|(?' . self::CALCULATION_REGEXP_COLUMN_RANGE
. ')|(?' . self::CALCULATION_REGEXP_ROW_RANGE
. ')|(?' . self::CALCULATION_REGEXP_NUMBER
. ')|(?' . self::CALCULATION_REGEXP_OPENBRACE
. ')|(?' . self::CALCULATION_REGEXP_STRUCTURED_REFERENCE
. ')|(?' . self::CALCULATION_REGEXP_DEFINEDNAME
. ')|(?' . self::CALCULATION_REGEXP_ERROR
. '))/sui';
// Start with initialisation
$index = 0;
$stack = new Stack($this->branchPruner);
$output = [];
$expectingOperator = false; // We use this test in syntax-checking the expression to determine when a
// - is a negation or + is a positive operator rather than an operation
$expectingOperand = false; // We use this test in syntax-checking the expression to determine whether an operand
// should be null in a function call
// The guts of the lexical parser
// Loop through the formula extracting each operator and operand in turn
while (true) {
// Branch pruning: we adapt the output item to the context (it will
// be used to limit its computation)
$this->branchPruner->initialiseForLoop();
$opCharacter = $formula[$index]; // Get the first character of the value at the current index position
if ($opCharacter === "\xe2") { // intersection or union
$opCharacter .= $formula[++$index];
$opCharacter .= $formula[++$index];
}
// Check for two-character operators (e.g. >=, <=, <>)
if ((isset(self::COMPARISON_OPERATORS[$opCharacter])) && (strlen($formula) > $index) && isset($formula[$index + 1], self::COMPARISON_OPERATORS[$formula[$index + 1]])) {
$opCharacter .= $formula[++$index];
}
// Find out if we're currently at the beginning of a number, variable, cell/row/column reference,
// function, defined name, structured reference, parenthesis, error or operand
$isOperandOrFunction = (bool) preg_match($regexpMatchString, substr($formula, $index), $match);
$expectingOperatorCopy = $expectingOperator;
if ($opCharacter === '-' && !$expectingOperator) { // Is it a negation instead of a minus?
// Put a negation on the stack
$stack->push('Unary Operator', '~');
++$index; // and drop the negation symbol
} elseif ($opCharacter === '%' && $expectingOperator) {
// Put a percentage on the stack
$stack->push('Unary Operator', '%');
++$index;
} elseif ($opCharacter === '+' && !$expectingOperator) { // Positive (unary plus rather than binary operator plus) can be discarded?
++$index; // Drop the redundant plus symbol
} elseif ((($opCharacter === '~') /*|| ($opCharacter === '∩') || ($opCharacter === '∪')*/) && (!$isOperandOrFunction)) {
// We have to explicitly deny a tilde, union or intersect because they are legal
return $this->raiseFormulaError("Formula Error: Illegal character '~'"); // on the stack but not in the input expression
} elseif ((isset(self::CALCULATION_OPERATORS[$opCharacter]) || $isOperandOrFunction) && $expectingOperator) { // Are we putting an operator on the stack?
while (self::swapOperands($stack, $opCharacter)) {
$output[] = $stack->pop(); // Swap operands and higher precedence operators from the stack to the output
}
// Finally put our current operator onto the stack
$stack->push('Binary Operator', $opCharacter);
++$index;
$expectingOperator = false;
} elseif ($opCharacter === ')' && $expectingOperator) { // Are we expecting to close a parenthesis?
$expectingOperand = false;
while (($o2 = $stack->pop()) && $o2['value'] !== '(') { // Pop off the stack back to the last (
$output[] = $o2;
}
$d = $stack->last(2);
// Branch pruning we decrease the depth whether is it a function
// call or a parenthesis
$this->branchPruner->decrementDepth();
if (is_array($d) && preg_match('/^' . self::CALCULATION_REGEXP_FUNCTION . '$/miu', StringHelper::convertToString($d['value']), $matches)) {
// Did this parenthesis just close a function?
try {
$this->branchPruner->closingBrace($d['value']);
} catch (Exception $e) {
return $this->raiseFormulaError($e->getMessage(), $e->getCode(), $e);
}
$functionName = $matches[1]; // Get the function name
$d = $stack->pop();
$argumentCount = $d['value'] ?? 0; // See how many arguments there were (argument count is the next value stored on the stack)
$output[] = $d; // Dump the argument count on the output
$output[] = $stack->pop(); // Pop the function and push onto the output
if (isset(self::$controlFunctions[$functionName])) {
$expectedArgumentCount = self::$controlFunctions[$functionName]['argumentCount'];
} elseif (isset($phpSpreadsheetFunctions[$functionName])) {
$expectedArgumentCount = $phpSpreadsheetFunctions[$functionName]['argumentCount'];
} else { // did we somehow push a non-function on the stack? this should never happen
return $this->raiseFormulaError('Formula Error: Internal error, non-function on stack');
}
// Check the argument count
$argumentCountError = false;
$expectedArgumentCountString = null;
if (is_numeric($expectedArgumentCount)) {
if ($expectedArgumentCount < 0) {
if ($argumentCount > abs($expectedArgumentCount + 0)) {
$argumentCountError = true;
$expectedArgumentCountString = 'no more than ' . abs($expectedArgumentCount + 0);
}
} else {
if ($argumentCount != $expectedArgumentCount) {
$argumentCountError = true;
$expectedArgumentCountString = $expectedArgumentCount;
}
}
} elseif (is_string($expectedArgumentCount) && $expectedArgumentCount !== '*') {
if (!Preg::isMatch('/(\d*)([-+,])(\d*)/', $expectedArgumentCount, $argMatch)) {
$argMatch = ['', '', '', ''];
}
switch ($argMatch[2]) {
case '+':
if ($argumentCount < $argMatch[1]) {
$argumentCountError = true;
$expectedArgumentCountString = $argMatch[1] . ' or more ';
}
break;
case '-':
if (($argumentCount < $argMatch[1]) || ($argumentCount > $argMatch[3])) {
$argumentCountError = true;
$expectedArgumentCountString = 'between ' . $argMatch[1] . ' and ' . $argMatch[3];
}
break;
case ',':
if (($argumentCount != $argMatch[1]) && ($argumentCount != $argMatch[3])) {
$argumentCountError = true;
$expectedArgumentCountString = 'either ' . $argMatch[1] . ' or ' . $argMatch[3];
}
break;
}
}
if ($argumentCountError) {
/** @var int $argumentCount */
return $this->raiseFormulaError("Formula Error: Wrong number of arguments for $functionName() function: $argumentCount given, " . $expectedArgumentCountString . ' expected');
}
}
++$index;
} elseif ($opCharacter === ',') { // Is this the separator for function arguments?
try {
$this->branchPruner->argumentSeparator();
} catch (Exception $e) {
return $this->raiseFormulaError($e->getMessage(), $e->getCode(), $e);
}
while (($o2 = $stack->pop()) && $o2['value'] !== '(') { // Pop off the stack back to the last (
$output[] = $o2; // pop the argument expression stuff and push onto the output
}
// If we've a comma when we're expecting an operand, then what we actually have is a null operand;
// so push a null onto the stack
if (($expectingOperand) || (!$expectingOperator)) {
$output[] = $stack->getStackItem('Empty Argument', null, 'NULL');
}
// make sure there was a function
$d = $stack->last(2);
/** @var string */
$temp = $d['value'] ?? '';
if (!preg_match('/^' . self::CALCULATION_REGEXP_FUNCTION . '$/miu', $temp, $matches)) {
// Can we inject a dummy function at this point so that the braces at least have some context
// because at least the braces are paired up (at this stage in the formula)
// MS Excel allows this if the content is cell references; but doesn't allow actual values,
// but at this point, we can't differentiate (so allow both)
//return $this->raiseFormulaError('Formula Error: Unexpected ,');
$stack->push('Binary Operator', '∪');
++$index;
$expectingOperator = false;
continue;
}
/** @var array $d */
$d = $stack->pop();
++$d['value']; // increment the argument count
$stack->pushStackItem($d);
$stack->push('Brace', '('); // put the ( back on, we'll need to pop back to it again
$expectingOperator = false;
$expectingOperand = true;
++$index;
} elseif ($opCharacter === '(' && !$expectingOperator) {
// Branch pruning: we go deeper
$this->branchPruner->incrementDepth();
$stack->push('Brace', '(', null);
++$index;
} elseif ($isOperandOrFunction && !$expectingOperatorCopy) {
// do we now have a function/variable/number?
$expectingOperator = true;
$expectingOperand = false;
$val = $match[1] ?? ''; //* @phpstan-ignore-line
$length = strlen($val);
if (preg_match('/^' . self::CALCULATION_REGEXP_FUNCTION . '$/miu', $val, $matches)) {
// $val is known to be valid unicode from statement above, so Preg::replace is okay even with u modifier
$val = Preg::replace('/\s/u', '', $val);
if (isset($phpSpreadsheetFunctions[strtoupper($matches[1])]) || isset(self::$controlFunctions[strtoupper($matches[1])])) { // it's a function
$valToUpper = strtoupper($val);
} else {
$valToUpper = 'NAME.ERROR(';
}
// here $matches[1] will contain values like "IF"
// and $val "IF("
$this->branchPruner->functionCall($valToUpper);
$stack->push('Function', $valToUpper);
// tests if the function is closed right after opening
$ax = preg_match('/^\s*\)/u', substr($formula, $index + $length));
if ($ax) {
$stack->push('Operand Count for Function ' . $valToUpper . ')', 0);
$expectingOperator = true;
} else {
$stack->push('Operand Count for Function ' . $valToUpper . ')', 1);
$expectingOperator = false;
}
$stack->push('Brace', '(');
} elseif (preg_match('/^' . self::CALCULATION_REGEXP_CELLREF . '$/miu', $val, $matches)) {
// Watch for this case-change when modifying to allow cell references in different worksheets...
// Should only be applied to the actual cell column, not the worksheet name
// If the last entry on the stack was a : operator, then we have a cell range reference
$testPrevOp = $stack->last(1);
if ($testPrevOp !== null && $testPrevOp['value'] === ':') {
// If we have a worksheet reference, then we're playing with a 3D reference
if ($matches[2] === '') {
// Otherwise, we 'inherit' the worksheet reference from the start cell reference
// The start of the cell range reference should be the last entry in $output
$rangeStartCellRef = $output[count($output) - 1]['value'] ?? '';
if ($rangeStartCellRef === ':') {
// Do we have chained range operators?
$rangeStartCellRef = $output[count($output) - 2]['value'] ?? '';
}
/** @var string $rangeStartCellRef */
preg_match('/^' . self::CALCULATION_REGEXP_CELLREF . '$/miu', $rangeStartCellRef, $rangeStartMatches);
if (array_key_exists(2, $rangeStartMatches)) {
if ($rangeStartMatches[2] > '') {
$val = $rangeStartMatches[2] . '!' . $val;
}
} else {
$val = ExcelError::REF();
}
} else {
$rangeStartCellRef = $output[count($output) - 1]['value'] ?? '';
if ($rangeStartCellRef === ':') {
// Do we have chained range operators?
$rangeStartCellRef = $output[count($output) - 2]['value'] ?? '';
}
/** @var string $rangeStartCellRef */
preg_match('/^' . self::CALCULATION_REGEXP_CELLREF . '$/miu', $rangeStartCellRef, $rangeStartMatches);
if (isset($rangeStartMatches[2]) && $rangeStartMatches[2] !== $matches[2]) {
return $this->raiseFormulaError('3D Range references are not yet supported');
}
}
} elseif (!str_contains($val, '!') && $pCellParent !== null) {
$worksheet = $pCellParent->getTitle();
$val = "'{$worksheet}'!{$val}";
}
// unescape any apostrophes or double quotes in worksheet name
$val = str_replace(["''", '""'], ["'", '"'], $val);
$outputItem = $stack->getStackItem('Cell Reference', $val, $val);
$output[] = $outputItem;
} elseif (preg_match('/^' . self::CALCULATION_REGEXP_STRUCTURED_REFERENCE . '$/miu', $val, $matches)) {
try {
$structuredReference = Operands\StructuredReference::fromParser($formula, $index, $matches);
} catch (Exception $e) {
return $this->raiseFormulaError($e->getMessage(), $e->getCode(), $e);
}
$val = $structuredReference->value();
$length = strlen($val);
$outputItem = $stack->getStackItem(Operands\StructuredReference::NAME, $structuredReference, null);
$output[] = $outputItem;
$expectingOperator = true;
} else {
// it's a variable, constant, string, number or boolean
$localeConstant = false;
$stackItemType = 'Value';
$stackItemReference = null;
// If the last entry on the stack was a : operator, then we may have a row or column range reference
$testPrevOp = $stack->last(1);
if ($testPrevOp !== null && $testPrevOp['value'] === ':') {
$stackItemType = 'Cell Reference';
if (
!is_numeric($val)
&& ((ctype_alpha($val) === false || strlen($val) > 3))
&& (preg_match('/^' . self::CALCULATION_REGEXP_DEFINEDNAME . '$/mui', $val) !== false)
&& ($this->spreadsheet === null || $this->spreadsheet->getNamedRange($val) !== null)
) {
$namedRange = ($this->spreadsheet === null) ? null : $this->spreadsheet->getNamedRange($val);
if ($namedRange !== null) {
$stackItemType = 'Defined Name';
$address = str_replace('$', '', $namedRange->getValue());
$stackItemReference = $val;
if (str_contains($address, ':')) {
// We'll need to manipulate the stack for an actual named range rather than a named cell
$fromTo = explode(':', $address);
$to = array_pop($fromTo);
foreach ($fromTo as $from) {
$output[] = $stack->getStackItem($stackItemType, $from, $stackItemReference);
$output[] = $stack->getStackItem('Binary Operator', ':');
}
$address = $to;
}
$val = $address;
}
} elseif ($val === ExcelError::REF()) {
$stackItemReference = $val;
} else {
/** @var non-empty-string $startRowColRef */
$startRowColRef = $output[count($output) - 1]['value'] ?? '';
[$rangeWS1, $startRowColRef] = Worksheet::extractSheetTitle($startRowColRef, true);
$rangeSheetRef = $rangeWS1;
if ($rangeWS1 !== '') {
$rangeWS1 .= '!';
}
if (str_starts_with($rangeSheetRef, "'")) {
$rangeSheetRef = Worksheet::unApostrophizeTitle($rangeSheetRef);
}
[$rangeWS2, $val] = Worksheet::extractSheetTitle($val, true);
if ($rangeWS2 !== '') {
$rangeWS2 .= '!';
} else {
$rangeWS2 = $rangeWS1;
}
$refSheet = $pCellParent;
if ($pCellParent !== null && $rangeSheetRef !== '' && $rangeSheetRef !== $pCellParent->getTitle()) {
$refSheet = $pCellParent->getParentOrThrow()->getSheetByName($rangeSheetRef);
}
if (ctype_digit($val) && $val <= AddressRange::MAX_ROW) {
// Row range
$stackItemType = 'Row Reference';
$valx = $val;
$endRowColRef = ($refSheet !== null) ? $refSheet->getHighestDataColumn($valx) : AddressRange::MAX_COLUMN; // Max 16,384 columns for Excel2007
$val = "{$rangeWS2}{$endRowColRef}{$val}";
} elseif (ctype_alpha($val) && strlen($val) <= 3) {
// Column range
$stackItemType = 'Column Reference';
$endRowColRef = ($refSheet !== null) ? $refSheet->getHighestDataRow($val) : AddressRange::MAX_ROW; // Max 1,048,576 rows for Excel2007
$val = "{$rangeWS2}{$val}{$endRowColRef}";
}
$stackItemReference = $val;
}
} elseif ($opCharacter === self::FORMULA_STRING_QUOTE) {
// UnEscape any quotes within the string
$val = self::wrapResult(str_replace('""', self::FORMULA_STRING_QUOTE, StringHelper::convertToString(self::unwrapResult($val))));
} elseif (isset(self::EXCEL_CONSTANTS[trim(strtoupper($val))])) {
$stackItemType = 'Constant';
$excelConstant = trim(strtoupper($val));
$val = self::EXCEL_CONSTANTS[$excelConstant];
$stackItemReference = $excelConstant;
} elseif (($localeConstant = array_search(trim(strtoupper($val)), self::$localeBoolean)) !== false) {
$stackItemType = 'Constant';
$val = self::EXCEL_CONSTANTS[$localeConstant];
$stackItemReference = $localeConstant;
} elseif (
preg_match('/^' . self::CALCULATION_REGEXP_ROW_RANGE . '/miu', substr($formula, $index), $rowRangeReference)
) {
$val = $rowRangeReference[1];
$length = strlen($rowRangeReference[1]);
$stackItemType = 'Row Reference';
// unescape any apostrophes or double quotes in worksheet name
$val = str_replace(["''", '""'], ["'", '"'], $val);
$column = 'A';
if (($testPrevOp !== null && $testPrevOp['value'] === ':') && $pCellParent !== null) {
$column = $pCellParent->getHighestDataColumn($val);
}
$val = "{$rowRangeReference[2]}{$column}{$rowRangeReference[7]}";
$stackItemReference = $val;
} elseif (
preg_match('/^' . self::CALCULATION_REGEXP_COLUMN_RANGE . '/miu', substr($formula, $index), $columnRangeReference)
) {
$val = $columnRangeReference[1];
$length = strlen($val);
$stackItemType = 'Column Reference';
// unescape any apostrophes or double quotes in worksheet name
$val = str_replace(["''", '""'], ["'", '"'], $val);
$row = '1';
if (($testPrevOp !== null && $testPrevOp['value'] === ':') && $pCellParent !== null) {
$row = $pCellParent->getHighestDataRow($val);
}
$val = "{$val}{$row}";
$stackItemReference = $val;
} elseif (preg_match('/^' . self::CALCULATION_REGEXP_DEFINEDNAME . '.*/miu', $val, $match)) {
$stackItemType = 'Defined Name';
$stackItemReference = $val;
} elseif (is_numeric($val)) {
if ((str_contains((string) $val, '.')) || (stripos((string) $val, 'e') !== false) || ($val > PHP_INT_MAX) || ($val < -PHP_INT_MAX)) {
$val = (float) $val;
} else {
$val = (int) $val;
}
}
$details = $stack->getStackItem($stackItemType, $val, $stackItemReference);
if ($localeConstant) {
$details['localeValue'] = $localeConstant;
}
$output[] = $details;
}
$index += $length;
} elseif ($opCharacter === '$') { // absolute row or column range
++$index;
} elseif ($opCharacter === ')') { // miscellaneous error checking
if ($expectingOperand) {
$output[] = $stack->getStackItem('Empty Argument', null, 'NULL');
$expectingOperand = false;
$expectingOperator = true;
} else {
return $this->raiseFormulaError("Formula Error: Unexpected ')'");
}
} elseif (isset(self::CALCULATION_OPERATORS[$opCharacter]) && !$expectingOperator) {
return $this->raiseFormulaError("Formula Error: Unexpected operator '$opCharacter'");
} else { // I don't even want to know what you did to get here
return $this->raiseFormulaError('Formula Error: An unexpected error occurred');
}
// Test for end of formula string
if ($index == strlen($formula)) {
// Did we end with an operator?.
// Only valid for the % unary operator
if ((isset(self::CALCULATION_OPERATORS[$opCharacter])) && ($opCharacter != '%')) {
return $this->raiseFormulaError("Formula Error: Operator '$opCharacter' has no operands");
}
break;
}
// Ignore white space
while (($formula[$index] === "\n") || ($formula[$index] === "\r")) {
++$index;
}
if ($formula[$index] === ' ') {
while ($formula[$index] === ' ') {
++$index;
}
// If we're expecting an operator, but only have a space between the previous and next operands (and both are
// Cell References, Defined Names or Structured References) then we have an INTERSECTION operator
$countOutputMinus1 = count($output) - 1;
if (
($expectingOperator)
&& array_key_exists($countOutputMinus1, $output)
&& is_array($output[$countOutputMinus1])
&& array_key_exists('type', $output[$countOutputMinus1])
&& (
(preg_match('/^' . self::CALCULATION_REGEXP_CELLREF . '.*/miu', substr($formula, $index), $match))
&& ($output[$countOutputMinus1]['type'] === 'Cell Reference')
|| (preg_match('/^' . self::CALCULATION_REGEXP_DEFINEDNAME . '.*/miu', substr($formula, $index), $match))
&& ($output[$countOutputMinus1]['type'] === 'Defined Name' || $output[$countOutputMinus1]['type'] === 'Value')
|| (preg_match('/^' . self::CALCULATION_REGEXP_STRUCTURED_REFERENCE . '.*/miu', substr($formula, $index), $match))
&& ($output[$countOutputMinus1]['type'] === Operands\StructuredReference::NAME || $output[$countOutputMinus1]['type'] === 'Value')
)
) {
while (self::swapOperands($stack, $opCharacter)) {
$output[] = $stack->pop(); // Swap operands and higher precedence operators from the stack to the output
}
$stack->push('Binary Operator', '∩'); // Put an Intersect Operator on the stack
$expectingOperator = false;
}
}
}
while (($op = $stack->pop()) !== null) {
// pop everything off the stack and push onto output
if ($op['value'] == '(') {
return $this->raiseFormulaError("Formula Error: Expecting ')'"); // if there are any opening braces on the stack, then braces were unbalanced
}
$output[] = $op;
}
return $output;
}
/** @param mixed[] $operandData */
private static function dataTestReference(array &$operandData): mixed
{
$operand = $operandData['value'];
if (($operandData['reference'] === null) && (is_array($operand))) {
$rKeys = array_keys($operand);
$rowKey = array_shift($rKeys);
if (is_array($operand[$rowKey]) === false) {
$operandData['value'] = $operand[$rowKey];
return $operand[$rowKey];
}
$cKeys = array_keys(array_keys($operand[$rowKey]));
$colKey = array_shift($cKeys);
if (ctype_upper("$colKey")) {
$operandData['reference'] = $colKey . $rowKey;
}
}
return $operand;
}
private static int $matchIndex8 = 8;
private static int $matchIndex9 = 9;
private static int $matchIndex10 = 10;
/**
* @param array|false $tokens
*
* @return array|false|string
*/
private function processTokenStack(false|array $tokens, ?string $cellID = null, ?Cell $cell = null)
{
if ($tokens === false) {
return false;
}
$phpSpreadsheetFunctions = &self::getFunctionsAddress();
// If we're using cell caching, then $pCell may well be flushed back to the cache (which detaches the parent cell collection),
// so we store the parent cell collection so that we can re-attach it when necessary
$pCellWorksheet = ($cell !== null) ? $cell->getWorksheet() : null;
$originalCoordinate = $cell?->getCoordinate();
$pCellParent = ($cell !== null) ? $cell->getParent() : null;
$stack = new Stack($this->branchPruner);
// Stores branches that have been pruned
$fakedForBranchPruning = [];
// help us to know when pruning ['branchTestId' => true/false]
$branchStore = [];
// Loop through each token in turn
foreach ($tokens as $tokenIdx => $tokenData) {
/** @var mixed[] $tokenData */
$this->processingAnchorArray = false;
if ($tokenData['type'] === 'Cell Reference' && isset($tokens[$tokenIdx + 1]) && $tokens[$tokenIdx + 1]['type'] === 'Operand Count for Function ANCHORARRAY()') { //* @phpstan-ignore-line
$this->processingAnchorArray = true;
}
$token = $tokenData['value'];
// Branch pruning: skip useless resolutions
/** @var ?string */
$storeKey = $tokenData['storeKey'] ?? null;
if ($this->branchPruningEnabled && isset($tokenData['onlyIf'])) {
/** @var string */
$onlyIfStoreKey = $tokenData['onlyIf'];
$storeValue = $branchStore[$onlyIfStoreKey] ?? null;
$storeValueAsBool = ($storeValue === null)
? true : (bool) Functions::flattenSingleValue($storeValue);
if (is_array($storeValue)) {
$wrappedItem = end($storeValue);
$storeValue = is_array($wrappedItem) ? end($wrappedItem) : $wrappedItem;
}
if (
(isset($storeValue) || $tokenData['reference'] === 'NULL')
&& (!$storeValueAsBool || Information\ErrorValue::isError($storeValue) || ($storeValue === 'Pruned branch'))
) {
// If branching value is not true, we don't need to compute
/** @var string $onlyIfStoreKey */
if (!isset($fakedForBranchPruning['onlyIf-' . $onlyIfStoreKey])) {
/** @var string $token */
$stack->push('Value', 'Pruned branch (only if ' . $onlyIfStoreKey . ') ' . $token);
$fakedForBranchPruning['onlyIf-' . $onlyIfStoreKey] = true;
}
if (isset($storeKey)) {
// We are processing an if condition
// We cascade the pruning to the depending branches
$branchStore[$storeKey] = 'Pruned branch';
$fakedForBranchPruning['onlyIfNot-' . $storeKey] = true;
$fakedForBranchPruning['onlyIf-' . $storeKey] = true;
}
continue;
}
}
if ($this->branchPruningEnabled && isset($tokenData['onlyIfNot'])) {
/** @var string */
$onlyIfNotStoreKey = $tokenData['onlyIfNot'];
$storeValue = $branchStore[$onlyIfNotStoreKey] ?? null;
$storeValueAsBool = ($storeValue === null)
? true : (bool) Functions::flattenSingleValue($storeValue);
if (is_array($storeValue)) {
$wrappedItem = end($storeValue);
$storeValue = is_array($wrappedItem) ? end($wrappedItem) : $wrappedItem;
}
if (
(isset($storeValue) || $tokenData['reference'] === 'NULL')
&& ($storeValueAsBool || Information\ErrorValue::isError($storeValue) || ($storeValue === 'Pruned branch'))
) {
// If branching value is true, we don't need to compute
if (!isset($fakedForBranchPruning['onlyIfNot-' . $onlyIfNotStoreKey])) {
/** @var string $token */
$stack->push('Value', 'Pruned branch (only if not ' . $onlyIfNotStoreKey . ') ' . $token);
$fakedForBranchPruning['onlyIfNot-' . $onlyIfNotStoreKey] = true;
}
if (isset($storeKey)) {
// We are processing an if condition
// We cascade the pruning to the depending branches
$branchStore[$storeKey] = 'Pruned branch';
$fakedForBranchPruning['onlyIfNot-' . $storeKey] = true;
$fakedForBranchPruning['onlyIf-' . $storeKey] = true;
}
continue;
}
}
if ($token instanceof Operands\StructuredReference) {
if ($cell === null) {
return $this->raiseFormulaError('Structured References must exist in a Cell context');
}
try {
$cellRange = $token->parse($cell);
if (str_contains($cellRange, ':')) {
$this->debugLog->writeDebugLog('Evaluating Structured Reference %s as Cell Range %s', $token->value(), $cellRange);
$rangeValue = self::getInstance($cell->getWorksheet()->getParent())->_calculateFormulaValue("={$cellRange}", $cellRange, $cell);
$stack->push('Value', $rangeValue);
$this->debugLog->writeDebugLog('Evaluated Structured Reference %s as value %s', $token->value(), $this->showValue($rangeValue));
} else {
$this->debugLog->writeDebugLog('Evaluating Structured Reference %s as Cell %s', $token->value(), $cellRange);
$cellValue = $cell->getWorksheet()->getCell($cellRange)->getCalculatedValue(false);
$stack->push('Cell Reference', $cellValue, $cellRange);
$this->debugLog->writeDebugLog('Evaluated Structured Reference %s as value %s', $token->value(), $this->showValue($cellValue));
}
} catch (Exception $e) {
if ($e->getCode() === Exception::CALCULATION_ENGINE_PUSH_TO_STACK) {
$stack->push('Error', ExcelError::REF(), null);
$this->debugLog->writeDebugLog('Evaluated Structured Reference %s as error value %s', $token->value(), ExcelError::REF());
} else {
return $this->raiseFormulaError($e->getMessage(), $e->getCode(), $e);
}
}
} elseif (!is_numeric($token) && !is_object($token) && isset($token, self::BINARY_OPERATORS[$token])) { //* @phpstan-ignore-line
// if the token is a binary operator, pop the top two values off the stack, do the operation, and push the result back on the stack
// We must have two operands, error if we don't
$operand2Data = $stack->pop();
if ($operand2Data === null) {
return $this->raiseFormulaError('Internal error - Operand value missing from stack');
}
$operand1Data = $stack->pop();
if ($operand1Data === null) {
return $this->raiseFormulaError('Internal error - Operand value missing from stack');
}
$operand1 = self::dataTestReference($operand1Data);
$operand2 = self::dataTestReference($operand2Data);
// Log what we're doing
if ($token == ':') {
$this->debugLog->writeDebugLog('Evaluating Range %s %s %s', $this->showValue($operand1Data['reference']), $token, $this->showValue($operand2Data['reference']));
} else {
$this->debugLog->writeDebugLog('Evaluating %s %s %s', $this->showValue($operand1), $token, $this->showValue($operand2));
}
// Process the operation in the appropriate manner
switch ($token) {
// Comparison (Boolean) Operators
case '>': // Greater than
case '<': // Less than
case '>=': // Greater than or Equal to
case '<=': // Less than or Equal to
case '=': // Equality
case '<>': // Inequality
$result = $this->executeBinaryComparisonOperation($operand1, $operand2, (string) $token, $stack);
if (isset($storeKey)) {
$branchStore[$storeKey] = $result;
}
break;
// Binary Operators
case ':': // Range
if ($operand1Data['type'] === 'Error') {
$stack->push($operand1Data['type'], $operand1Data['value'], null);
break;
}
if ($operand2Data['type'] === 'Error') {
$stack->push($operand2Data['type'], $operand2Data['value'], null);
break;
}
if ($operand1Data['type'] === 'Defined Name') {
/** @var array{reference: string} $operand1Data */
if (preg_match('/$' . self::CALCULATION_REGEXP_DEFINEDNAME . '^/mui', $operand1Data['reference']) !== false && $this->spreadsheet !== null) {
/** @var string[] $operand1Data */
$definedName = $this->spreadsheet->getNamedRange($operand1Data['reference']);
if ($definedName !== null) {
$operand1Data['reference'] = $operand1Data['value'] = str_replace('$', '', $definedName->getValue());
}
}
}
/** @var array{reference?: ?string} $operand1Data */
if (str_contains($operand1Data['reference'] ?? '', '!')) {
[$sheet1, $operand1Data['reference']] = Worksheet::extractSheetTitle($operand1Data['reference'], true, true);
} else {
$sheet1 = ($pCellWorksheet !== null) ? $pCellWorksheet->getTitle() : '';
}
//$sheet1 ??= ''; // phpstan level 10 says this is unneeded
/** @var string */
$op2ref = $operand2Data['reference'];
[$sheet2, $operand2Data['reference']] = Worksheet::extractSheetTitle($op2ref, true, true);
if (empty($sheet2)) {
$sheet2 = $sheet1;
}
if ($sheet1 === $sheet2) {
/** @var array{reference: ?string, value: string|string[]} $operand1Data */
if ($operand1Data['reference'] === null && $cell !== null) {
if (is_array($operand1Data['value'])) {
$operand1Data['reference'] = $cell->getCoordinate();
} elseif ((trim($operand1Data['value']) != '') && (is_numeric($operand1Data['value']))) {
$operand1Data['reference'] = $cell->getColumn() . $operand1Data['value'];
} elseif (trim($operand1Data['value']) == '') {
$operand1Data['reference'] = $cell->getCoordinate();
} else {
$operand1Data['reference'] = $operand1Data['value'] . $cell->getRow();
}
}
/** @var array{reference: ?string, value: string|string[]} $operand2Data */
if ($operand2Data['reference'] === null && $cell !== null) {
if (is_array($operand2Data['value'])) {
$operand2Data['reference'] = $cell->getCoordinate();
} elseif ((trim($operand2Data['value']) != '') && (is_numeric($operand2Data['value']))) {
$operand2Data['reference'] = $cell->getColumn() . $operand2Data['value'];
} elseif (trim($operand2Data['value']) == '') {
$operand2Data['reference'] = $cell->getCoordinate();
} else {
$operand2Data['reference'] = $operand2Data['value'] . $cell->getRow();
}
}
$oData = array_merge(explode(':', $operand1Data['reference'] ?? ''), explode(':', $operand2Data['reference'] ?? ''));
$oCol = $oRow = [];
$breakNeeded = false;
foreach ($oData as $oDatum) {
try {
$oCR = Coordinate::coordinateFromString($oDatum);
$oCol[] = Coordinate::columnIndexFromString($oCR[0]) - 1;
$oRow[] = $oCR[1];
} catch (\Exception) {
$stack->push('Error', ExcelError::REF(), null);
$breakNeeded = true;
break;
}
}
if ($breakNeeded) {
break;
}
$cellRef = Coordinate::stringFromColumnIndex(min($oCol) + 1) . min($oRow) . ':' . Coordinate::stringFromColumnIndex(max($oCol) + 1) . max($oRow); // @phpstan-ignore-line
if ($pCellParent !== null && $this->spreadsheet !== null) {
$cellValue = $this->extractCellRange($cellRef, $this->spreadsheet->getSheetByName($sheet1), false);
} else {
return $this->raiseFormulaError('Unable to access Cell Reference');
}
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($cellValue));
$stack->push('Cell Reference', $cellValue, $cellRef);
} else {
$this->debugLog->writeDebugLog('Evaluation Result is a #REF! Error');
$stack->push('Error', ExcelError::REF(), null);
}
break;
case '+': // Addition
case '-': // Subtraction
case '*': // Multiplication
case '/': // Division
case '^': // Exponential
$result = $this->executeNumericBinaryOperation($operand1, $operand2, $token, $stack);
if (isset($storeKey)) {
$branchStore[$storeKey] = $result;
}
break;
case '&': // Concatenation
// If either of the operands is a matrix, we need to treat them both as matrices
// (converting the other operand to a matrix if need be); then perform the required
// matrix operation
$operand1 = self::boolToString($operand1);
$operand2 = self::boolToString($operand2);
if (is_array($operand1) || is_array($operand2)) {
if (is_string($operand1)) {
$operand1 = self::unwrapResult($operand1);
}
if (is_string($operand2)) {
$operand2 = self::unwrapResult($operand2);
}
// Ensure that both operands are arrays/matrices
[$rows, $columns] = self::checkMatrixOperands($operand1, $operand2, 2);
for ($row = 0; $row < $rows; ++$row) {
for ($column = 0; $column < $columns; ++$column) {
/** @var mixed[][] $operand1 */
$op1x = self::boolToString($operand1[$row][$column]);
/** @var mixed[][] $operand2 */
$op2x = self::boolToString($operand2[$row][$column]);
if (Information\ErrorValue::isError($op1x)) {
// no need to do anything
} elseif (Information\ErrorValue::isError($op2x)) {
$operand1[$row][$column] = $op2x;
} else {
/** @var string $op1x */
/** @var string $op2x */
$operand1[$row][$column]
= StringHelper::substring(
$op1x . $op2x,
0,
DataType::MAX_STRING_LENGTH
);
}
}
}
$result = $operand1;
} else {
if (Information\ErrorValue::isError($operand1)) {
$result = $operand1;
} elseif (Information\ErrorValue::isError($operand2)) {
$result = $operand2;
} else {
$result = str_replace('""', self::FORMULA_STRING_QUOTE, self::unwrapResult($operand1) . self::unwrapResult($operand2)); //* @phpstan-ignore-line
$result = StringHelper::substring(
$result,
0,
DataType::MAX_STRING_LENGTH
);
$result = self::FORMULA_STRING_QUOTE . $result . self::FORMULA_STRING_QUOTE;
}
}
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($result));
$stack->push('Value', $result);
if (isset($storeKey)) {
$branchStore[$storeKey] = $result;
}
break;
case '∩': // Intersect
/** @var mixed[][] $operand1 */
/** @var mixed[][] $operand2 */
$rowIntersect = array_intersect_key($operand1, $operand2);
$cellIntersect = $oCol = $oRow = [];
foreach (array_keys($rowIntersect) as $row) {
$oRow[] = $row;
foreach ($rowIntersect[$row] as $col => $data) {
$oCol[] = Coordinate::columnIndexFromString($col) - 1;
$cellIntersect[$row] = array_intersect_key($operand1[$row], $operand2[$row]);
}
}
if (count(Functions::flattenArray($cellIntersect)) === 0) {
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($cellIntersect));
$stack->push('Error', ExcelError::null(), null);
} else {
$cellRef = Coordinate::stringFromColumnIndex(min($oCol) + 1) . min($oRow) . ':' // @phpstan-ignore-line
. Coordinate::stringFromColumnIndex(max($oCol) + 1) . max($oRow); // @phpstan-ignore-line
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($cellIntersect));
$stack->push('Value', $cellIntersect, $cellRef);
}
break;
case '∪': // union
/** @var mixed[][] $operand1 */
/** @var mixed[][] $operand2 */
$cellUnion = array_merge($operand1, $operand2);
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($cellUnion));
$stack->push('Value', $cellUnion, 'A1');
break;
}
} elseif (($token === '~') || ($token === '%')) {
// if the token is a unary operator, pop one value off the stack, do the operation, and push it back on
if (($arg = $stack->pop()) === null) {
return $this->raiseFormulaError('Internal error - Operand value missing from stack');
}
$arg = $arg['value'];
if ($token === '~') {
$this->debugLog->writeDebugLog('Evaluating Negation of %s', $this->showValue($arg));
$multiplier = -1;
} else {
$this->debugLog->writeDebugLog('Evaluating Percentile of %s', $this->showValue($arg));
$multiplier = 0.01;
}
if (is_array($arg)) {
$operand2 = $multiplier;
$result = $arg;
[$rows, $columns] = self::checkMatrixOperands($result, $operand2, 0);
for ($row = 0; $row < $rows; ++$row) {
for ($column = 0; $column < $columns; ++$column) {
/** @var mixed[][] $result */
if (self::isNumericOrBool($result[$row][$column])) {
/** @var float|int|numeric-string */
$temp = $result[$row][$column];
$result[$row][$column] = $temp * $multiplier;
} else {
$result[$row][$column] = self::makeError($result[$row][$column]);
}
}
}
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($result));
$stack->push('Value', $result);
if (isset($storeKey)) {
$branchStore[$storeKey] = $result;
}
} else {
$this->executeNumericBinaryOperation($multiplier, $arg, '*', $stack);
}
} elseif (Preg::isMatch('/^' . self::CALCULATION_REGEXP_CELLREF . '$/i', StringHelper::convertToString($token ?? ''), $matches)) {
$cellRef = null;
/* Phpstan says matches[8/9/10] is never set,
and code coverage report seems to confirm.
regex101.com confirms - only 7 capturing groups.
My theory is that this code expected regexp to
match cell *or* cellRange, but it does not
match the latter. Retain the code for now in case
we do want to add the range match later.
Probably delete this block later.
Until delete happens, turn code coverage off.
*/
if (isset($matches[self::$matchIndex8])) {
// @codeCoverageIgnoreStart
if ($cell === null) {
// We can't access the range, so return a REF error
$cellValue = ExcelError::REF();
} else {
$cellRef = $matches[6] . $matches[7] . ':' . $matches[self::$matchIndex9] . $matches[self::$matchIndex10];
$matches[2] = (string) $matches[2];
if ($matches[2] > '') {
$matches[2] = trim($matches[2], "\"'");
if ((str_contains($matches[2], '[')) || (str_contains($matches[2], ']'))) {
// It's a Reference to an external spreadsheet (not currently supported)
return $this->raiseFormulaError('Unable to access External Workbook');
}
$matches[2] = trim($matches[2], "\"'");
$this->debugLog->writeDebugLog('Evaluating Cell Range %s in worksheet %s', $cellRef, $matches[2]);
if ($pCellParent !== null && $this->spreadsheet !== null) {
$cellValue = $this->extractCellRange($cellRef, $this->spreadsheet->getSheetByName($matches[2]), false);
} else {
return $this->raiseFormulaError('Unable to access Cell Reference');
}
$this->debugLog->writeDebugLog('Evaluation Result for cells %s in worksheet %s is %s', $cellRef, $matches[2], $this->showTypeDetails($cellValue));
} else {
$this->debugLog->writeDebugLog('Evaluating Cell Range %s in current worksheet', $cellRef);
if ($pCellParent !== null) {
$cellValue = $this->extractCellRange($cellRef, $pCellWorksheet, false);
} else {
return $this->raiseFormulaError('Unable to access Cell Reference');
}
$this->debugLog->writeDebugLog('Evaluation Result for cells %s is %s', $cellRef, $this->showTypeDetails($cellValue));
}
}
// @codeCoverageIgnoreEnd
} else {
if ($cell === null) {
// We can't access the cell, so return a REF error
$cellValue = ExcelError::REF();
} else {
$cellRef = $matches[6] . $matches[7];
$matches[2] = (string) $matches[2];
if ($matches[2] > '') {
$matches[2] = trim($matches[2], "\"'");
if ((str_contains($matches[2], '[')) || (str_contains($matches[2], ']'))) {
// It's a Reference to an external spreadsheet (not currently supported)
return $this->raiseFormulaError('Unable to access External Workbook');
}
$this->debugLog->writeDebugLog('Evaluating Cell %s in worksheet %s', $cellRef, $matches[2]);
if ($pCellParent !== null && $this->spreadsheet !== null) {
$cellSheet = $this->spreadsheet->getSheetByName($matches[2]);
if ($cellSheet && !$cellSheet->cellExists($cellRef)) {
try {
$cellSheet->setCellValue($cellRef, null);
} catch (SpreadsheetException) {
// do nothing
}
}
if ($cellSheet && $cellSheet->cellExists($cellRef)) {
$cellValue = $this->extractCellRange($cellRef, $this->spreadsheet->getSheetByName($matches[2]), false);
$cell->attach($pCellParent);
} else {
$cellRef = ($cellSheet !== null) ? "'{$matches[2]}'!{$cellRef}" : $cellRef;
$cellValue = ($cellSheet !== null) ? null : ExcelError::REF();
}
} else {
return $this->raiseFormulaError('Unable to access Cell Reference');
}
$this->debugLog->writeDebugLog('Evaluation Result for cell %s in worksheet %s is %s', $cellRef, $matches[2], $this->showTypeDetails($cellValue));
} else {
$this->debugLog->writeDebugLog('Evaluating Cell %s in current worksheet', $cellRef);
if ($pCellParent !== null && $pCellParent->has($cellRef)) {
$cellValue = $this->extractCellRange($cellRef, $pCellWorksheet, false);
$cell->attach($pCellParent);
} else {
$cellValue = null;
}
$this->debugLog->writeDebugLog('Evaluation Result for cell %s is %s', $cellRef, $this->showTypeDetails($cellValue));
}
}
}
if ($this->getInstanceArrayReturnType() === self::RETURN_ARRAY_AS_ARRAY && !$this->processingAnchorArray && is_array($cellValue)) {
while (is_array($cellValue)) {
$cellValue = array_shift($cellValue);
}
if (is_string($cellValue)) {
$cellValue = Preg::replace('/"/', '""', $cellValue);
}
$this->debugLog->writeDebugLog('Scalar Result for cell %s is %s', $cellRef, $this->showTypeDetails($cellValue));
}
$this->processingAnchorArray = false;
$stack->push('Cell Value', $cellValue, $cellRef);
if (isset($storeKey)) {
$branchStore[$storeKey] = $cellValue;
}
} elseif (preg_match('/^' . self::CALCULATION_REGEXP_FUNCTION . '$/miu', StringHelper::convertToString($token ?? ''), $matches)) {
// if the token is a function, pop arguments off the stack, hand them to the function, and push the result back on
if ($cell !== null && $pCellParent !== null) {
$cell->attach($pCellParent);
}
$functionName = $matches[1];
/** @var array $argCount */
$argCount = $stack->pop();
$argCount = $argCount['value'];
if ($functionName !== 'MKMATRIX') {
$this->debugLog->writeDebugLog('Evaluating Function %s() with %s argument%s', self::localeFunc($functionName), (($argCount == 0) ? 'no' : $argCount), (($argCount == 1) ? '' : 's'));
}
if ((isset($phpSpreadsheetFunctions[$functionName])) || (isset(self::$controlFunctions[$functionName]))) { // function
$passByReference = false;
$passCellReference = false;
$functionCall = null;
if (isset($phpSpreadsheetFunctions[$functionName])) {
$functionCall = $phpSpreadsheetFunctions[$functionName]['functionCall'];
$passByReference = isset($phpSpreadsheetFunctions[$functionName]['passByReference']);
$passCellReference = isset($phpSpreadsheetFunctions[$functionName]['passCellReference']);
} elseif (isset(self::$controlFunctions[$functionName])) {
$functionCall = self::$controlFunctions[$functionName]['functionCall'];
$passByReference = isset(self::$controlFunctions[$functionName]['passByReference']);
$passCellReference = isset(self::$controlFunctions[$functionName]['passCellReference']);
}
// get the arguments for this function
$args = $argArrayVals = [];
$emptyArguments = [];
for ($i = 0; $i < $argCount; ++$i) {
$arg = $stack->pop();
$a = $argCount - $i - 1;
if (
($passByReference)
&& (isset($phpSpreadsheetFunctions[$functionName]['passByReference'][$a])) //* @phpstan-ignore-line
&& ($phpSpreadsheetFunctions[$functionName]['passByReference'][$a])
) {
/** @var mixed[] $arg */
if ($arg['reference'] === null) {
$nextArg = $cellID;
if ($functionName === 'ISREF' && ($arg['type'] ?? '') === 'Value') {
if (array_key_exists('value', $arg)) {
$argValue = $arg['value'];
if (is_scalar($argValue)) {
$nextArg = $argValue;
} elseif (empty($argValue)) {
$nextArg = '';
}
}
} elseif (($arg['type'] ?? '') === 'Error') {
$argValue = $arg['value'];
if (is_scalar($argValue)) {
$nextArg = $argValue;
} elseif (empty($argValue)) {
$nextArg = '';
}
}
$args[] = $nextArg;
if ($functionName !== 'MKMATRIX') {
$argArrayVals[] = $this->showValue($cellID);
}
} else {
$args[] = $arg['reference'];
if ($functionName !== 'MKMATRIX') {
$argArrayVals[] = $this->showValue($arg['reference']);
}
}
} else {
/** @var mixed[] $arg */
if ($arg['type'] === 'Empty Argument' && in_array($functionName, ['MIN', 'MINA', 'MAX', 'MAXA', 'IF'], true)) {
$emptyArguments[] = false;
$args[] = $arg['value'] = 0;
$this->debugLog->writeDebugLog('Empty Argument reevaluated as 0');
} else {
$emptyArguments[] = $arg['type'] === 'Empty Argument';
$args[] = self::unwrapResult($arg['value']);
}
if ($functionName !== 'MKMATRIX') {
$argArrayVals[] = $this->showValue($arg['value']);
}
}
}
// Reverse the order of the arguments
krsort($args);
krsort($emptyArguments);
if ($argCount > 0 && is_array($functionCall)) {
/** @var string[] */
$functionCallCopy = $functionCall;
$args = $this->addDefaultArgumentValues($functionCallCopy, $args, $emptyArguments);
}
if (($passByReference) && ($argCount == 0)) {
$args[] = $cellID;
$argArrayVals[] = $this->showValue($cellID);
}
if ($functionName !== 'MKMATRIX') {
if ($this->debugLog->getWriteDebugLog()) {
krsort($argArrayVals);
$this->debugLog->writeDebugLog('Evaluating %s ( %s )', self::localeFunc($functionName), implode(self::$localeArgumentSeparator . ' ', Functions::flattenArray($argArrayVals)));
}
}
// Process the argument with the appropriate function call
if ($pCellWorksheet !== null && $originalCoordinate !== null) {
$pCellWorksheet->getCell($originalCoordinate);
}
/** @var array|string $functionCall */
$args = $this->addCellReference($args, $passCellReference, $functionCall, $cell);
if (!is_array($functionCall)) {
foreach ($args as &$arg) {
$arg = Functions::flattenSingleValue($arg);
}
unset($arg);
}
/** @var callable $functionCall */
try {
$result = call_user_func_array($functionCall, $args);
} catch (TypeError $e) {
if (!$this->suppressFormulaErrors) {
throw $e;
}
$result = false;
}
if ($functionName !== 'MKMATRIX') {
$this->debugLog->writeDebugLog('Evaluation Result for %s() function call is %s', self::localeFunc($functionName), $this->showTypeDetails($result));
}
$stack->push('Value', self::wrapResult($result));
if (isset($storeKey)) {
$branchStore[$storeKey] = $result;
}
}
} else {
// if the token is a number, boolean, string or an Excel error, push it onto the stack
/** @var ?string $token */
if (isset(self::EXCEL_CONSTANTS[strtoupper($token ?? '')])) {
$excelConstant = strtoupper("$token");
$stack->push('Constant Value', self::EXCEL_CONSTANTS[$excelConstant]);
if (isset($storeKey)) {
$branchStore[$storeKey] = self::EXCEL_CONSTANTS[$excelConstant];
}
$this->debugLog->writeDebugLog('Evaluating Constant %s as %s', $excelConstant, $this->showTypeDetails(self::EXCEL_CONSTANTS[$excelConstant]));
} elseif ((is_numeric($token)) || ($token === null) || (is_bool($token)) || ($token == '') || ($token[0] == self::FORMULA_STRING_QUOTE) || ($token[0] == '#')) { //* @phpstan-ignore-line
/** @var array{type: string, reference: ?string} $tokenData */
$stack->push($tokenData['type'], $token, $tokenData['reference']);
if (isset($storeKey)) {
$branchStore[$storeKey] = $token;
}
} elseif (preg_match('/^' . self::CALCULATION_REGEXP_DEFINEDNAME . '$/miu', $token, $matches)) {
// if the token is a named range or formula, evaluate it and push the result onto the stack
$definedName = $matches[6];
if (str_starts_with($definedName, '_xleta')) {
return Functions::NOT_YET_IMPLEMENTED;
}
if ($cell === null || $pCellWorksheet === null) {
return $this->raiseFormulaError("undefined name '$token'");
}
$specifiedWorksheet = trim($matches[2], "'");
$this->debugLog->writeDebugLog('Evaluating Defined Name %s', $definedName);
$namedRange = DefinedName::resolveName($definedName, $pCellWorksheet, $specifiedWorksheet);
// If not Defined Name, try as Table.
if ($namedRange === null && $this->spreadsheet !== null) {
$table = $this->spreadsheet->getTableByName($definedName);
if ($table !== null) {
$tableRange = Coordinate::getRangeBoundaries($table->getRange());
if ($table->getShowHeaderRow()) {
++$tableRange[0][1];
}
if ($table->getShowTotalsRow()) {
--$tableRange[1][1];
}
$tableRangeString
= '$' . $tableRange[0][0]
. '$' . $tableRange[0][1]
. ':'
. '$' . $tableRange[1][0]
. '$' . $tableRange[1][1];
$namedRange = new NamedRange($definedName, $table->getWorksheet(), $tableRangeString);
}
}
if ($namedRange === null) {
$result = ExcelError::NAME();
$stack->push('Error', $result, null);
$this->debugLog->writeDebugLog("Error $result");
} else {
$result = $this->evaluateDefinedName($cell, $namedRange, $pCellWorksheet, $stack, $specifiedWorksheet !== '');
}
if (isset($storeKey)) {
$branchStore[$storeKey] = $result;
}
} else {
return $this->raiseFormulaError("undefined name '$token'");
}
}
}
// when we're out of tokens, the stack should have a single element, the final result
if ($stack->count() != 1) {
return $this->raiseFormulaError('internal error');
}
/** @var array|false|string> */
$output = $stack->pop();
$output = $output['value'];
return $output;
}
private function validateBinaryOperand(mixed &$operand, Stack &$stack): bool
{
if (is_array($operand)) {
if ((count($operand, COUNT_RECURSIVE) - count($operand)) == 1) {
do {
$operand = array_pop($operand);
} while (is_array($operand));
}
}
// Numbers, matrices and booleans can pass straight through, as they're already valid
if (is_string($operand)) {
// We only need special validations for the operand if it is a string
// Start by stripping off the quotation marks we use to identify true excel string values internally
if ($operand > '' && $operand[0] == self::FORMULA_STRING_QUOTE) {
$operand = StringHelper::convertToString(self::unwrapResult($operand));
}
// If the string is a numeric value, we treat it as a numeric, so no further testing
if (!is_numeric($operand)) {
// If not a numeric, test to see if the value is an Excel error, and so can't be used in normal binary operations
if ($operand > '' && $operand[0] == '#') {
$stack->push('Value', $operand);
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($operand));
return false;
} elseif (Engine\FormattedNumber::convertToNumberIfFormatted($operand) === false) {
// If not a numeric, a fraction or a percentage, then it's a text string, and so can't be used in mathematical binary operations
$stack->push('Error', '#VALUE!');
$this->debugLog->writeDebugLog('Evaluation Result is a %s', $this->showTypeDetails('#VALUE!'));
return false;
}
}
}
// return a true if the value of the operand is one that we can use in normal binary mathematical operations
return true;
}
/** @return mixed[] */
private function executeArrayComparison(mixed $operand1, mixed $operand2, string $operation, Stack &$stack, bool $recursingArrays): array
{
$result = [];
if (!is_array($operand2) && is_array($operand1)) {
// Operand 1 is an array, Operand 2 is a scalar
foreach ($operand1 as $x => $operandData) {
$this->debugLog->writeDebugLog('Evaluating Comparison %s %s %s', $this->showValue($operandData), $operation, $this->showValue($operand2));
$this->executeBinaryComparisonOperation($operandData, $operand2, $operation, $stack);
/** @var array $r */
$r = $stack->pop();
$result[$x] = $r['value'];
}
} elseif (is_array($operand2) && !is_array($operand1)) {
// Operand 1 is a scalar, Operand 2 is an array
foreach ($operand2 as $x => $operandData) {
$this->debugLog->writeDebugLog('Evaluating Comparison %s %s %s', $this->showValue($operand1), $operation, $this->showValue($operandData));
$this->executeBinaryComparisonOperation($operand1, $operandData, $operation, $stack);
/** @var array $r */
$r = $stack->pop();
$result[$x] = $r['value'];
}
} elseif (is_array($operand2) && is_array($operand1)) {
// Operand 1 and Operand 2 are both arrays
if (!$recursingArrays) {
self::checkMatrixOperands($operand1, $operand2, 2);
}
foreach ($operand1 as $x => $operandData) {
$this->debugLog->writeDebugLog('Evaluating Comparison %s %s %s', $this->showValue($operandData), $operation, $this->showValue($operand2[$x]));
$this->executeBinaryComparisonOperation($operandData, $operand2[$x], $operation, $stack, true);
/** @var array $r */
$r = $stack->pop();
$result[$x] = $r['value'];
}
} else {
throw new Exception('Neither operand is an arra');
}
// Log the result details
$this->debugLog->writeDebugLog('Comparison Evaluation Result is %s', $this->showTypeDetails($result));
// And push the result onto the stack
$stack->push('Array', $result);
return $result;
}
/** @return array|bool|string */
private function executeBinaryComparisonOperation(mixed $operand1, mixed $operand2, string $operation, Stack &$stack, bool $recursingArrays = false): array|bool|string
{
// If we're dealing with matrix operations, we want a matrix result
if ((is_array($operand1)) || (is_array($operand2))) {
return $this->executeArrayComparison($operand1, $operand2, $operation, $stack, $recursingArrays);
}
$result = BinaryComparison::compare($operand1, $operand2, $operation);
// Log the result details
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($result));
// And push the result onto the stack
$stack->push('Value', $result);
return $result;
}
private function executeNumericBinaryOperation(mixed $operand1, mixed $operand2, string $operation, Stack &$stack): mixed
{
// Validate the two operands
if (
($this->validateBinaryOperand($operand1, $stack) === false)
|| ($this->validateBinaryOperand($operand2, $stack) === false)
) {
return false;
}
if (
(Functions::getCompatibilityMode() != Functions::COMPATIBILITY_OPENOFFICE)
&& ((is_string($operand1) && !is_numeric($operand1) && $operand1 !== '')
|| (is_string($operand2) && !is_numeric($operand2) && $operand2 !== ''))
) {
$result = ExcelError::VALUE();
} elseif (is_array($operand1) || is_array($operand2)) {
// Ensure that both operands are arrays/matrices
if (is_array($operand1)) {
foreach ($operand1 as $key => $value) {
$operand1[$key] = Functions::flattenArray($value);
}
}
if (is_array($operand2)) {
foreach ($operand2 as $key => $value) {
$operand2[$key] = Functions::flattenArray($value);
}
}
[$rows, $columns] = self::checkMatrixOperands($operand1, $operand2, 3);
for ($row = 0; $row < $rows; ++$row) {
for ($column = 0; $column < $columns; ++$column) {
/** @var mixed[][] $operand1 */
if (($operand1[$row][$column] ?? null) === null) {
$operand1[$row][$column] = 0;
} elseif (!self::isNumericOrBool($operand1[$row][$column])) {
$operand1[$row][$column] = self::makeError($operand1[$row][$column]);
continue;
}
/** @var mixed[][] $operand2 */
if (($operand2[$row][$column] ?? null) === null) {
$operand2[$row][$column] = 0;
} elseif (!self::isNumericOrBool($operand2[$row][$column])) {
$operand1[$row][$column] = self::makeError($operand2[$row][$column]);
continue;
}
/** @var float|int */
$operand1Val = $operand1[$row][$column];
/** @var float|int */
$operand2Val = $operand2[$row][$column];
switch ($operation) {
case '+':
$operand1[$row][$column] = $operand1Val + $operand2Val;
break;
case '-':
$operand1[$row][$column] = $operand1Val - $operand2Val;
break;
case '*':
$operand1[$row][$column] = $operand1Val * $operand2Val;
break;
case '/':
if ($operand2Val == 0) {
$operand1[$row][$column] = ExcelError::DIV0();
} else {
$operand1[$row][$column] = $operand1Val / $operand2Val;
}
break;
case '^':
$operand1[$row][$column] = $operand1Val ** $operand2Val;
break;
default:
throw new Exception('Unsupported numeric binary operation');
}
}
}
$result = $operand1;
} else {
// If we're dealing with non-matrix operations, execute the necessary operation
/** @var float|int $operand1 */
/** @var float|int $operand2 */
switch ($operation) {
// Addition
case '+':
$result = $operand1 + $operand2;
break;
// Subtraction
case '-':
$result = $operand1 - $operand2;
break;
// Multiplication
case '*':
$result = $operand1 * $operand2;
break;
// Division
case '/':
if ($operand2 == 0) {
// Trap for Divide by Zero error
$stack->push('Error', ExcelError::DIV0());
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails(ExcelError::DIV0()));
return false;
}
$result = $operand1 / $operand2;
break;
// Power
case '^':
$result = $operand1 ** $operand2;
break;
default:
throw new Exception('Unsupported numeric binary operation');
}
}
// Log the result details
$this->debugLog->writeDebugLog('Evaluation Result is %s', $this->showTypeDetails($result));
// And push the result onto the stack
$stack->push('Value', $result);
return $result;
}
/**
* Trigger an error, but nicely, if need be.
*
* @return false
*/
protected function raiseFormulaError(string $errorMessage, int $code = 0, ?Throwable $exception = null): bool
{
$this->formulaError = $errorMessage;
$this->cyclicReferenceStack->clear();
$suppress = $this->suppressFormulaErrors;
$suppressed = $suppress ? ' $suppressed' : '';
$this->debugLog->writeDebugLog("Raise Error$suppressed $errorMessage");
if (!$suppress) {
throw new Exception($errorMessage, $code, $exception);
}
return false;
}
/**
* Extract range values.
*
* @param string $range String based range representation
* @param ?Worksheet $worksheet Worksheet
* @param bool $resetLog Flag indicating whether calculation log should be reset or not
*
* @return mixed[] Array of values in range if range contains more than one element. Otherwise, a single value is returned.
*/
public function extractCellRange(string &$range = 'A1', ?Worksheet $worksheet = null, bool $resetLog = true, bool $createCell = false): array
{
// Return value
/** @var mixed[][] */
$returnValue = [];
if ($worksheet !== null) {
$worksheetName = $worksheet->getTitle();
if (str_contains($range, '!')) {
[$worksheetName, $range] = Worksheet::extractSheetTitle($range, true, true);
$worksheet = ($this->spreadsheet === null) ? null : $this->spreadsheet->getSheetByName($worksheetName);
}
// Extract range
$aReferences = Coordinate::extractAllCellReferencesInRange($range);
$range = "'" . $worksheetName . "'" . '!' . $range;
$currentCol = '';
$currentRow = 0;
if (!isset($aReferences[1])) {
// Single cell in range
sscanf($aReferences[0], '%[A-Z]%d', $currentCol, $currentRow);
/** @var string $currentCol */
/** @var int $currentRow */
if ($createCell && $worksheet !== null && !$worksheet->cellExists($aReferences[0])) {
$worksheet->setCellValue($aReferences[0], null);
}
if ($worksheet !== null && $worksheet->cellExists($aReferences[0])) {
$temp = $worksheet->getCell($aReferences[0])->getCalculatedValue($resetLog);
if ($this->getInstanceArrayReturnType() === self::RETURN_ARRAY_AS_ARRAY) {
while (is_array($temp)) {
$temp = array_shift($temp);
}
}
$returnValue[$currentRow][$currentCol] = $temp;
} else {
$returnValue[$currentRow][$currentCol] = null;
}
} else {
// Extract cell data for all cells in the range
foreach ($aReferences as $reference) {
// Extract range
sscanf($reference, '%[A-Z]%d', $currentCol, $currentRow);
/** @var string $currentCol */
/** @var int $currentRow */
if ($createCell && $worksheet !== null && !$worksheet->cellExists($reference)) {
$worksheet->setCellValue($reference, null);
}
if ($worksheet !== null && $worksheet->cellExists($reference)) {
$temp = $worksheet->getCell($reference)->getCalculatedValue($resetLog);
if ($this->getInstanceArrayReturnType() === self::RETURN_ARRAY_AS_ARRAY) {
while (is_array($temp)) {
$temp = array_shift($temp);
}
}
$returnValue[$currentRow][$currentCol] = $temp;
} else {
$returnValue[$currentRow][$currentCol] = null;
}
}
}
}
return $returnValue;
}
/**
* Extract range values.
*
* @param string $range String based range representation
* @param null|Worksheet $worksheet Worksheet
* @param bool $resetLog Flag indicating whether calculation log should be reset or not
*
* @return mixed[]|string Array of values in range if range contains more than one element. Otherwise, a single value is returned.
*/
public function extractNamedRange(string &$range = 'A1', ?Worksheet $worksheet = null, bool $resetLog = true): string|array
{
// Return value
$returnValue = [];
if ($worksheet !== null) {
if (str_contains($range, '!')) {
[$worksheetName, $range] = Worksheet::extractSheetTitle($range, true, true);
$worksheet = ($this->spreadsheet === null) ? null : $this->spreadsheet->getSheetByName($worksheetName);
}
// Named range?
$namedRange = ($worksheet === null) ? null : DefinedName::resolveName($range, $worksheet);
if ($namedRange === null) {
return ExcelError::REF();
}
$worksheet = $namedRange->getWorksheet();
$range = $namedRange->getValue();
$splitRange = Coordinate::splitRange($range);
// Convert row and column references
if ($worksheet !== null && ctype_alpha($splitRange[0][0])) {
$range = $splitRange[0][0] . '1:' . $splitRange[0][1] . $worksheet->getHighestRow();
} elseif ($worksheet !== null && ctype_digit($splitRange[0][0])) {
$range = 'A' . $splitRange[0][0] . ':' . $worksheet->getHighestColumn() . $splitRange[0][1];
}
// Extract range
$aReferences = Coordinate::extractAllCellReferencesInRange($range);
if (!isset($aReferences[1])) {
// Single cell (or single column or row) in range
[$currentCol, $currentRow] = Coordinate::coordinateFromString($aReferences[0]);
/** @var mixed[][] $returnValue */
if ($worksheet !== null && $worksheet->cellExists($aReferences[0])) {
$returnValue[$currentRow][$currentCol] = $worksheet->getCell($aReferences[0])->getCalculatedValue($resetLog);
} else {
$returnValue[$currentRow][$currentCol] = null;
}
} else {
// Extract cell data for all cells in the range
foreach ($aReferences as $reference) {
// Extract range
[$currentCol, $currentRow] = Coordinate::coordinateFromString($reference);
if ($worksheet !== null && $worksheet->cellExists($reference)) {
$returnValue[$currentRow][$currentCol] = $worksheet->getCell($reference)->getCalculatedValue($resetLog);
} else {
$returnValue[$currentRow][$currentCol] = null;
}
}
}
}
return $returnValue;
}
/**
* Is a specific function implemented?
*
* @param string $function Function Name
*/
public function isImplemented(string $function): bool
{
$function = strtoupper($function);
$phpSpreadsheetFunctions = &self::getFunctionsAddress();
$notImplemented = !isset($phpSpreadsheetFunctions[$function]) || (is_array($phpSpreadsheetFunctions[$function]['functionCall']) && $phpSpreadsheetFunctions[$function]['functionCall'][1] === 'DUMMY');
return !$notImplemented;
}
/**
* Get a list of implemented Excel function names.
*
* @return string[]
*/
public function getImplementedFunctionNames(): array
{
$returnValue = [];
$phpSpreadsheetFunctions = &self::getFunctionsAddress();
foreach ($phpSpreadsheetFunctions as $functionName => $function) {
if ($this->isImplemented($functionName)) {
$returnValue[] = $functionName;
}
}
return $returnValue;
}
/**
* @param string[] $functionCall
* @param mixed[] $args
* @param mixed[] $emptyArguments
*
* @return mixed[]
*/
private function addDefaultArgumentValues(array $functionCall, array $args, array $emptyArguments): array
{
$reflector = new ReflectionMethod($functionCall[0], $functionCall[1]);
$methodArguments = $reflector->getParameters();
if (count($methodArguments) > 0) {
// Apply any defaults for empty argument values
foreach ($emptyArguments as $argumentId => $isArgumentEmpty) {
if ($isArgumentEmpty === true) {
$reflectedArgumentId = count($args) - (int) $argumentId - 1;
if (
!array_key_exists($reflectedArgumentId, $methodArguments)
|| $methodArguments[$reflectedArgumentId]->isVariadic()
) {
break;
}
$args[$argumentId] = $this->getArgumentDefaultValue($methodArguments[$reflectedArgumentId]);
}
}
}
return $args;
}
private function getArgumentDefaultValue(ReflectionParameter $methodArgument): mixed
{
$defaultValue = null;
if ($methodArgument->isDefaultValueAvailable()) {
$defaultValue = $methodArgument->getDefaultValue();
if ($methodArgument->isDefaultValueConstant()) {
$constantName = $methodArgument->getDefaultValueConstantName() ?? '';
// read constant value
if (str_contains($constantName, '::')) {
[$className, $constantName] = explode('::', $constantName);
/** @var class-string $className */
$constantReflector = new ReflectionClassConstant($className, $constantName);
return $constantReflector->getValue();
}
return constant($constantName);
}
}
return $defaultValue;
}
/**
* Add cell reference if needed while making sure that it is the last argument.
*
* @param mixed[] $args
* @param string|string[] $functionCall
*
* @return mixed[]
*/
private function addCellReference(array $args, bool $passCellReference, array|string $functionCall, ?Cell $cell = null): array
{
if ($passCellReference) {
if (is_array($functionCall)) {
$className = $functionCall[0];
$methodName = $functionCall[1];
$reflectionMethod = new ReflectionMethod($className, $methodName);
$argumentCount = count($reflectionMethod->getParameters());
while (count($args) < $argumentCount - 1) {
$args[] = null;
}
}
$args[] = $cell;
}
return $args;
}
private function evaluateDefinedName(Cell $cell, DefinedName $namedRange, Worksheet $cellWorksheet, Stack $stack, bool $ignoreScope = false): mixed
{
$definedNameScope = $namedRange->getScope();
if ($definedNameScope !== null && $definedNameScope !== $cellWorksheet && !$ignoreScope) {
// The defined name isn't in our current scope, so #REF
$result = ExcelError::REF();
$stack->push('Error', $result, $namedRange->getName());
return $result;
}
$definedNameValue = $namedRange->getValue();
$definedNameType = $namedRange->isFormula() ? 'Formula' : 'Range';
if ($definedNameType === 'Range') {
if (Preg::isMatch('/^(.*!)?(.*)$/', $definedNameValue, $matches)) {
$matches2 = Preg::replace(
['/ +/', '/,/'],
[' ∩ ', ' ∪ '],
trim($matches[2])
);
$definedNameValue = $matches[1] . $matches2;
}
}
$definedNameWorksheet = $namedRange->getWorksheet();
if ($definedNameValue[0] !== '=') {
$definedNameValue = '=' . $definedNameValue;
}
$this->debugLog->writeDebugLog('Defined Name is a %s with a value of %s', $definedNameType, $definedNameValue);
$originalCoordinate = $cell->getCoordinate();
$recursiveCalculationCell = ($definedNameType !== 'Formula' && $definedNameWorksheet !== null && $definedNameWorksheet !== $cellWorksheet)
? $definedNameWorksheet->getCell('A1')
: $cell;
$recursiveCalculationCellAddress = $recursiveCalculationCell->getCoordinate();
// Adjust relative references in ranges and formulae so that we execute the calculation for the correct rows and columns
$definedNameValue = ReferenceHelper::getInstance()
->updateFormulaReferencesAnyWorksheet(
$definedNameValue,
Coordinate::columnIndexFromString(
$cell->getColumn()
) - 1,
$cell->getRow() - 1
);
$this->debugLog->writeDebugLog('Value adjusted for relative references is %s', $definedNameValue);
$recursiveCalculator = new self($this->spreadsheet);
$recursiveCalculator->getDebugLog()->setWriteDebugLog($this->getDebugLog()->getWriteDebugLog());
$recursiveCalculator->getDebugLog()->setEchoDebugLog($this->getDebugLog()->getEchoDebugLog());
$result = $recursiveCalculator->_calculateFormulaValue($definedNameValue, $recursiveCalculationCellAddress, $recursiveCalculationCell, true);
$cellWorksheet->getCell($originalCoordinate);
if ($this->getDebugLog()->getWriteDebugLog()) {
$this->debugLog->mergeDebugLog(array_slice($recursiveCalculator->getDebugLog()->getLog(), 3));
$this->debugLog->writeDebugLog('Evaluation Result for Named %s %s is %s', $definedNameType, $namedRange->getName(), $this->showTypeDetails($result));
}
$y = $namedRange->getWorksheet()?->getTitle();
$x = $namedRange->getLocalOnly();
if ($x && $y !== null) {
$stack->push('Defined Name', $result, "'$y'!" . $namedRange->getName());
} else {
$stack->push('Defined Name', $result, $namedRange->getName());
}
return $result;
}
public function setSuppressFormulaErrors(bool $suppressFormulaErrors): self
{
$this->suppressFormulaErrors = $suppressFormulaErrors;
return $this;
}
public function getSuppressFormulaErrors(): bool
{
return $this->suppressFormulaErrors;
}
public static function boolToString(mixed $operand1): mixed
{
if (is_bool($operand1)) {
$operand1 = ($operand1) ? self::$localeBoolean['TRUE'] : self::$localeBoolean['FALSE'];
} elseif ($operand1 === null) {
$operand1 = '';
}
return $operand1;
}
private static function isNumericOrBool(mixed $operand): bool
{
return is_numeric($operand) || is_bool($operand);
}
private static function makeError(mixed $operand = ''): string
{
return (is_string($operand) && Information\ErrorValue::isError($operand)) ? $operand : ExcelError::VALUE();
}
private static function swapOperands(Stack $stack, string $opCharacter): bool
{
$retVal = false;
if ($stack->count() > 0) {
$o2 = $stack->last();
if ($o2) {
/** @var array{value: string} $o2 */
if (isset(self::CALCULATION_OPERATORS[$o2['value']])) {
$retVal = (self::OPERATOR_PRECEDENCE[$opCharacter] ?? 0) <= self::OPERATOR_PRECEDENCE[$o2['value']];
}
}
}
return $retVal;
}
public function getSpreadsheet(): ?Spreadsheet
{
return $this->spreadsheet;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/CalculationBase.php
================================================
*/
public static function getFunctions(): array
{
return FunctionArray::$phpSpreadsheetFunctions;
}
/**
* Get address of list of all implemented functions as an array of function objects.
*
* @return array>
*/
protected static function &getFunctionsAddress(): array
{
return FunctionArray::$phpSpreadsheetFunctions;
}
/**
* @param array{category: string, functionCall: string|string[], argumentCount: string, passCellReference?: bool, passByReference?: bool[], custom?: bool} $value
*/
public static function addFunction(string $key, array $value): bool
{
$key = strtoupper($key);
if (
array_key_exists($key, FunctionArray::$phpSpreadsheetFunctions)
&& !self::isDummy($key)
) {
return false;
}
$value['custom'] = true;
FunctionArray::$phpSpreadsheetFunctions[$key] = $value;
return true;
}
private static function isDummy(string $key): bool
{
// key is already known to exist
$functionCall = FunctionArray::$phpSpreadsheetFunctions[$key]['functionCall'] ?? null;
if (!is_array($functionCall)) {
return false;
}
if (($functionCall[1] ?? '') !== 'DUMMY') {
return false;
}
return true;
}
public static function removeFunction(string $key): bool
{
$key = strtoupper($key);
if (array_key_exists($key, FunctionArray::$phpSpreadsheetFunctions)) {
if (FunctionArray::$phpSpreadsheetFunctions[$key]['custom'] ?? false) {
unset(FunctionArray::$phpSpreadsheetFunctions[$key]);
return true;
}
}
return false;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/CalculationLocale.php
================================================
*/
protected static array $localeBoolean = [
'TRUE' => 'TRUE',
'FALSE' => 'FALSE',
'NULL' => 'NULL',
];
/** @var array> */
protected static array $falseTrueArray = [];
public static function getLocaleBoolean(string $index): string
{
return self::$localeBoolean[$index];
}
protected static function loadLocales(): void
{
$localeFileDirectory = __DIR__ . '/locale/';
$localeFileNames = glob($localeFileDirectory . '*', GLOB_ONLYDIR) ?: [];
foreach ($localeFileNames as $filename) {
$filename = substr($filename, strlen($localeFileDirectory));
if ($filename != 'en') {
self::$validLocaleLanguages[] = $filename;
$subdirs = glob("$localeFileDirectory$filename/*", GLOB_ONLYDIR) ?: [];
foreach ($subdirs as $subdir) {
$subdirx = basename($subdir);
self::$validLocaleLanguages[] = "{$filename}_{$subdirx}";
}
}
}
}
/**
* Return the locale-specific translation of TRUE.
*
* @return string locale-specific translation of TRUE
*/
public static function getTRUE(): string
{
return self::$localeBoolean['TRUE'];
}
/**
* Return the locale-specific translation of FALSE.
*
* @return string locale-specific translation of FALSE
*/
public static function getFALSE(): string
{
return self::$localeBoolean['FALSE'];
}
/**
* Get the currently defined locale code.
*/
public function getLocale(): string
{
return self::$localeLanguage;
}
protected function getLocaleFile(string $localeDir, string $locale, string $language, string $file): string
{
$localeFileName = $localeDir . str_replace('_', DIRECTORY_SEPARATOR, $locale)
. DIRECTORY_SEPARATOR . $file;
if (!file_exists($localeFileName)) {
// If there isn't a locale specific file, look for a language specific file
$localeFileName = $localeDir . $language . DIRECTORY_SEPARATOR . $file;
if (!file_exists($localeFileName)) {
throw new Exception('Locale file not found');
}
}
return $localeFileName;
}
/** @return array> */
public function getFalseTrueArray(): array
{
if (!empty(self::$falseTrueArray)) {
return self::$falseTrueArray;
}
if (count(self::$validLocaleLanguages) == 1) {
self::loadLocales();
}
$falseTrueArray = [['FALSE'], ['TRUE']];
foreach (self::$validLocaleLanguages as $language) {
if (str_starts_with($language, 'en')) {
continue;
}
$locale = $language;
if (str_contains($locale, '_')) {
[$language] = explode('_', $locale);
}
$localeDir = implode(DIRECTORY_SEPARATOR, [__DIR__, 'locale', null]);
try {
$functionNamesFile = $this->getLocaleFile($localeDir, $locale, $language, 'functions');
} catch (Exception $e) {
continue;
}
// Retrieve the list of locale or language specific function names
$localeFunctions = file($functionNamesFile, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) ?: [];
foreach ($localeFunctions as $localeFunction) {
[$localeFunction] = explode('##', $localeFunction); // Strip out comments
if (str_contains($localeFunction, '=')) {
[$fName, $lfName] = array_map('trim', explode('=', $localeFunction));
if ($fName === 'FALSE') {
$falseTrueArray[0][] = $lfName;
} elseif ($fName === 'TRUE') {
$falseTrueArray[1][] = $lfName;
}
}
}
}
self::$falseTrueArray = $falseTrueArray;
return $falseTrueArray;
}
/**
* Set the locale code.
*
* @param string $locale The locale to use for formula translation, eg: 'en_us'
*/
public function setLocale(string $locale): bool
{
// Identify our locale and language
$language = $locale = strtolower($locale);
if (str_contains($locale, '_')) {
[$language] = explode('_', $locale);
}
if (count(self::$validLocaleLanguages) == 1) {
self::loadLocales();
}
// Test whether we have any language data for this language (any locale)
if (in_array($language, self::$validLocaleLanguages, true)) {
// initialise language/locale settings
self::$localeFunctions = [];
self::$localeArgumentSeparator = ',';
self::$localeBoolean = ['TRUE' => 'TRUE', 'FALSE' => 'FALSE', 'NULL' => 'NULL'];
// Default is US English, if user isn't requesting US english, then read the necessary data from the locale files
if ($locale !== 'en_us') {
$localeDir = implode(DIRECTORY_SEPARATOR, [__DIR__, 'locale', null]);
// Search for a file with a list of function names for locale
try {
$functionNamesFile = $this->getLocaleFile($localeDir, $locale, $language, 'functions');
} catch (Exception $e) {
return false;
}
// Retrieve the list of locale or language specific function names
$localeFunctions = file($functionNamesFile, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) ?: [];
$phpSpreadsheetFunctions = &self::getFunctionsAddress();
foreach ($localeFunctions as $localeFunction) {
[$localeFunction] = explode('##', $localeFunction); // Strip out comments
if (str_contains($localeFunction, '=')) {
[$fName, $lfName] = array_map('trim', explode('=', $localeFunction));
if ((str_starts_with($fName, '*') || isset($phpSpreadsheetFunctions[$fName])) && ($lfName != '') && ($fName != $lfName)) {
self::$localeFunctions[$fName] = $lfName;
}
}
}
// Default the TRUE and FALSE constants to the locale names of the TRUE() and FALSE() functions
if (isset(self::$localeFunctions['TRUE'])) {
self::$localeBoolean['TRUE'] = self::$localeFunctions['TRUE'];
}
if (isset(self::$localeFunctions['FALSE'])) {
self::$localeBoolean['FALSE'] = self::$localeFunctions['FALSE'];
}
try {
$configFile = $this->getLocaleFile($localeDir, $locale, $language, 'config');
} catch (Exception) {
return false;
}
$localeSettings = file($configFile, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) ?: [];
foreach ($localeSettings as $localeSetting) {
[$localeSetting] = explode('##', $localeSetting); // Strip out comments
if (str_contains($localeSetting, '=')) {
[$settingName, $settingValue] = array_map('trim', explode('=', $localeSetting));
$settingName = strtoupper($settingName);
if ($settingValue !== '') {
switch ($settingName) {
case 'ARGUMENTSEPARATOR':
self::$localeArgumentSeparator = $settingValue;
break;
}
}
}
}
}
self::$functionReplaceFromExcel = self::$functionReplaceToExcel
= self::$functionReplaceFromLocale = self::$functionReplaceToLocale = null;
self::$localeLanguage = $locale;
return true;
}
return false;
}
public static function translateSeparator(
string $fromSeparator,
string $toSeparator,
string $formula,
int &$inBracesLevel,
string $openBrace = self::FORMULA_OPEN_FUNCTION_BRACE,
string $closeBrace = self::FORMULA_CLOSE_FUNCTION_BRACE
): string {
$strlen = mb_strlen($formula);
for ($i = 0; $i < $strlen; ++$i) {
$chr = mb_substr($formula, $i, 1);
switch ($chr) {
case $openBrace:
++$inBracesLevel;
break;
case $closeBrace:
--$inBracesLevel;
break;
case $fromSeparator:
if ($inBracesLevel > 0) {
$formula = mb_substr($formula, 0, $i) . $toSeparator . mb_substr($formula, $i + 1);
}
}
}
return $formula;
}
/**
* @param string[] $from
* @param string[] $to
*/
protected static function translateFormulaBlock(
array $from,
array $to,
string $formula,
int &$inFunctionBracesLevel,
int &$inMatrixBracesLevel,
string $fromSeparator,
string $toSeparator
): string {
// Function Names
$formula = (string) preg_replace($from, $to, $formula);
// Temporarily adjust matrix separators so that they won't be confused with function arguments
$formula = self::translateSeparator(';', '|', $formula, $inMatrixBracesLevel, self::FORMULA_OPEN_MATRIX_BRACE, self::FORMULA_CLOSE_MATRIX_BRACE);
$formula = self::translateSeparator(',', '!', $formula, $inMatrixBracesLevel, self::FORMULA_OPEN_MATRIX_BRACE, self::FORMULA_CLOSE_MATRIX_BRACE);
// Function Argument Separators
$formula = self::translateSeparator($fromSeparator, $toSeparator, $formula, $inFunctionBracesLevel);
// Restore matrix separators
$formula = self::translateSeparator('|', ';', $formula, $inMatrixBracesLevel, self::FORMULA_OPEN_MATRIX_BRACE, self::FORMULA_CLOSE_MATRIX_BRACE);
$formula = self::translateSeparator('!', ',', $formula, $inMatrixBracesLevel, self::FORMULA_OPEN_MATRIX_BRACE, self::FORMULA_CLOSE_MATRIX_BRACE);
return $formula;
}
/**
* @param string[] $from
* @param string[] $to
*/
protected static function translateFormula(array $from, array $to, string $formula, string $fromSeparator, string $toSeparator): string
{
// Convert any Excel function names and constant names to the required language;
// and adjust function argument separators
if (self::$localeLanguage !== 'en_us') {
$inFunctionBracesLevel = 0;
$inMatrixBracesLevel = 0;
// If there is the possibility of separators within a quoted string, then we treat them as literals
if (str_contains($formula, self::FORMULA_STRING_QUOTE)) {
// So instead we skip replacing in any quoted strings by only replacing in every other array element
// after we've exploded the formula
$temp = explode(self::FORMULA_STRING_QUOTE, $formula);
$notWithinQuotes = false;
foreach ($temp as &$value) {
// Only adjust in alternating array entries
$notWithinQuotes = $notWithinQuotes === false;
if ($notWithinQuotes === true) {
$value = self::translateFormulaBlock($from, $to, $value, $inFunctionBracesLevel, $inMatrixBracesLevel, $fromSeparator, $toSeparator);
}
}
unset($value);
// Then rebuild the formula string
$formula = implode(self::FORMULA_STRING_QUOTE, $temp);
} else {
// If there's no quoted strings, then we do a simple count/replace
$formula = self::translateFormulaBlock($from, $to, $formula, $inFunctionBracesLevel, $inMatrixBracesLevel, $fromSeparator, $toSeparator);
}
}
return $formula;
}
/** @var null|string[] */
private static ?array $functionReplaceFromExcel;
/** @var null|string[] */
private static ?array $functionReplaceToLocale;
public function translateFormulaToLocale(string $formula): string
{
$formula = preg_replace(self::CALCULATION_REGEXP_STRIP_XLFN_XLWS, '', $formula) ?? '';
// Build list of function names and constants for translation
if (self::$functionReplaceFromExcel === null) {
self::$functionReplaceFromExcel = [];
foreach (array_keys(self::$localeFunctions) as $excelFunctionName) {
self::$functionReplaceFromExcel[] = '/(@?[^\w\.])' . preg_quote($excelFunctionName, '/') . '([\s]*\()/ui';
}
foreach (array_keys(self::$localeBoolean) as $excelBoolean) {
self::$functionReplaceFromExcel[] = '/(@?[^\w\.])' . preg_quote($excelBoolean, '/') . '([^\w\.])/ui';
}
}
if (self::$functionReplaceToLocale === null) {
self::$functionReplaceToLocale = [];
foreach (self::$localeFunctions as $localeFunctionName) {
self::$functionReplaceToLocale[] = '$1' . trim($localeFunctionName) . '$2';
}
foreach (self::$localeBoolean as $localeBoolean) {
self::$functionReplaceToLocale[] = '$1' . trim($localeBoolean) . '$2';
}
}
return self::translateFormula(
self::$functionReplaceFromExcel,
self::$functionReplaceToLocale,
$formula,
',',
self::$localeArgumentSeparator
);
}
/** @var null|string[] */
protected static ?array $functionReplaceFromLocale;
/** @var null|string[] */
protected static ?array $functionReplaceToExcel;
public function translateFormulaToEnglish(string $formula): string
{
if (self::$functionReplaceFromLocale === null) {
self::$functionReplaceFromLocale = [];
foreach (self::$localeFunctions as $localeFunctionName) {
self::$functionReplaceFromLocale[] = '/(@?[^\w\.])' . preg_quote($localeFunctionName, '/') . '([\s]*\()/ui';
}
foreach (self::$localeBoolean as $excelBoolean) {
self::$functionReplaceFromLocale[] = '/(@?[^\w\.])' . preg_quote($excelBoolean, '/') . '([^\w\.])/ui';
}
}
if (self::$functionReplaceToExcel === null) {
self::$functionReplaceToExcel = [];
foreach (array_keys(self::$localeFunctions) as $excelFunctionName) {
self::$functionReplaceToExcel[] = '$1' . trim($excelFunctionName) . '$2';
}
foreach (array_keys(self::$localeBoolean) as $excelBoolean) {
self::$functionReplaceToExcel[] = '$1' . trim($excelBoolean) . '$2';
}
}
return self::translateFormula(self::$functionReplaceFromLocale, self::$functionReplaceToExcel, $formula, self::$localeArgumentSeparator, ',');
}
public static function localeFunc(string $function): string
{
if (self::$localeLanguage !== 'en_us') {
$functionName = trim($function, '(');
if (isset(self::$localeFunctions[$functionName])) {
$brace = ($functionName != $function);
$function = self::$localeFunctions[$functionName];
if ($brace) {
$function .= '(';
}
}
}
return $function;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/CalculationParserOnly.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): string|int|float
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return Averages::average(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DCount.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria, bool $returnError = true): string|int
{
$field = self::fieldExtract($database, $field);
if ($returnError && $field === null) {
return ExcelError::VALUE();
}
return Counts::COUNT(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DCountA.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): string|int
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return Counts::COUNTA(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DGet.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): null|float|int|string
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
$columnData = self::getFilteredColumn($database, $field, $criteria);
if (count($columnData) > 1) {
return ExcelError::NAN();
}
/** @var array */
$row = array_pop($columnData);
return array_pop($row);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DMax.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria, bool $returnError = true): null|float|string
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return $returnError ? ExcelError::VALUE() : null;
}
return Maximum::max(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DMin.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria, bool $returnError = true): float|string|null
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return $returnError ? ExcelError::VALUE() : null;
}
return Minimum::min(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DProduct.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): string|float
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return MathTrig\Operations::product(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DStDev.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): float|string
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return StandardDeviations::STDEV(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DStDevP.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): float|string
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return StandardDeviations::STDEVP(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DSum.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria, bool $returnNull = false): null|float|string
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return $returnNull ? null : ExcelError::VALUE();
}
return MathTrig\Sum::sumIgnoringStrings(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DVar.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*
* @return float|string (string if result is an error)
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): string|float
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return Variances::VAR(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DVarP.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*
* @return float|string (string if result is an error)
*/
public static function evaluate(array $database, array|null|int|string $field, array $criteria): string|float
{
$field = self::fieldExtract($database, $field);
if ($field === null) {
return ExcelError::VALUE();
}
return Variances::VARP(
self::getFilteredColumn($database, $field, $criteria)
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Database/DatabaseAbstract.php
================================================
|int|string $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
* @param mixed[] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*/
abstract public static function evaluate(array $database, array|null|int|string $field, array $criteria): null|float|int|string;
/**
* fieldExtract.
*
* Extracts the column ID to use for the data field.
*
* @param mixed[] $database The range of cells that makes up the list or database.
* A database is a list of related data in which rows of related
* information are records, and columns of data are fields. The
* first row of the list contains labels for each column.
* @param mixed $field Indicates which column is used in the function. Enter the
* column label enclosed between double quotation marks, such as
* "Age" or "Yield," or a number (without quotation marks) that
* represents the position of the column within the list: 1 for
* the first column, 2 for the second column, and so on.
*/
protected static function fieldExtract(array $database, mixed $field): ?int
{
/** @var ?string */
$single = Functions::flattenSingleValue($field);
$field = strtoupper($single ?? '');
if ($field === '') {
return null;
}
/** @var callable */
$callable = 'strtoupper';
$fieldNames = array_map($callable, array_shift($database)); //* @phpstan-ignore-line
if (is_numeric($field)) {
$field = (int) $field - 1;
if ($field < 0 || $field >= count($fieldNames)) {
return null;
}
return $field;
}
$key = array_search($field, array_values($fieldNames), true);
return ($key !== false) ? (int) $key : null;
}
/**
* filter.
*
* Parses the selection criteria, extracts the database rows that match those criteria, and
* returns that subset of rows.
*
* @param mixed[] $database The range of cells that makes up the list or database.
* A database is a list of related data in which rows of related
* information are records, and columns of data are fields. The
* first row of the list contains labels for each column.
* @param mixed[][] $criteria The range of cells that contains the conditions you specify.
* You can use any range for the criteria argument, as long as it
* includes at least one column label and at least one cell below
* the column label in which you specify a condition for the
* column.
*
* @return mixed[]
*/
protected static function filter(array $database, array $criteria): array
{
/** @var mixed[] */
$fieldNames = array_shift($database);
$criteriaNames = array_shift($criteria);
// Convert the criteria into a set of AND/OR conditions with [:placeholders]
/** @var string[] $criteriaNames */
$query = self::buildQuery($criteriaNames, $criteria);
// Loop through each row of the database
/** @var mixed[][] $criteriaNames */
return self::executeQuery($database, $query, $criteriaNames, $fieldNames);
}
/**
* @param mixed[] $database The range of cells that makes up the list or database
* @param mixed[][] $criteria
*
* @return mixed[]
*/
protected static function getFilteredColumn(array $database, ?int $field, array $criteria): array
{
// reduce the database to a set of rows that match all the criteria
$database = self::filter($database, $criteria);
$defaultReturnColumnValue = ($field === null) ? 1 : null;
// extract an array of values for the requested column
$columnData = [];
/** @var mixed[] $row */
foreach ($database as $rowKey => $row) {
$keys = array_keys($row);
$key = ($field === null) ? null : ($keys[$field] ?? null);
$columnKey = $key ?? 'A';
$columnData[$rowKey][$columnKey] = ($key === null) ? $defaultReturnColumnValue : ($row[$key] ?? $defaultReturnColumnValue);
}
return $columnData;
}
/**
* @param string[] $criteriaNames
* @param mixed[][] $criteria
*/
private static function buildQuery(array $criteriaNames, array $criteria): string
{
$baseQuery = [];
foreach ($criteria as $key => $criterion) {
foreach ($criterion as $field => $value) {
$criterionName = $criteriaNames[$field];
if ($value !== null) {
$condition = self::buildCondition($value, $criterionName);
$baseQuery[$key][] = $condition;
}
}
}
$rowQuery = array_map(
fn ($rowValue): string => (count($rowValue) > 1) ? 'AND(' . implode(',', $rowValue) . ')' : ($rowValue[0] ?? ''), // @phpstan-ignore-line
$baseQuery
);
return (count($rowQuery) > 1) ? 'OR(' . implode(',', $rowQuery) . ')' : ($rowQuery[0] ?? '');
}
private static function buildCondition(mixed $criterion, string $criterionName): string
{
$ifCondition = Functions::ifCondition($criterion);
// Check for wildcard characters used in the condition
$result = preg_match('/(?[^"]*)(?".*[*?].*")/ui', $ifCondition, $matches);
if ($result !== 1) {
return "[:{$criterionName}]{$ifCondition}";
}
$trueFalse = ($matches['operator'] !== '<>');
$wildcard = WildcardMatch::wildcard($matches['operand']);
$condition = "WILDCARDMATCH([:{$criterionName}],{$wildcard})";
if ($trueFalse === false) {
$condition = "NOT({$condition})";
}
return $condition;
}
/**
* @param mixed[] $database
* @param mixed[][] $criteria
* @param array $fields
*
* @return mixed[]
*/
private static function executeQuery(array $database, string $query, array $criteria, array $fields): array
{
foreach ($database as $dataRow => $dataValues) {
// Substitute actual values from the database row for our [:placeholders]
$conditions = $query;
foreach ($criteria as $criterion) {
/** @var string $criterion */
/** @var mixed[] $dataValues */
$conditions = self::processCondition($criterion, $fields, $dataValues, $conditions);
}
// evaluate the criteria against the row data
$result = Calculation::getInstance()->_calculateFormulaValue('=' . $conditions);
// If the row failed to meet the criteria, remove it from the database
if ($result !== true) {
unset($database[$dataRow]);
}
}
return $database;
}
/**
* @param array $fields
* @param array $dataValues
*/
private static function processCondition(string $criterion, array $fields, array $dataValues, string $conditions): string
{
$key = array_search($criterion, $fields, true);
$dataValue = 'NULL';
if (is_bool($dataValues[$key])) {
$dataValue = ($dataValues[$key]) ? 'TRUE' : 'FALSE';
} elseif ($dataValues[$key] !== null) {
$dataValue = $dataValues[$key];
// escape quotes if we have a string containing quotes
if (is_string($dataValue) && str_contains($dataValue, '"')) {
$dataValue = str_replace('"', '""', $dataValue);
}
if (is_string($dataValue)) {
$dataValue = Calculation::wrapResult(strtoupper($dataValue));
}
$dataValue = StringHelper::convertToString($dataValue);
}
return str_replace('[:' . $criterion . ']', $dataValue, $conditions);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Constants.php
================================================
self::DOW_SUNDAY,
self::DOW_MONDAY,
self::STARTWEEK_MONDAY_ALT => self::DOW_MONDAY,
self::DOW_TUESDAY,
self::DOW_WEDNESDAY,
self::DOW_THURSDAY,
self::DOW_FRIDAY,
self::DOW_SATURDAY,
self::DOW_SUNDAY,
self::STARTWEEK_MONDAY_ISO => self::STARTWEEK_MONDAY_ISO,
];
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Current.php
================================================
format('c'));
return Helpers::dateParseSucceeded($dateArray) ? Helpers::returnIn3FormatsArray($dateArray, true) : ExcelError::VALUE();
}
/**
* DATETIMENOW.
*
* Returns the current date and time.
* The NOW function is useful when you need to display the current date and time on a worksheet or
* calculate a value based on the current date and time, and have that value updated each time you
* open the worksheet.
*
* NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the date
* and time format of your regional settings. PhpSpreadsheet does not change cell formatting in this way.
*
* Excel Function:
* NOW()
*
* @return DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
*/
public static function now(): DateTime|float|int|string
{
$dti = new DateTimeImmutable();
$dateArray = Helpers::dateParse($dti->format('c'));
return Helpers::dateParseSucceeded($dateArray) ? Helpers::returnIn3FormatsArray($dateArray) : ExcelError::VALUE();
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Date.php
================================================
|float|int|string $year The value of the year argument can include one to four digits.
* Excel interprets the year argument according to the configured
* date system: 1900 or 1904.
* If year is between 0 (zero) and 1899 (inclusive), Excel adds that
* value to 1900 to calculate the year. For example, DATE(108,1,2)
* returns January 2, 2008 (1900+108).
* If year is between 1900 and 9999 (inclusive), Excel uses that
* value as the year. For example, DATE(2008,1,2) returns January 2,
* 2008.
* If year is less than 0 or is 10000 or greater, Excel returns the
* #NUM! error value.
* @param array|float|int|string $month A positive or negative integer representing the month of the year
* from 1 to 12 (January to December).
* If month is greater than 12, month adds that number of months to
* the first month in the year specified. For example, DATE(2008,14,2)
* returns the serial number representing February 2, 2009.
* If month is less than 1, month subtracts the magnitude of that
* number of months, plus 1, from the first month in the year
* specified. For example, DATE(2008,-3,2) returns the serial number
* representing September 2, 2007.
* @param array|float|int|string $day A positive or negative integer representing the day of the month
* from 1 to 31.
* If day is greater than the number of days in the month specified,
* day adds that number of days to the first day in the month. For
* example, DATE(2008,1,35) returns the serial number representing
* February 4, 2008.
* If day is less than 1, day subtracts the magnitude that number of
* days, plus one, from the first day of the month specified. For
* example, DATE(2008,1,-15) returns the serial number representing
* December 16, 2007.
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function fromYMD(array|float|int|string $year, null|array|bool|float|int|string $month, array|float|int|string $day): float|int|DateTime|string|array
{
if (is_array($year) || is_array($month) || is_array($day)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $year, $month, $day);
}
$baseYear = SharedDateHelper::getExcelCalendar();
try {
$year = self::getYear($year, $baseYear);
$month = self::getMonth($month);
$day = self::getDay($day);
self::adjustYearMonth($year, $month, $baseYear);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$excelDateValue = SharedDateHelper::formattedPHPToExcel($year, $month, $day);
return Helpers::returnIn3FormatsFloat($excelDateValue);
}
/**
* Convert year from multiple formats to int.
*/
private static function getYear(mixed $year, int $baseYear): int
{
if ($year === null) {
$year = 0;
} elseif (is_scalar($year)) {
$year = StringHelper::testStringAsNumeric((string) $year);
}
if (!is_numeric($year)) {
throw new Exception(ExcelError::VALUE());
}
$year = (int) $year;
if ($year < ($baseYear - 1900)) {
throw new Exception(ExcelError::NAN());
}
if ((($baseYear - 1900) !== 0) && ($year < $baseYear) && ($year >= 1900)) {
throw new Exception(ExcelError::NAN());
}
if (($year < $baseYear) && ($year >= ($baseYear - 1900))) {
$year += 1900;
}
return (int) $year;
}
/**
* Convert month from multiple formats to int.
*/
private static function getMonth(mixed $month): int
{
if (is_string($month)) {
if (!is_numeric($month)) {
$month = SharedDateHelper::monthStringToNumber($month);
}
} elseif ($month === null) {
$month = 0;
} elseif (is_bool($month)) {
$month = (int) $month;
}
if (!is_numeric($month)) {
throw new Exception(ExcelError::VALUE());
}
return (int) $month;
}
/**
* Convert day from multiple formats to int.
*/
private static function getDay(mixed $day): int
{
if (is_string($day) && !is_numeric($day)) {
$day = SharedDateHelper::dayStringToNumber($day);
}
if ($day === null) {
$day = 0;
} elseif (is_scalar($day)) {
$day = StringHelper::testStringAsNumeric((string) $day);
}
if (!is_numeric($day)) {
throw new Exception(ExcelError::VALUE());
}
return (int) $day;
}
private static function adjustYearMonth(int &$year, int &$month, int $baseYear): void
{
if ($month < 1) {
// Handle year/month adjustment if month < 1
--$month;
$year += (int) (ceil($month / 12) - 1);
$month = 13 - abs($month % 12);
} elseif ($month > 12) {
// Handle year/month adjustment if month > 12
$year += intdiv($month, 12);
$month = ($month % 12);
}
// Re-validate the year parameter after adjustments
if (($year < $baseYear) || ($year >= 10000)) {
throw new Exception(ExcelError::NAN());
}
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/DateParts.php
================================================
|int|string Day of the month
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function day(mixed $dateValue): array|int|string
{
if (is_array($dateValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $dateValue);
}
$weirdResult = self::weirdCondition($dateValue);
if ($weirdResult >= 0) {
return $weirdResult;
}
try {
$dateValue = Helpers::getDateValue($dateValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$PHPDateObject = SharedDateHelper::excelToDateTimeObject($dateValue);
SharedDateHelper::roundMicroseconds($PHPDateObject);
return (int) $PHPDateObject->format('j');
}
/**
* MONTHOFYEAR.
*
* Returns the month of a date represented by a serial number.
* The month is given as an integer, ranging from 1 (January) to 12 (December).
*
* Excel Function:
* MONTH(dateValue)
*
* @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
* Or can be an array of date values
*
* @return array|int|string Month of the year
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function month(mixed $dateValue): array|string|int
{
if (is_array($dateValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $dateValue);
}
try {
$dateValue = Helpers::getDateValue($dateValue);
} catch (Exception $e) {
return $e->getMessage();
}
if ($dateValue < 1 && SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_WINDOWS_1900) {
return 1;
}
// Execute function
$PHPDateObject = SharedDateHelper::excelToDateTimeObject($dateValue);
SharedDateHelper::roundMicroseconds($PHPDateObject);
return (int) $PHPDateObject->format('n');
}
/**
* YEAR.
*
* Returns the year corresponding to a date.
* The year is returned as an integer in the range 1900-9999.
*
* Excel Function:
* YEAR(dateValue)
*
* @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
* Or can be an array of date values
*
* @return array|int|string Year
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function year(mixed $dateValue): array|string|int
{
if (is_array($dateValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $dateValue);
}
try {
$dateValue = Helpers::getDateValue($dateValue);
} catch (Exception $e) {
return $e->getMessage();
}
if ($dateValue < 1 && SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_WINDOWS_1900) {
return 1900;
}
// Execute function
$PHPDateObject = SharedDateHelper::excelToDateTimeObject($dateValue);
SharedDateHelper::roundMicroseconds($PHPDateObject);
return (int) $PHPDateObject->format('Y');
}
/**
* @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
*/
private static function weirdCondition(mixed $dateValue): int
{
// Excel does not treat 0 consistently for DAY vs. (MONTH or YEAR)
if (SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_WINDOWS_1900 && Functions::getCompatibilityMode() == Functions::COMPATIBILITY_EXCEL) {
if (is_bool($dateValue)) {
return (int) $dateValue;
}
if ($dateValue === null) {
return 0;
}
if (is_numeric($dateValue) && $dateValue < 1 && $dateValue >= 0) {
return 0;
}
}
return -1;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/DateValue.php
================================================
|bool|float|int|string $dateValue Text that represents a date in a Microsoft Excel date format.
* For example, "1/30/2008" or "30-Jan-2008" are text strings within
* quotation marks that represent dates. Using the default date
* system in Excel for Windows, date_text must represent a date from
* January 1, 1900, to December 31, 9999. Using the default date
* system in Excel for the Macintosh, date_text must represent a date
* from January 1, 1904, to December 31, 9999. DATEVALUE returns the
* #VALUE! error value if date_text is out of this range.
* Or can be an array of date values
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function fromString(null|array|string|int|bool|float $dateValue): array|string|float|int|DateTime
{
if (is_array($dateValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $dateValue);
}
// try to parse as date iff there is at least one digit
if (is_string($dateValue) && preg_match('/\d/', $dateValue) !== 1) {
return ExcelError::VALUE();
}
$dti = new DateTimeImmutable();
$baseYear = SharedDateHelper::getExcelCalendar();
$dateValue = trim((string) $dateValue, '"');
// Strip any ordinals because they're allowed in Excel (English only)
$dateValue = (string) preg_replace('/(\d)(st|nd|rd|th)([ -\/])/Ui', '$1$3', $dateValue);
// Convert separators (/ . or space) to hyphens (should also handle dot used for ordinals in some countries, e.g. Denmark, Germany)
$dateValue = str_replace(['/', '.', '-', ' '], ' ', $dateValue);
$yearFound = false;
$t1 = explode(' ', $dateValue);
$t = '';
foreach ($t1 as &$t) {
if ((is_numeric($t)) && ($t > 31)) {
if ($yearFound) {
return ExcelError::VALUE();
}
if ($t < 100) {
$t += 1900;
}
$yearFound = true;
}
}
if (count($t1) === 1) {
// We've been fed a time value without any date
return ((!str_contains((string) $t, ':'))) ? ExcelError::Value() : 0.0;
}
unset($t);
$dateValue = self::t1ToString($t1, $dti, $yearFound);
$PHPDateArray = self::setUpArray($dateValue, $dti);
return self::finalResults($PHPDateArray, $dti, $baseYear);
}
/** @param mixed[] $t1 */
private static function t1ToString(array $t1, DateTimeImmutable $dti, bool $yearFound): string
{
if (count($t1) == 2) {
// We only have two parts of the date: either day/month or month/year
if ($yearFound) {
array_unshift($t1, 1);
} else {
if (is_numeric($t1[1]) && $t1[1] > 29) {
$t1[1] += 1900;
array_unshift($t1, 1);
} else {
$t1[] = $dti->format('Y');
}
}
}
$dateValue = implode(' ', $t1);
return $dateValue;
}
/**
* Parse date.
*
* @return mixed[]
*/
private static function setUpArray(string $dateValue, DateTimeImmutable $dti): array
{
$PHPDateArray = Helpers::dateParse($dateValue);
if (!Helpers::dateParseSucceeded($PHPDateArray)) {
// If original count was 1, we've already returned.
// If it was 2, we added another.
// Therefore, neither of the first 2 strtoks below can fail.
$testVal1 = strtok($dateValue, '- ');
$testVal2 = strtok('- ');
$testVal3 = strtok('- ') ?: $dti->format('Y');
Helpers::adjustYear((string) $testVal1, (string) $testVal2, $testVal3);
$PHPDateArray = Helpers::dateParse($testVal1 . '-' . $testVal2 . '-' . $testVal3);
if (!Helpers::dateParseSucceeded($PHPDateArray)) {
$PHPDateArray = Helpers::dateParse($testVal2 . '-' . $testVal1 . '-' . $testVal3);
}
}
return $PHPDateArray;
}
/**
* Final results.
*
* @param mixed[] $PHPDateArray
*
* @return DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
*/
private static function finalResults(array $PHPDateArray, DateTimeImmutable $dti, int $baseYear): string|float|int|DateTime
{
$retValue = ExcelError::Value();
if (Helpers::dateParseSucceeded($PHPDateArray)) {
/** @var array{year: int, month: int, day: int, hour: int, minute: int, second: int} $PHPDateArray */
// Execute function
Helpers::replaceIfEmpty($PHPDateArray['year'], $dti->format('Y'));
if ($PHPDateArray['year'] < $baseYear) {
return ExcelError::VALUE();
}
Helpers::replaceIfEmpty($PHPDateArray['month'], $dti->format('m'));
Helpers::replaceIfEmpty($PHPDateArray['day'], $dti->format('d'));
/** @var array{year: int, month: int, day: int, hour: int, minute: int, second: int} $PHPDateArray */
$PHPDateArray['hour'] = 0;
$PHPDateArray['minute'] = 0;
$PHPDateArray['second'] = 0;
$month = self::getInt($PHPDateArray, 'month');
$day = self::getInt($PHPDateArray, 'day');
$year = self::getInt($PHPDateArray, 'year');
if (!checkdate($month, $day, $year)) {
return ($year === 1900 && $month === 2 && $day === 29) ? Helpers::returnIn3FormatsFloat(60.0) : ExcelError::VALUE();
}
$retValue = Helpers::returnIn3FormatsArray($PHPDateArray, true);
}
return $retValue;
}
/** @param mixed[] $array */
private static function getInt(array $array, string $index): int
{
return (array_key_exists($index, $array) && is_numeric($array[$index])) ? (int) $array[$index] : 0;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Days.php
================================================
|DateTimeInterface|float|int|string $endDate Excel date serial value (float),
* PHP date timestamp (integer), PHP DateTime object, or a standard date string
* Or can be an array of date values
* @param array|DateTimeInterface|float|int|string $startDate Excel date serial value (float),
* PHP date timestamp (integer), PHP DateTime object, or a standard date string
* Or can be an array of date values
*
* @return array|int|string Number of days between start date and end date or an error
* If an array of values is passed for the $startDate or $endDays,arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function between(array|DateTimeInterface|float|int|string $endDate, array|DateTimeInterface|float|int|string $startDate): array|int|string
{
if (is_array($endDate) || is_array($startDate)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $endDate, $startDate);
}
try {
$startDate = Helpers::getDateValue($startDate);
$endDate = Helpers::getDateValue($endDate);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$PHPStartDateObject = SharedDateHelper::excelToDateTimeObject($startDate);
$PHPEndDateObject = SharedDateHelper::excelToDateTimeObject($endDate);
$days = ExcelError::VALUE();
$diff = $PHPStartDateObject->diff($PHPEndDateObject);
if (!is_bool($diff->days)) {
$days = $diff->days;
if ($diff->invert) {
$days = -$days;
}
}
return $days;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Days360.php
================================================
|int|string Number of days between start date and end date
* If an array of values is passed for the $startDate or $endDays,arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function between(mixed $startDate = 0, mixed $endDate = 0, mixed $method = false): array|string|int
{
if (is_array($startDate) || is_array($endDate) || is_array($method)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $startDate, $endDate, $method);
}
try {
$startDate = Helpers::getDateValue($startDate);
$endDate = Helpers::getDateValue($endDate);
} catch (Exception $e) {
return $e->getMessage();
}
if (!is_bool($method)) {
return ExcelError::VALUE();
}
// Execute function
$PHPStartDateObject = SharedDateHelper::excelToDateTimeObject($startDate);
$startDay = $PHPStartDateObject->format('j');
$startMonth = $PHPStartDateObject->format('n');
$startYear = $PHPStartDateObject->format('Y');
$PHPEndDateObject = SharedDateHelper::excelToDateTimeObject($endDate);
$endDay = $PHPEndDateObject->format('j');
$endMonth = $PHPEndDateObject->format('n');
$endYear = $PHPEndDateObject->format('Y');
return self::dateDiff360((int) $startDay, (int) $startMonth, (int) $startYear, (int) $endDay, (int) $endMonth, (int) $endYear, !$method);
}
/**
* Return the number of days between two dates based on a 360-day calendar.
*/
private static function dateDiff360(int $startDay, int $startMonth, int $startYear, int $endDay, int $endMonth, int $endYear, bool $methodUS): int
{
$startDay = self::getStartDay($startDay, $startMonth, $startYear, $methodUS);
$endDay = self::getEndDay($endDay, $endMonth, $endYear, $startDay, $methodUS);
return $endDay + $endMonth * 30 + $endYear * 360 - $startDay - $startMonth * 30 - $startYear * 360;
}
private static function getStartDay(int $startDay, int $startMonth, int $startYear, bool $methodUS): int
{
if ($startDay == 31) {
--$startDay;
} elseif ($methodUS && ($startMonth == 2 && ($startDay == 29 || ($startDay == 28 && !Helpers::isLeapYear($startYear))))) {
$startDay = 30;
}
return $startDay;
}
private static function getEndDay(int $endDay, int &$endMonth, int &$endYear, int $startDay, bool $methodUS): int
{
if ($endDay == 31) {
if ($methodUS && $startDay != 30) {
$endDay = 1;
if ($endMonth == 12) {
++$endYear;
$endMonth = 1;
} else {
++$endMonth;
}
} else {
$endDay = 30;
}
}
return $endDay;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Difference.php
================================================
|string $unit Or can be an array of unit values
*
* @return array|int|string Interval between the dates
* If an array of values is passed for the $startDate or $endDays,arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function interval(mixed $startDate, mixed $endDate, array|string $unit = 'D')
{
if (is_array($startDate) || is_array($endDate) || is_array($unit)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $startDate, $endDate, $unit);
}
try {
$startDate = Helpers::getDateValue($startDate);
$endDate = Helpers::getDateValue($endDate);
$difference = self::initialDiff($startDate, $endDate);
$unit = strtoupper($unit);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$PHPStartDateObject = SharedDateHelper::excelToDateTimeObject($startDate);
$startDays = (int) $PHPStartDateObject->format('j');
//$startMonths = (int) $PHPStartDateObject->format('n');
$startYears = (int) $PHPStartDateObject->format('Y');
$PHPEndDateObject = SharedDateHelper::excelToDateTimeObject($endDate);
$endDays = (int) $PHPEndDateObject->format('j');
//$endMonths = (int) $PHPEndDateObject->format('n');
$endYears = (int) $PHPEndDateObject->format('Y');
$PHPDiffDateObject = $PHPEndDateObject->diff($PHPStartDateObject);
$retVal = false;
$retVal = self::replaceRetValue($retVal, $unit, 'D') ?? self::datedifD($difference);
$retVal = self::replaceRetValue($retVal, $unit, 'M') ?? self::datedifM($PHPDiffDateObject);
$retVal = self::replaceRetValue($retVal, $unit, 'MD') ?? self::datedifMD($startDays, $endDays, $PHPEndDateObject, $PHPDiffDateObject);
$retVal = self::replaceRetValue($retVal, $unit, 'Y') ?? self::datedifY($PHPDiffDateObject);
$retVal = self::replaceRetValue($retVal, $unit, 'YD') ?? self::datedifYD($difference, $startYears, $endYears, $PHPStartDateObject, $PHPEndDateObject);
$retVal = self::replaceRetValue($retVal, $unit, 'YM') ?? self::datedifYM($PHPDiffDateObject);
return is_bool($retVal) ? ExcelError::VALUE() : $retVal;
}
private static function initialDiff(float $startDate, float $endDate): float
{
// Validate parameters
if ($startDate > $endDate) {
throw new Exception(ExcelError::NAN());
}
return $endDate - $startDate;
}
/**
* Decide whether it's time to set retVal.
*/
private static function replaceRetValue(bool|int $retVal, string $unit, string $compare): null|bool|int
{
if ($retVal !== false || $unit !== $compare) {
return $retVal;
}
return null;
}
private static function datedifD(float $difference): int
{
return (int) $difference;
}
private static function datedifM(DateInterval $PHPDiffDateObject): int
{
return 12 * (int) $PHPDiffDateObject->format('%y') + (int) $PHPDiffDateObject->format('%m');
}
private static function datedifMD(int $startDays, int $endDays, DateTime $PHPEndDateObject, DateInterval $PHPDiffDateObject): int
{
if ($endDays < $startDays) {
$retVal = $endDays;
$PHPEndDateObject->modify('-' . $endDays . ' days');
$adjustDays = (int) $PHPEndDateObject->format('j');
$retVal += ($adjustDays - $startDays);
} else {
$retVal = (int) $PHPDiffDateObject->format('%d');
}
return $retVal;
}
private static function datedifY(DateInterval $PHPDiffDateObject): int
{
return (int) $PHPDiffDateObject->format('%y');
}
private static function datedifYD(float $difference, int $startYears, int $endYears, DateTime $PHPStartDateObject, DateTime $PHPEndDateObject): int
{
$retVal = (int) $difference;
if ($endYears > $startYears) {
$isLeapStartYear = $PHPStartDateObject->format('L');
$wasLeapEndYear = $PHPEndDateObject->format('L');
// Adjust end year to be as close as possible as start year
while ($PHPEndDateObject >= $PHPStartDateObject) {
$PHPEndDateObject->modify('-1 year');
//$endYears = $PHPEndDateObject->format('Y');
}
$PHPEndDateObject->modify('+1 year');
// Get the result
$retVal = (int) $PHPEndDateObject->diff($PHPStartDateObject)->days;
// Adjust for leap years cases
$isLeapEndYear = $PHPEndDateObject->format('L');
$limit = new DateTime($PHPEndDateObject->format('Y-02-29'));
if (!$isLeapStartYear && !$wasLeapEndYear && $isLeapEndYear && $PHPEndDateObject >= $limit) {
--$retVal;
}
}
return (int) $retVal;
}
private static function datedifYM(DateInterval $PHPDiffDateObject): int
{
return (int) $PHPDiffDateObject->format('%m');
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Helpers.php
================================================
format('m');
$oYear = (int) $PHPDateObject->format('Y');
$adjustmentMonthsString = (string) $adjustmentMonths;
if ($adjustmentMonths > 0) {
$adjustmentMonthsString = '+' . $adjustmentMonths;
}
if ($adjustmentMonths != 0) {
$PHPDateObject->modify($adjustmentMonthsString . ' months');
}
$nMonth = (int) $PHPDateObject->format('m');
$nYear = (int) $PHPDateObject->format('Y');
$monthDiff = ($nMonth - $oMonth) + (($nYear - $oYear) * 12);
if ($monthDiff != $adjustmentMonths) {
$adjustDays = (int) $PHPDateObject->format('d');
$adjustDaysString = '-' . $adjustDays . ' days';
$PHPDateObject->modify($adjustDaysString);
}
return $PHPDateObject;
}
/**
* Help reduce perceived complexity of some tests.
*/
public static function replaceIfEmpty(mixed &$value, mixed $altValue): void
{
$value = $value ?: $altValue;
}
/**
* Adjust year in ambiguous situations.
*/
public static function adjustYear(string $testVal1, string $testVal2, string &$testVal3): void
{
if (!is_numeric($testVal1) || $testVal1 < 31) {
if (!is_numeric($testVal2) || $testVal2 < 12) {
if (is_numeric($testVal3) && $testVal3 < 12) {
$testVal3 = (string) ($testVal3 + 2000);
}
}
}
}
/**
* Return result in one of three formats.
*
* @param array{year: int, month: int, day: int, hour: int, minute: int, second: int} $dateArray
*/
public static function returnIn3FormatsArray(array $dateArray, bool $noFrac = false): DateTime|float|int
{
$retType = Functions::getReturnDateType();
if ($retType === Functions::RETURNDATE_PHP_DATETIME_OBJECT) {
return new DateTime(
$dateArray['year']
. '-' . $dateArray['month']
. '-' . $dateArray['day']
. ' ' . $dateArray['hour']
. ':' . $dateArray['minute']
. ':' . $dateArray['second']
);
}
$excelDateValue
= SharedDateHelper::formattedPHPToExcel(
$dateArray['year'],
$dateArray['month'],
$dateArray['day'],
$dateArray['hour'],
$dateArray['minute'],
$dateArray['second']
);
if ($retType === Functions::RETURNDATE_EXCEL) {
return $noFrac ? floor($excelDateValue) : $excelDateValue;
}
// RETURNDATE_UNIX_TIMESTAMP)
return SharedDateHelper::excelToTimestamp($excelDateValue);
}
/**
* Return result in one of three formats.
*/
public static function returnIn3FormatsFloat(float $excelDateValue): float|int|DateTime
{
$retType = Functions::getReturnDateType();
if ($retType === Functions::RETURNDATE_EXCEL) {
return $excelDateValue;
}
if ($retType === Functions::RETURNDATE_UNIX_TIMESTAMP) {
return SharedDateHelper::excelToTimestamp($excelDateValue);
}
// RETURNDATE_PHP_DATETIME_OBJECT
return SharedDateHelper::excelToDateTimeObject($excelDateValue);
}
/**
* Return result in one of three formats.
*/
public static function returnIn3FormatsObject(DateTime $PHPDateObject): DateTime|float|int
{
$retType = Functions::getReturnDateType();
if ($retType === Functions::RETURNDATE_PHP_DATETIME_OBJECT) {
return $PHPDateObject;
}
if ($retType === Functions::RETURNDATE_EXCEL) {
return (float) SharedDateHelper::PHPToExcel($PHPDateObject);
}
// RETURNDATE_UNIX_TIMESTAMP
$stamp = SharedDateHelper::PHPToExcel($PHPDateObject);
$stamp = is_bool($stamp) ? ((int) $stamp) : $stamp;
return SharedDateHelper::excelToTimestamp($stamp);
}
private static function baseDate(): int
{
if (Functions::getCompatibilityMode() === Functions::COMPATIBILITY_OPENOFFICE) {
return 0;
}
if (SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_MAC_1904) {
return 0;
}
return 1;
}
/**
* Many functions accept null/false/true argument treated as 0/0/1.
*/
public static function nullFalseTrueToNumber(mixed &$number, bool $allowBool = true): void
{
$number = Functions::flattenSingleValue($number);
$nullVal = self::baseDate();
if ($number === null) {
$number = $nullVal;
} elseif ($allowBool && is_bool($number)) {
$number = $nullVal + (int) $number;
}
}
/**
* Many functions accept null argument treated as 0.
*/
public static function validateNumericNull(mixed $number): int|float
{
$number = Functions::flattenSingleValue($number);
if ($number === null) {
return 0;
}
if (is_int($number)) {
return $number;
}
if (is_numeric($number)) {
return (float) $number;
}
throw new Exception(ExcelError::VALUE());
}
/**
* Many functions accept null/false/true argument treated as 0/0/1.
*
* @phpstan-assert float $number
*/
public static function validateNotNegative(mixed $number): float
{
if (!is_numeric($number)) {
throw new Exception(ExcelError::VALUE());
}
if ($number >= 0) {
return (float) $number;
}
throw new Exception(ExcelError::NAN());
}
public static function silly1900(DateTime $PHPDateObject, string $mod = '-1 day'): void
{
$isoDate = $PHPDateObject->format('c');
if ($isoDate < '1900-03-01') {
$PHPDateObject->modify($mod);
}
}
/** @return array{year: int, month: int, day: int, hour: int, minute: int, second: int} */
public static function dateParse(string $string): array
{
/** @var array{year: int, month: int, day: int, hour: int, minute: int, second: int} */
$temp = self::forceArray(date_parse($string));
return $temp;
}
/** @param mixed[] $dateArray */
public static function dateParseSucceeded(array $dateArray): bool
{
return $dateArray['error_count'] === 0;
}
/**
* Despite documentation, date_parse probably never returns false.
* Just in case, this routine helps guarantee it.
*
* @param array|false $dateArray
*
* @return mixed[]
*/
private static function forceArray(array|bool $dateArray): array
{
return is_array($dateArray) ? $dateArray : ['error_count' => 1];
}
public static function floatOrInt(mixed $value): float|int
{
$result = Functions::scalar($value);
return is_numeric($result) ? ($result + 0) : 0;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Month.php
================================================
|int $adjustmentMonths The number of months before or after start_date.
* A positive value for months yields a future date;
* a negative value yields a past date.
* Or can be an array of adjustment values
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of values is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function adjust(mixed $dateValue, array|string|bool|float|int $adjustmentMonths): DateTime|float|int|string|array
{
if (is_array($dateValue) || is_array($adjustmentMonths)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $dateValue, $adjustmentMonths);
}
try {
$dateValue = Helpers::getDateValue($dateValue, false);
$adjustmentMonths = Helpers::validateNumericNull($adjustmentMonths);
} catch (Exception $e) {
return $e->getMessage();
}
$dateValue = floor($dateValue);
$adjustmentMonths = floor($adjustmentMonths);
// Execute function
$PHPDateObject = Helpers::adjustDateByMonths($dateValue, $adjustmentMonths);
return Helpers::returnIn3FormatsObject($PHPDateObject);
}
/**
* EOMONTH.
*
* Returns the date value for the last day of the month that is the indicated number of months
* before or after start_date.
* Use EOMONTH to calculate maturity dates or due dates that fall on the last day of the month.
*
* Excel Function:
* EOMONTH(dateValue,adjustmentMonths)
*
* @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
* Or can be an array of date values
* @param array|int $adjustmentMonths The number of months before or after start_date.
* A positive value for months yields a future date;
* a negative value yields a past date.
* Or can be an array of adjustment values
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of values is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function lastDay(mixed $dateValue, array|float|int|bool|string $adjustmentMonths): array|string|DateTime|float|int
{
if (is_array($dateValue) || is_array($adjustmentMonths)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $dateValue, $adjustmentMonths);
}
try {
$dateValue = Helpers::getDateValue($dateValue, false);
$adjustmentMonths = Helpers::validateNumericNull($adjustmentMonths);
} catch (Exception $e) {
return $e->getMessage();
}
$dateValue = floor($dateValue);
$adjustmentMonths = floor($adjustmentMonths);
// Execute function
$PHPDateObject = Helpers::adjustDateByMonths($dateValue, $adjustmentMonths + 1);
$adjustDays = (int) $PHPDateObject->format('d');
$adjustDaysString = '-' . $adjustDays . ' days';
$PHPDateObject->modify($adjustDaysString);
return Helpers::returnIn3FormatsObject($PHPDateObject);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/NetworkDays.php
================================================
|int|string Interval between the dates
* If an array of values is passed for the $startDate or $endDate arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function count(mixed $startDate, mixed $endDate, mixed ...$dateArgs): array|string|int
{
if (is_array($startDate) || is_array($endDate)) {
return self::evaluateArrayArgumentsSubset(
[self::class, __FUNCTION__],
2,
$startDate,
$endDate,
...$dateArgs
);
}
try {
// Retrieve the mandatory start and end date that are referenced in the function definition
$sDate = Helpers::getDateValue($startDate);
$eDate = Helpers::getDateValue($endDate);
$startDate = min($sDate, $eDate);
$endDate = max($sDate, $eDate);
// Get the optional days
$dateArgs = Functions::flattenArray($dateArgs);
// Test any extra holiday parameters
$holidayArray = [];
foreach ($dateArgs as $holidayDate) {
$holidayArray[] = Helpers::getDateValue($holidayDate);
}
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$startDow = self::calcStartDow($startDate);
$endDow = self::calcEndDow($endDate);
$wholeWeekDays = (int) floor(($endDate - $startDate) / 7) * 5;
$partWeekDays = self::calcPartWeekDays($startDow, $endDow);
// Test any extra holiday parameters
$holidayCountedArray = [];
foreach ($holidayArray as $holidayDate) {
if (($holidayDate >= $startDate) && ($holidayDate <= $endDate)) {
if ((Week::day($holidayDate, 2) < 6) && (!in_array($holidayDate, $holidayCountedArray))) {
--$partWeekDays;
$holidayCountedArray[] = $holidayDate;
}
}
}
return self::applySign($wholeWeekDays + $partWeekDays, $sDate, $eDate);
}
private static function calcStartDow(float $startDate): int
{
$startDow = 6 - (int) Week::day($startDate, 2);
if ($startDow < 0) {
$startDow = 5;
}
return $startDow;
}
private static function calcEndDow(float $endDate): int
{
$endDow = (int) Week::day($endDate, 2);
if ($endDow >= 6) {
$endDow = 0;
}
return $endDow;
}
private static function calcPartWeekDays(int $startDow, int $endDow): int
{
$partWeekDays = $endDow + $startDow;
if ($partWeekDays > 5) {
$partWeekDays -= 5;
}
return $partWeekDays;
}
private static function applySign(int $result, float $sDate, float $eDate): int
{
return ($sDate > $eDate) ? -$result : $result;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Time.php
================================================
|bool|float|int|string $hour A number from 0 (zero) to 32767 representing the hour.
* Any value greater than 23 will be divided by 24 and the remainder
* will be treated as the hour value. For example, TIME(27,0,0) =
* TIME(3,0,0) = .125 or 3:00 AM.
* @param null|array|bool|float|int|string $minute A number from 0 to 32767 representing the minute.
* Any value greater than 59 will be converted to hours and minutes.
* For example, TIME(0,750,0) = TIME(12,30,0) = .520833 or 12:30 PM.
* @param null|array|bool|float|int|string $second A number from 0 to 32767 representing the second.
* Any value greater than 59 will be converted to hours, minutes,
* and seconds. For example, TIME(0,0,2000) = TIME(0,33,22) = .023148
* or 12:33:20 AM
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function fromHMS(array|int|float|bool|null|string $hour, array|int|float|bool|null|string $minute, array|int|float|bool|null|string $second): array|string|float|int|DateTime
{
if (is_array($hour) || is_array($minute) || is_array($second)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $hour, $minute, $second);
}
try {
$hour = self::toIntWithNullBool($hour);
$minute = self::toIntWithNullBool($minute);
$second = self::toIntWithNullBool($second);
} catch (Exception $e) {
return $e->getMessage();
}
self::adjustSecond($second, $minute);
self::adjustMinute($minute, $hour);
if ($hour > 23) {
$hour = $hour % 24;
} elseif ($hour < 0) {
return ExcelError::NAN();
}
// Execute function
$retType = Functions::getReturnDateType();
if ($retType === Functions::RETURNDATE_EXCEL) {
$calendar = SharedDateHelper::getExcelCalendar();
$date = (int) ($calendar !== SharedDateHelper::CALENDAR_WINDOWS_1900);
return (float) SharedDateHelper::formattedPHPToExcel($calendar, 1, $date, $hour, $minute, $second);
}
if ($retType === Functions::RETURNDATE_UNIX_TIMESTAMP) {
return (int) SharedDateHelper::excelToTimestamp(SharedDateHelper::formattedPHPToExcel(1970, 1, 1, $hour, $minute, $second)); // -2147468400; // -2147472000 + 3600
}
// RETURNDATE_PHP_DATETIME_OBJECT
// Hour has already been normalized (0-23) above
$phpDateObject = new DateTime('1900-01-01 ' . $hour . ':' . $minute . ':' . $second);
return $phpDateObject;
}
private static function adjustSecond(int &$second, int &$minute): void
{
if ($second < 0) {
$minute += (int) floor($second / 60);
$second = 60 - abs($second % 60);
if ($second == 60) {
$second = 0;
}
} elseif ($second >= 60) {
$minute += intdiv($second, 60);
$second = $second % 60;
}
}
private static function adjustMinute(int &$minute, int &$hour): void
{
if ($minute < 0) {
$hour += (int) floor($minute / 60);
$minute = 60 - abs($minute % 60);
if ($minute == 60) {
$minute = 0;
}
} elseif ($minute >= 60) {
$hour += intdiv($minute, 60);
$minute = $minute % 60;
}
}
/**
* @param mixed $value expect int
*/
private static function toIntWithNullBool(mixed $value): int
{
$value = $value ?? 0;
if (is_bool($value)) {
$value = (int) $value;
}
if (!is_numeric($value)) {
throw new Exception(ExcelError::VALUE());
}
return (int) $value;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/TimeParts.php
================================================
|int|string Hour
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function hour(mixed $timeValue): array|string|int
{
if (is_array($timeValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $timeValue);
}
try {
Helpers::nullFalseTrueToNumber($timeValue);
if (is_string($timeValue) && !is_numeric($timeValue)) {
$timeValue = Helpers::getTimeValue($timeValue);
}
Helpers::validateNotNegative($timeValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
try {
SharedDateHelper::excelToDateTimeObject($timeValue);
} catch (Throwable) {
return ExcelError::NAN();
}
$timeValue = fmod($timeValue, 1);
$timeValue = SharedDateHelper::excelToDateTimeObject($timeValue);
SharedDateHelper::roundMicroseconds($timeValue);
return (int) $timeValue->format('H');
}
/**
* MINUTE.
*
* Returns the minutes of a time value.
* The minute is given as an integer, ranging from 0 to 59.
*
* Excel Function:
* MINUTE(timeValue)
*
* @param mixed $timeValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard time string
* Or can be an array of date/time values
*
* @return array|int|string Minute
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function minute(mixed $timeValue): array|string|int
{
if (is_array($timeValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $timeValue);
}
try {
Helpers::nullFalseTrueToNumber($timeValue);
if (is_string($timeValue) && !is_numeric($timeValue)) {
$timeValue = Helpers::getTimeValue($timeValue);
}
Helpers::validateNotNegative($timeValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
try {
SharedDateHelper::excelToDateTimeObject($timeValue);
} catch (Throwable) {
return ExcelError::NAN();
}
$timeValue = fmod($timeValue, 1);
$timeValue = SharedDateHelper::excelToDateTimeObject($timeValue);
SharedDateHelper::roundMicroseconds($timeValue);
return (int) $timeValue->format('i');
}
/**
* SECOND.
*
* Returns the seconds of a time value.
* The minute is given as an integer, ranging from 0 to 59.
*
* Excel Function:
* SECOND(timeValue)
*
* @param mixed $timeValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard time string
* Or can be an array of date/time values
*
* @return array|int|string Second
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function second(mixed $timeValue): array|string|int
{
if (is_array($timeValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $timeValue);
}
try {
Helpers::nullFalseTrueToNumber($timeValue);
if (is_string($timeValue) && !is_numeric($timeValue)) {
$timeValue = Helpers::getTimeValue($timeValue);
}
Helpers::validateNotNegative($timeValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
try {
SharedDateHelper::excelToDateTimeObject($timeValue);
} catch (Throwable) {
return ExcelError::NAN();
}
$timeValue = fmod($timeValue, 1);
$timeValue = SharedDateHelper::excelToDateTimeObject($timeValue);
SharedDateHelper::roundMicroseconds($timeValue);
return (int) $timeValue->format('s');
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/TimeValue.php
================================================
|bool|float|int|string $timeValue A text string that represents a time in any one of the Microsoft
* Excel time formats; for example, "6:45 PM" and "18:45" text strings
* within quotation marks that represent time.
* Date information in time_text is ignored.
* Or can be an array of date/time values
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function fromString(null|array|string|int|bool|float $timeValue): array|string|DateTime|int|float
{
if (is_array($timeValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $timeValue);
}
// try to parse as time iff there is at least one digit
if (is_string($timeValue) && !Preg::isMatch('/\d/', $timeValue)) {
return ExcelError::VALUE();
}
$timeValue = trim((string) $timeValue, '"');
if (Preg::isMatch(self::EXTRACT_TIME, $timeValue, $matches)) {
if (empty($matches[6])) { // am/pm
$hour = (int) $matches[0];
$timeValue = ($hour % 24) . $matches[2];
} elseif ($matches[6] === $matches[7]) { // Excel wants space before am/pm
return ExcelError::VALUE();
} else {
$timeValue = $matches[0] . 'm';
}
}
$PHPDateArray = Helpers::dateParse($timeValue);
$retValue = ExcelError::VALUE();
if (Helpers::dateParseSucceeded($PHPDateArray)) {
$hour = $PHPDateArray['hour'];
$minute = $PHPDateArray['minute'];
$second = $PHPDateArray['second'];
// OpenOffice-specific code removed - it works just like Excel
$excelDateValue = SharedDateHelper::formattedPHPToExcel(1900, 1, 1, $hour, $minute, $second) - 1;
$retType = Functions::getReturnDateType();
if ($retType === Functions::RETURNDATE_EXCEL) {
$retValue = (float) $excelDateValue;
} elseif ($retType === Functions::RETURNDATE_UNIX_TIMESTAMP) {
$retValue = (int) SharedDateHelper::excelToTimestamp($excelDateValue + 25569) - 3600;
} else {
$retValue = new DateTime('1900-01-01 ' . $PHPDateArray['hour'] . ':' . $PHPDateArray['minute'] . ':' . $PHPDateArray['second']);
}
}
return $retValue;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/Week.php
================================================
|int $method Week begins on Sunday or Monday
* 1 or omitted Week begins on Sunday.
* 2 Week begins on Monday.
* 11 Week begins on Monday.
* 12 Week begins on Tuesday.
* 13 Week begins on Wednesday.
* 14 Week begins on Thursday.
* 15 Week begins on Friday.
* 16 Week begins on Saturday.
* 17 Week begins on Sunday.
* 21 ISO (Jan. 4 is week 1, begins on Monday).
* Or can be an array of methods
*
* @return array|int|string Week Number
* If an array of values is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function number(mixed $dateValue, array|int|string|null $method = Constants::STARTWEEK_SUNDAY): array|int|string
{
if (is_array($dateValue) || is_array($method)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $dateValue, $method);
}
$origDateValueNull = empty($dateValue);
try {
$method = self::validateMethod($method);
if ($dateValue === null) { // boolean not allowed
$dateValue = (SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_MAC_1904 || $method === Constants::DOW_SUNDAY) ? 0 : 1;
}
$dateValue = self::validateDateValue($dateValue);
if (!$dateValue && self::buggyWeekNum1900($method)) {
// This seems to be an additional Excel bug.
return 0;
}
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$PHPDateObject = SharedDateHelper::excelToDateTimeObject($dateValue);
if ($method == Constants::STARTWEEK_MONDAY_ISO) {
Helpers::silly1900($PHPDateObject);
return (int) $PHPDateObject->format('W');
}
if (self::buggyWeekNum1904($method, $origDateValueNull, $PHPDateObject)) {
return 0;
}
Helpers::silly1900($PHPDateObject, '+ 5 years'); // 1905 calendar matches
$dayOfYear = (int) $PHPDateObject->format('z');
$PHPDateObject->modify('-' . $dayOfYear . ' days');
$firstDayOfFirstWeek = (int) $PHPDateObject->format('w');
$daysInFirstWeek = (6 - $firstDayOfFirstWeek + $method) % 7;
$daysInFirstWeek += 7 * !$daysInFirstWeek;
$endFirstWeek = $daysInFirstWeek - 1;
$weekOfYear = floor(($dayOfYear - $endFirstWeek + 13) / 7);
return (int) $weekOfYear;
}
/**
* ISOWEEKNUM.
*
* Returns the ISO 8601 week number of the year for a specified date.
*
* Excel Function:
* ISOWEEKNUM(dateValue)
*
* @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
* Or can be an array of date values
*
* @return array|int|string Week Number
* If an array of numbers is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function isoWeekNumber(mixed $dateValue): array|int|string
{
if (is_array($dateValue)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $dateValue);
}
if (self::apparentBug($dateValue)) {
return 52;
}
try {
$dateValue = Helpers::getDateValue($dateValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$PHPDateObject = SharedDateHelper::excelToDateTimeObject($dateValue);
Helpers::silly1900($PHPDateObject);
return (int) $PHPDateObject->format('W');
}
/**
* WEEKDAY.
*
* Returns the day of the week for a specified date. The day is given as an integer
* ranging from 0 to 7 (dependent on the requested style).
*
* Excel Function:
* WEEKDAY(dateValue[,style])
*
* @param null|array|bool|float|int|string $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
* Or can be an array of date values
* @param mixed $style A number that determines the type of return value
* 1 or omitted Numbers 1 (Sunday) through 7 (Saturday).
* 2 Numbers 1 (Monday) through 7 (Sunday).
* 3 Numbers 0 (Monday) through 6 (Sunday).
* Or can be an array of styles
*
* @return array|int|string Day of the week value
* If an array of values is passed as the argument, then the returned result will also be an array
* with the same dimensions
*/
public static function day(null|array|float|int|string|bool $dateValue, mixed $style = 1): array|string|int
{
if (is_array($dateValue) || is_array($style)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $dateValue, $style);
}
try {
$dateValue = Helpers::getDateValue($dateValue);
$style = self::validateStyle($style);
} catch (Exception $e) {
return $e->getMessage();
}
// Execute function
$PHPDateObject = SharedDateHelper::excelToDateTimeObject($dateValue);
Helpers::silly1900($PHPDateObject);
$DoW = (int) $PHPDateObject->format('w');
switch ($style) {
case 1:
++$DoW;
break;
case 2:
$DoW = self::dow0Becomes7($DoW);
break;
case 3:
$DoW = self::dow0Becomes7($DoW) - 1;
break;
}
return $DoW;
}
/**
* @param mixed $style expect int
*/
private static function validateStyle(mixed $style): int
{
if (!is_numeric($style)) {
throw new Exception(ExcelError::VALUE());
}
$style = (int) $style;
if (($style < 1) || ($style > 3)) {
throw new Exception(ExcelError::NAN());
}
return $style;
}
private static function dow0Becomes7(int $DoW): int
{
return ($DoW === 0) ? 7 : $DoW;
}
/**
* @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
*/
private static function apparentBug(mixed $dateValue): bool
{
if (SharedDateHelper::getExcelCalendar() !== SharedDateHelper::CALENDAR_MAC_1904) {
if (is_bool($dateValue)) {
return true;
}
if (is_numeric($dateValue) && !((int) $dateValue)) {
return true;
}
}
return false;
}
/**
* Validate dateValue parameter.
*/
private static function validateDateValue(mixed $dateValue): float
{
if (is_bool($dateValue)) {
throw new Exception(ExcelError::VALUE());
}
return Helpers::getDateValue($dateValue);
}
/**
* Validate method parameter.
*/
private static function validateMethod(mixed $method): int
{
if ($method === null) {
$method = Constants::STARTWEEK_SUNDAY;
}
if (!is_numeric($method)) {
throw new Exception(ExcelError::VALUE());
}
$method = (int) $method;
if (!array_key_exists($method, Constants::METHODARR)) {
throw new Exception(ExcelError::NAN());
}
$method = Constants::METHODARR[$method];
return $method;
}
private static function buggyWeekNum1900(int $method): bool
{
return $method === Constants::DOW_SUNDAY && SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_WINDOWS_1900;
}
private static function buggyWeekNum1904(int $method, bool $origNull, DateTime $dateObject): bool
{
// This appears to be another Excel bug.
return $method === Constants::DOW_SUNDAY && SharedDateHelper::getExcelCalendar() === SharedDateHelper::CALENDAR_MAC_1904
&& !$origNull && $dateObject->format('Y-m-d') === '1904-01-01';
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/WorkDay.php
================================================
|mixed $startDate Excel date serial value (float), PHP date timestamp (integer),
* PHP DateTime object, or a standard date string
* Or can be an array of date values
* @param array|int $endDays The number of nonweekend and nonholiday days before or after
* startDate. A positive value for days yields a future date; a
* negative value yields a past date.
* Or can be an array of int values
* @param null|mixed $dateArgs An array of dates (such as holidays) to exclude from the calculation
*
* @return array|DateTime|float|int|string Excel date/time serial value, PHP date/time serial value or PHP date/time object,
* depending on the value of the ReturnDateType flag
* If an array of values is passed for the $startDate or $endDays,arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function date(mixed $startDate, array|int|string $endDays, mixed ...$dateArgs): array|float|int|DateTime|string
{
if (is_array($startDate) || is_array($endDays)) {
return self::evaluateArrayArgumentsSubset(
[self::class, __FUNCTION__],
2,
$startDate,
$endDays,
...$dateArgs
);
}
// Retrieve the mandatory start date and days that are referenced in the function definition
try {
$startDate = Helpers::getDateValue($startDate);
$endDays = Helpers::validateNumericNull($endDays);
$holidayArray = array_map([Helpers::class, 'getDateValue'], Functions::flattenArray($dateArgs));
} catch (Exception $e) {
return $e->getMessage();
}
$startDate = (float) floor($startDate);
$endDays = (int) floor($endDays);
// If endDays is 0, we always return startDate
if ($endDays == 0) {
return $startDate;
}
if ($endDays < 0) {
return self::decrementing($startDate, $endDays, $holidayArray);
}
return self::incrementing($startDate, $endDays, $holidayArray);
}
/**
* Use incrementing logic to determine Workday.
*
* @param array $holidayArray
*/
private static function incrementing(float $startDate, int $endDays, array $holidayArray): float|int|DateTime
{
// Adjust the start date if it falls over a weekend
$startDoW = self::getWeekDay($startDate, 3);
if ($startDoW >= 5) {
$startDate += 7 - $startDoW;
--$endDays;
}
// Add endDays
$endDate = (float) $startDate + ((int) ($endDays / 5) * 7);
$endDays = $endDays % 5;
while ($endDays > 0) {
++$endDate;
// Adjust the calculated end date if it falls over a weekend
$endDow = self::getWeekDay($endDate, 3);
if ($endDow >= 5) {
$endDate += 7 - $endDow;
}
--$endDays;
}
// Test any extra holiday parameters
if (!empty($holidayArray)) {
$endDate = self::incrementingArray($startDate, $endDate, $holidayArray);
}
return Helpers::returnIn3FormatsFloat($endDate);
}
/** @param array $holidayArray */
private static function incrementingArray(float $startDate, float $endDate, array $holidayArray): float
{
$holidayCountedArray = $holidayDates = [];
foreach ($holidayArray as $holidayDate) {
/** @var float $holidayDate */
if (self::getWeekDay($holidayDate, 3) < 5) {
$holidayDates[] = $holidayDate;
}
}
sort($holidayDates, SORT_NUMERIC);
foreach ($holidayDates as $holidayDate) {
if (($holidayDate >= $startDate) && ($holidayDate <= $endDate)) {
if (!in_array($holidayDate, $holidayCountedArray)) {
++$endDate;
$holidayCountedArray[] = $holidayDate;
}
}
// Adjust the calculated end date if it falls over a weekend
$endDoW = self::getWeekDay($endDate, 3);
if ($endDoW >= 5) {
$endDate += 7 - $endDoW;
}
}
return $endDate;
}
/**
* Use decrementing logic to determine Workday.
*
* @param array $holidayArray
*/
private static function decrementing(float $startDate, int $endDays, array $holidayArray): float|int|DateTime
{
// Adjust the start date if it falls over a weekend
$startDoW = self::getWeekDay($startDate, 3);
if ($startDoW >= 5) {
$startDate += -$startDoW + 4;
++$endDays;
}
// Add endDays
$endDate = (float) $startDate + ((int) ($endDays / 5) * 7);
$endDays = $endDays % 5;
while ($endDays < 0) {
--$endDate;
// Adjust the calculated end date if it falls over a weekend
$endDow = self::getWeekDay($endDate, 3);
if ($endDow >= 5) {
$endDate += 4 - $endDow;
}
++$endDays;
}
// Test any extra holiday parameters
if (!empty($holidayArray)) {
$endDate = self::decrementingArray($startDate, $endDate, $holidayArray);
}
return Helpers::returnIn3FormatsFloat($endDate);
}
/** @param array $holidayArray */
private static function decrementingArray(float $startDate, float $endDate, array $holidayArray): float
{
$holidayCountedArray = $holidayDates = [];
foreach ($holidayArray as $holidayDate) {
/** @var float $holidayDate */
if (self::getWeekDay($holidayDate, 3) < 5) {
$holidayDates[] = $holidayDate;
}
}
rsort($holidayDates, SORT_NUMERIC);
foreach ($holidayDates as $holidayDate) {
if (($holidayDate <= $startDate) && ($holidayDate >= $endDate)) {
if (!in_array($holidayDate, $holidayCountedArray)) {
--$endDate;
$holidayCountedArray[] = $holidayDate;
}
}
// Adjust the calculated end date if it falls over a weekend
$endDoW = self::getWeekDay($endDate, 3);
/** int $endDoW */
if ($endDoW >= 5) {
$endDate += -$endDoW + 4;
}
}
return $endDate;
}
private static function getWeekDay(float $date, int $wd): int
{
$result = Functions::scalar(Week::day($date, $wd));
return is_int($result) ? $result : -1;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/DateTimeExcel/YearFrac.php
================================================
|int $method Method used for the calculation
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
* Or can be an array of methods
*
* @return array|float|int|string fraction of the year, or a string containing an error
* If an array of values is passed for the $startDate or $endDays,arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function fraction(mixed $startDate, mixed $endDate, array|int|string|null $method = 0): array|string|int|float
{
if (is_array($startDate) || is_array($endDate) || is_array($method)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $startDate, $endDate, $method);
}
try {
$method = (int) Helpers::validateNumericNull($method);
$sDate = Helpers::getDateValue($startDate);
$eDate = Helpers::getDateValue($endDate);
$sDate = self::excelBug($sDate, $startDate, $endDate, $method);
$eDate = self::excelBug($eDate, $endDate, $startDate, $method);
$startDate = min($sDate, $eDate);
$endDate = max($sDate, $eDate);
} catch (Exception $e) {
return $e->getMessage();
}
return match ($method) {
0 => Helpers::floatOrInt(Days360::between($startDate, $endDate)) / 360,
1 => self::method1($startDate, $endDate),
2 => Helpers::floatOrInt(Difference::interval($startDate, $endDate)) / 360,
3 => Helpers::floatOrInt(Difference::interval($startDate, $endDate)) / 365,
4 => Helpers::floatOrInt(Days360::between($startDate, $endDate, true)) / 360,
default => ExcelError::NAN(),
};
}
/**
* Excel 1900 calendar treats date argument of null as 1900-01-00. Really.
*/
private static function excelBug(float $sDate, mixed $startDate, mixed $endDate, int $method): float
{
if (Functions::getCompatibilityMode() !== Functions::COMPATIBILITY_OPENOFFICE && SharedDateHelper::getExcelCalendar() !== SharedDateHelper::CALENDAR_MAC_1904) {
if ($endDate === null && $startDate !== null) {
if (DateParts::month($sDate) == 12 && DateParts::day($sDate) === 31 && $method === 0) {
$sDate += 2;
} else {
++$sDate;
}
}
}
return $sDate;
}
private static function method1(float $startDate, float $endDate): float
{
$days = Helpers::floatOrInt(Difference::interval($startDate, $endDate));
$startYear = (int) DateParts::year($startDate);
$endYear = (int) DateParts::year($endDate);
$years = $endYear - $startYear + 1;
$startMonth = (int) DateParts::month($startDate);
$startDay = (int) DateParts::day($startDate);
$endMonth = (int) DateParts::month($endDate);
$endDay = (int) DateParts::day($endDate);
$startMonthDay = 100 * $startMonth + $startDay;
$endMonthDay = 100 * $endMonth + $endDay;
if ($years == 1) {
$tmpCalcAnnualBasis = 365 + (int) Helpers::isLeapYear($endYear);
} elseif ($years == 2 && $startMonthDay >= $endMonthDay) {
if (Helpers::isLeapYear($startYear)) {
$tmpCalcAnnualBasis = 365 + (int) ($startMonthDay <= 229);
} elseif (Helpers::isLeapYear($endYear)) {
$tmpCalcAnnualBasis = 365 + (int) ($endMonthDay >= 229);
} else {
$tmpCalcAnnualBasis = 365;
}
} else {
$tmpCalcAnnualBasis = 0;
for ($year = $startYear; $year <= $endYear; ++$year) {
$tmpCalcAnnualBasis += 365 + (int) Helpers::isLeapYear($year);
}
$tmpCalcAnnualBasis /= $years;
}
return $days / $tmpCalcAnnualBasis;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/ArrayArgumentHelper.php
================================================
indexStart = (int) array_shift($keys);
$this->rows = $this->rows($arguments);
$this->columns = $this->columns($arguments);
$this->argumentCount = count($arguments);
$this->arguments = $this->flattenSingleCellArrays($arguments, $this->rows, $this->columns);
$this->rows = $this->rows($arguments);
$this->columns = $this->columns($arguments);
if ($this->arrayArguments() > 2) {
throw new Exception('Formulae with more than two array arguments are not supported');
}
}
/** @return mixed[] */
public function arguments(): array
{
return $this->arguments;
}
public function hasArrayArgument(): bool
{
return $this->arrayArguments() > 0;
}
public function getFirstArrayArgumentNumber(): int
{
$rowArrays = $this->filterArray($this->rows);
$columnArrays = $this->filterArray($this->columns);
for ($index = $this->indexStart; $index < $this->argumentCount; ++$index) {
if (isset($rowArrays[$index]) || isset($columnArrays[$index])) {
return ++$index;
}
}
return 0;
}
public function getSingleRowVector(): ?int
{
$rowVectors = $this->getRowVectors();
return count($rowVectors) === 1 ? array_pop($rowVectors) : null;
}
/** @return int[] */
private function getRowVectors(): array
{
$rowVectors = [];
for ($index = $this->indexStart; $index < ($this->indexStart + $this->argumentCount); ++$index) {
if ($this->rows[$index] === 1 && $this->columns[$index] > 1) {
$rowVectors[] = $index;
}
}
return $rowVectors;
}
public function getSingleColumnVector(): ?int
{
$columnVectors = $this->getColumnVectors();
return count($columnVectors) === 1 ? array_pop($columnVectors) : null;
}
/** @return int[] */
private function getColumnVectors(): array
{
$columnVectors = [];
for ($index = $this->indexStart; $index < ($this->indexStart + $this->argumentCount); ++$index) {
if ($this->rows[$index] > 1 && $this->columns[$index] === 1) {
$columnVectors[] = $index;
}
}
return $columnVectors;
}
/** @return int[] */
public function getMatrixPair(): array
{
for ($i = $this->indexStart; $i < ($this->indexStart + $this->argumentCount - 1); ++$i) {
for ($j = $i + 1; $j < $this->argumentCount; ++$j) {
if (isset($this->rows[$i], $this->rows[$j])) {
return [$i, $j];
}
}
}
return [];
}
public function isVector(int $argument): bool
{
return $this->rows[$argument] === 1 || $this->columns[$argument] === 1;
}
public function isRowVector(int $argument): bool
{
return $this->rows[$argument] === 1;
}
public function isColumnVector(int $argument): bool
{
return $this->columns[$argument] === 1;
}
public function rowCount(int $argument): int
{
return $this->rows[$argument];
}
public function columnCount(int $argument): int
{
return $this->columns[$argument];
}
/**
* @param mixed[] $arguments
*
* @return int[]
*/
private function rows(array $arguments): array
{
return array_map(
fn ($argument): int => is_countable($argument) ? count($argument) : 1,
$arguments
);
}
/**
* @param mixed[] $arguments
*
* @return int[]
*/
private function columns(array $arguments): array
{
return array_map(
fn (mixed $argument): int => is_array($argument) && is_array($argument[array_keys($argument)[0]])
? count($argument[array_keys($argument)[0]])
: 1,
$arguments
);
}
public function arrayArguments(): int
{
$count = 0;
foreach (array_keys($this->arguments) as $argument) {
if ($this->rows[$argument] > 1 || $this->columns[$argument] > 1) {
++$count;
}
}
return $count;
}
/**
* @param mixed[] $arguments
* @param int[] $rows
* @param int[] $columns
*
* @return mixed[]
*/
private function flattenSingleCellArrays(array $arguments, array $rows, array $columns): array
{
foreach ($arguments as $index => $argument) {
if ($rows[$index] === 1 && $columns[$index] === 1) {
while (is_array($argument)) {
$argument = array_pop($argument);
}
$arguments[$index] = $argument;
}
}
return $arguments;
}
/**
* @param mixed[] $array
*
* @return mixed[]
*/
private function filterArray(array $array): array
{
return array_filter(
$array,
fn ($value): bool => $value > 1
);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/ArrayArgumentProcessor.php
================================================
hasArrayArgument() === false) {
return [$method(...$arguments)];
}
if (self::$arrayArgumentHelper->arrayArguments() === 1) {
$nthArgument = self::$arrayArgumentHelper->getFirstArrayArgumentNumber();
return self::evaluateNthArgumentAsArray($method, $nthArgument, ...$arguments);
}
$singleRowVectorIndex = self::$arrayArgumentHelper->getSingleRowVector();
$singleColumnVectorIndex = self::$arrayArgumentHelper->getSingleColumnVector();
if ($singleRowVectorIndex !== null && $singleColumnVectorIndex !== null) {
// Basic logic for a single row vector and a single column vector
return self::evaluateVectorPair($method, $singleRowVectorIndex, $singleColumnVectorIndex, ...$arguments);
}
$matrixPair = self::$arrayArgumentHelper->getMatrixPair();
if ($matrixPair !== []) {
if (
(self::$arrayArgumentHelper->isVector($matrixPair[0]) === true
&& self::$arrayArgumentHelper->isVector($matrixPair[1]) === false)
|| (self::$arrayArgumentHelper->isVector($matrixPair[0]) === false
&& self::$arrayArgumentHelper->isVector($matrixPair[1]) === true)
) {
// Logic for a matrix and a vector (row or column)
return self::evaluateVectorMatrixPair($method, $matrixPair, ...$arguments);
}
// Logic for matrix/matrix, column vector/column vector or row vector/row vector
return self::evaluateMatrixPair($method, $matrixPair, ...$arguments);
}
// Still need to work out the logic for more than two array arguments,
// For the moment, we're throwing an Exception when we initialise the ArrayArgumentHelper
return ['#VALUE!'];
}
/**
* @param int[] $matrixIndexes
*
* @return mixed[]
*/
private static function evaluateVectorMatrixPair(callable $method, array $matrixIndexes, mixed ...$arguments): array
{
$matrix2 = array_pop($matrixIndexes) ?? throw new Exception('empty array 2');
/** @var mixed[][] $matrixValues2 */
$matrixValues2 = $arguments[$matrix2];
$matrix1 = array_pop($matrixIndexes) ?? throw new Exception('empty array 1');
/** @var mixed[][] $matrixValues1 */
$matrixValues1 = $arguments[$matrix1];
/** @var non-empty-array */
$matrix12 = [$matrix1, $matrix2];
$rows = min(array_map(self::$arrayArgumentHelper->rowCount(...), $matrix12));
$columns = min(array_map(self::$arrayArgumentHelper->columnCount(...), $matrix12));
if ($rows === 1) {
$rows = max(array_map(self::$arrayArgumentHelper->rowCount(...), $matrix12));
}
if ($columns === 1) {
$columns = max(array_map(self::$arrayArgumentHelper->columnCount(...), $matrix12));
}
$result = [];
for ($rowIndex = 0; $rowIndex < $rows; ++$rowIndex) {
for ($columnIndex = 0; $columnIndex < $columns; ++$columnIndex) {
$rowIndex1 = self::$arrayArgumentHelper->isRowVector($matrix1) ? 0 : $rowIndex;
$columnIndex1 = self::$arrayArgumentHelper->isColumnVector($matrix1) ? 0 : $columnIndex;
$value1 = $matrixValues1[$rowIndex1][$columnIndex1];
$rowIndex2 = self::$arrayArgumentHelper->isRowVector($matrix2) ? 0 : $rowIndex;
$columnIndex2 = self::$arrayArgumentHelper->isColumnVector($matrix2) ? 0 : $columnIndex;
$value2 = $matrixValues2[$rowIndex2][$columnIndex2];
$arguments[$matrix1] = $value1;
$arguments[$matrix2] = $value2;
$result[$rowIndex][$columnIndex] = $method(...$arguments);
}
}
return $result;
}
/**
* @param array $matrixIndexes
*
* @return mixed[]
*/
private static function evaluateMatrixPair(callable $method, array $matrixIndexes, mixed ...$arguments): array
{
$matrix2 = array_pop($matrixIndexes);
/** @var mixed[][] $matrixValues2 */
$matrixValues2 = $arguments[$matrix2];
$matrix1 = array_pop($matrixIndexes);
/** @var mixed[][] $matrixValues1 */
$matrixValues1 = $arguments[$matrix1];
$result = [];
foreach ($matrixValues1 as $rowIndex => $row) {
foreach ($row as $columnIndex => $value1) {
if (isset($matrixValues2[$rowIndex][$columnIndex]) === false) {
continue;
}
$value2 = $matrixValues2[$rowIndex][$columnIndex];
$arguments[$matrix1] = $value1;
$arguments[$matrix2] = $value2;
$result[$rowIndex][$columnIndex] = $method(...$arguments);
}
}
return $result;
}
/** @return mixed[] */
private static function evaluateVectorPair(callable $method, int $rowIndex, int $columnIndex, mixed ...$arguments): array
{
$rowVector = Functions::flattenArray($arguments[$rowIndex]);
$columnVector = Functions::flattenArray($arguments[$columnIndex]);
$result = [];
foreach ($columnVector as $column) {
$rowResults = [];
foreach ($rowVector as $row) {
$arguments[$rowIndex] = $row;
$arguments[$columnIndex] = $column;
$rowResults[] = $method(...$arguments);
}
$result[] = $rowResults;
}
return $result;
}
/**
* Note, offset is from 1 (for the first argument) rather than from 0.
*
* @return mixed[]
*/
private static function evaluateNthArgumentAsArray(callable $method, int $nthArgument, mixed ...$arguments): array
{
$values = array_slice($arguments, $nthArgument - 1, 1);
/** @var mixed[] $values */
$values = array_pop($values);
$result = [];
foreach ($values as $value) {
$arguments[$nthArgument - 1] = $value;
$result[] = $method(...$arguments);
}
return $result;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/BranchPruner.php
================================================
branchPruningEnabled = $branchPruningEnabled;
}
public function clearBranchStore(): void
{
$this->branchStoreKeyCounter = 0;
}
public function initialiseForLoop(): void
{
$this->currentCondition = null;
$this->currentOnlyIf = null;
$this->currentOnlyIfNot = null;
$this->previousStoreKey = null;
$this->pendingStoreKey = empty($this->storeKeysStack) ? null : end($this->storeKeysStack);
if ($this->branchPruningEnabled) {
$this->initialiseCondition();
$this->initialiseThen();
$this->initialiseElse();
}
}
private function initialiseCondition(): void
{
if (isset($this->pendingStoreKey, $this->conditionMap[$this->pendingStoreKey]) && $this->conditionMap[$this->pendingStoreKey]) {
$this->currentCondition = $this->pendingStoreKey;
$stackDepth = count($this->storeKeysStack);
if ($stackDepth > 1) {
// nested if
$this->previousStoreKey = $this->storeKeysStack[$stackDepth - 2];
}
}
}
private function initialiseThen(): void
{
if (isset($this->pendingStoreKey, $this->thenMap[$this->pendingStoreKey]) && $this->thenMap[$this->pendingStoreKey]) {
$this->currentOnlyIf = $this->pendingStoreKey;
} elseif (
isset($this->previousStoreKey, $this->thenMap[$this->previousStoreKey])
&& $this->thenMap[$this->previousStoreKey]
) {
$this->currentOnlyIf = $this->previousStoreKey;
}
}
private function initialiseElse(): void
{
if (isset($this->pendingStoreKey, $this->elseMap[$this->pendingStoreKey]) && $this->elseMap[$this->pendingStoreKey]) {
$this->currentOnlyIfNot = $this->pendingStoreKey;
} elseif (
isset($this->previousStoreKey, $this->elseMap[$this->previousStoreKey])
&& $this->elseMap[$this->previousStoreKey]
) {
$this->currentOnlyIfNot = $this->previousStoreKey;
}
}
public function decrementDepth(): void
{
if (!empty($this->pendingStoreKey)) {
--$this->braceDepthMap[$this->pendingStoreKey];
}
}
public function incrementDepth(): void
{
if (!empty($this->pendingStoreKey)) {
++$this->braceDepthMap[$this->pendingStoreKey];
}
}
public function functionCall(string $functionName): void
{
if ($this->branchPruningEnabled && ($functionName === 'IF(')) {
// we handle a new if
$this->pendingStoreKey = $this->getUnusedBranchStoreKey();
$this->storeKeysStack[] = $this->pendingStoreKey;
$this->conditionMap[$this->pendingStoreKey] = true;
$this->braceDepthMap[$this->pendingStoreKey] = 0;
} elseif (!empty($this->pendingStoreKey) && array_key_exists($this->pendingStoreKey, $this->braceDepthMap)) {
// this is not an if but we go deeper
++$this->braceDepthMap[$this->pendingStoreKey];
}
}
public function argumentSeparator(): void
{
if (!empty($this->pendingStoreKey) && $this->braceDepthMap[$this->pendingStoreKey] === 0) {
// We must go to the IF next argument
if ($this->conditionMap[$this->pendingStoreKey]) {
$this->conditionMap[$this->pendingStoreKey] = false;
$this->thenMap[$this->pendingStoreKey] = true;
} elseif ($this->thenMap[$this->pendingStoreKey]) {
$this->thenMap[$this->pendingStoreKey] = false;
$this->elseMap[$this->pendingStoreKey] = true;
} elseif ($this->elseMap[$this->pendingStoreKey]) {
throw new Exception('Reaching fourth argument of an IF');
}
}
}
public function closingBrace(mixed $value): void
{
if (!empty($this->pendingStoreKey) && $this->braceDepthMap[$this->pendingStoreKey] === -1) {
// we are closing an IF(
if ($value !== 'IF(') {
throw new Exception('Parser bug we should be in an "IF("');
}
if ($this->conditionMap[$this->pendingStoreKey]) {
throw new Exception('We should not be expecting a condition');
}
$this->thenMap[$this->pendingStoreKey] = false;
$this->elseMap[$this->pendingStoreKey] = false;
--$this->braceDepthMap[$this->pendingStoreKey];
array_pop($this->storeKeysStack);
$this->pendingStoreKey = null;
}
}
public function currentCondition(): ?string
{
return $this->currentCondition;
}
public function currentOnlyIf(): ?string
{
return $this->currentOnlyIf;
}
public function currentOnlyIfNot(): ?string
{
return $this->currentOnlyIfNot;
}
private function getUnusedBranchStoreKey(): string
{
$storeKeyValue = 'storeKey-' . $this->branchStoreKeyCounter;
++$this->branchStoreKeyCounter;
return $storeKeyValue;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/CyclicReferenceStack.php
================================================
stack);
}
/**
* Push a new entry onto the stack.
*
* @param int|string $value The value to test
*/
public function push($value): void
{
$this->stack[$value] = $value;
}
/**
* Pop the last entry from the stack.
*/
public function pop(): mixed
{
return array_pop($this->stack);
}
/**
* Test to see if a specified entry exists on the stack.
*
* @param int|string $value The value to test
*/
public function onStack($value): bool
{
return isset($this->stack[$value]);
}
/**
* Clear the stack.
*/
public function clear(): void
{
$this->stack = [];
}
/**
* Return an array of all entries on the stack.
*
* @return mixed[]
*/
public function showStack(): array
{
return $this->stack;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/FormattedNumber.php
================================================
[-+])? *\% *(?[-+])? *(?[0-9]+\.?[0-9*]*(?:E[-+]?[0-9]*)?) *)|(?: *(?[-+])? *(?[0-9]+\.?[0-9]*(?:E[-+]?[0-9]*)?) *\% *))$~i';
// preg_quoted string for major currency symbols, with a %s for locale currency
private const CURRENCY_CONVERSION_LIST = '\$€£¥%s';
/**
* Identify whether a string contains a formatted numeric value,
* and convert it to a numeric if it is.
*
* @param float|string $operand string value to test
*/
public static function convertToNumberIfFormatted(float|string &$operand): bool
{
return self::convertToNumberIfNumeric($operand)
|| self::convertToNumberIfFraction($operand)
|| self::convertToNumberIfPercent($operand)
|| self::convertToNumberIfCurrency($operand);
}
/**
* Identify whether a string contains a numeric value,
* and convert it to a numeric if it is.
*
* @param float|string $operand string value to test
*/
public static function convertToNumberIfNumeric(float|string &$operand): bool
{
$thousandsSeparator = preg_quote(StringHelper::getThousandsSeparator(), '/');
$value = preg_replace(['/(\d)' . $thousandsSeparator . '(\d)/u', '/([+-])\s+(\d)/u'], ['$1$2', '$1$2'], trim("$operand"));
$decimalSeparator = preg_quote(StringHelper::getDecimalSeparator(), '/');
$value = preg_replace(['/(\d)' . $decimalSeparator . '(\d)/u', '/([+-])\s+(\d)/u'], ['$1.$2', '$1$2'], $value ?? '');
if (is_numeric($value)) {
$operand = (float) $value;
return true;
}
return false;
}
/**
* Identify whether a string contains a fractional numeric value,
* and convert it to a numeric if it is.
*
* @param string $operand string value to test
*/
public static function convertToNumberIfFraction(float|string &$operand): bool
{
if (is_string($operand) && preg_match(self::STRING_REGEXP_FRACTION, $operand, $match)) {
$sign = ($match[1] === '-') ? '-' : '+';
$wholePart = ($match[3] === '') ? '' : ($sign . $match[3]);
$fractionFormula = '=' . $wholePart . $sign . $match[4];
/** @var string */
$operandx = Calculation::getInstance()->_calculateFormulaValue($fractionFormula);
$operand = $operandx;
return true;
}
return false;
}
/**
* Identify whether a string contains a percentage, and if so,
* convert it to a numeric.
*
* @param float|string $operand string value to test
*/
public static function convertToNumberIfPercent(float|string &$operand): bool
{
$thousandsSeparator = preg_quote(StringHelper::getThousandsSeparator(), '/');
$value = preg_replace('/(\d)' . $thousandsSeparator . '(\d)/u', '$1$2', trim("$operand"));
$decimalSeparator = preg_quote(StringHelper::getDecimalSeparator(), '/');
$value = preg_replace(['/(\d)' . $decimalSeparator . '(\d)/u', '/([+-])\s+(\d)/u'], ['$1.$2', '$1$2'], $value ?? '');
$match = [];
if ($value !== null && preg_match(self::STRING_REGEXP_PERCENT, $value, $match, PREG_UNMATCHED_AS_NULL)) {
//Calculate the percentage
$sign = ($match['PrefixedSign'] ?? $match['PrefixedSign2'] ?? $match['PostfixedSign']) ?? '';
$operand = (float) ($sign . ($match['PostfixedValue'] ?? $match['PrefixedValue'])) / 100;
return true;
}
return false;
}
/**
* Identify whether a string contains a currency value, and if so,
* convert it to a numeric.
*
* @param float|string $operand string value to test
*/
public static function convertToNumberIfCurrency(float|string &$operand): bool
{
$currencyRegexp = self::currencyMatcherRegexp();
$thousandsSeparator = preg_quote(StringHelper::getThousandsSeparator(), '/');
$value = preg_replace('/(\d)' . $thousandsSeparator . '(\d)/u', '$1$2', "$operand");
$match = [];
if ($value !== null && preg_match($currencyRegexp, $value, $match, PREG_UNMATCHED_AS_NULL)) {
//Determine the sign
$sign = ($match['PrefixedSign'] ?? $match['PrefixedSign2'] ?? $match['PostfixedSign']) ?? '';
$decimalSeparator = StringHelper::getDecimalSeparator();
//Cast to a float
$intermediate = (string) ($match['PostfixedValue'] ?? $match['PrefixedValue']);
$intermediate = str_replace($decimalSeparator, '.', $intermediate);
if (is_numeric($intermediate)) {
$operand = (float) ($sign . str_replace($decimalSeparator, '.', $intermediate));
return true;
}
}
return false;
}
public static function currencyMatcherRegexp(): string
{
$currencyCodes = sprintf(self::CURRENCY_CONVERSION_LIST, preg_quote(StringHelper::getCurrencyCode(), '/'));
$decimalSeparator = preg_quote(StringHelper::getDecimalSeparator(), '/');
return '~^(?:(?: *(?[-+])? *(?[' . $currencyCodes . ']) *(?[-+])? *(?[0-9]+[' . $decimalSeparator . ']?[0-9*]*(?:E[-+]?[0-9]*)?) *)|(?: *(?[-+])? *(?[0-9]+' . $decimalSeparator . '?[0-9]*(?:E[-+]?[0-9]*)?) *(?[' . $currencyCodes . ']) *))$~ui';
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/Logger.php
================================================
cellStack = $stack;
}
/**
* Enable/Disable Calculation engine logging.
*/
public function setWriteDebugLog(bool $writeDebugLog): void
{
$this->writeDebugLog = $writeDebugLog;
}
/**
* Return whether calculation engine logging is enabled or disabled.
*/
public function getWriteDebugLog(): bool
{
return $this->writeDebugLog;
}
/**
* Enable/Disable echoing of debug log information.
*/
public function setEchoDebugLog(bool $echoDebugLog): void
{
$this->echoDebugLog = $echoDebugLog;
}
/**
* Return whether echoing of debug log information is enabled or disabled.
*/
public function getEchoDebugLog(): bool
{
return $this->echoDebugLog;
}
/**
* Write an entry to the calculation engine debug log.
*/
public function writeDebugLog(string $message, mixed ...$args): void
{
// Only write the debug log if logging is enabled
if ($this->writeDebugLog) {
$message = sprintf($message, ...$args); //* @phpstan-ignore-line
$cellReference = implode(' -> ', $this->cellStack->showStack());
if ($this->echoDebugLog) {
echo $cellReference,
($this->cellStack->count() > 0 ? ' => ' : ''),
$message,
PHP_EOL;
}
$this->debugLog[] = $cellReference
. ($this->cellStack->count() > 0 ? ' => ' : '')
. $message;
}
}
/**
* Write a series of entries to the calculation engine debug log.
*
* @param string[] $args
*/
public function mergeDebugLog(array $args): void
{
if ($this->writeDebugLog) {
foreach ($args as $entry) {
$this->writeDebugLog($entry);
}
}
}
/**
* Clear the calculation engine debug log.
*/
public function clearLog(): void
{
$this->debugLog = [];
}
/**
* Return the calculation engine debug log.
*
* @return string[]
*/
public function getLog(): array
{
return $this->debugLog;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engine/Operands/Operand.php
================================================
value = $structuredReference;
}
/** @param string[] $matches */
public static function fromParser(string $formula, int $index, array $matches): self
{
$val = $matches[0];
$srCount = substr_count($val, self::OPEN_BRACE)
- substr_count($val, self::CLOSE_BRACE);
while ($srCount > 0) {
$srIndex = strlen($val);
$srStringRemainder = substr($formula, $index + $srIndex);
$closingPos = strpos($srStringRemainder, self::CLOSE_BRACE);
if ($closingPos === false) {
throw new Exception("Formula Error: No closing ']' to match opening '['");
}
$srStringRemainder = substr($srStringRemainder, 0, $closingPos + 1);
--$srCount;
if (str_contains($srStringRemainder, self::OPEN_BRACE)) {
++$srCount;
}
$val .= $srStringRemainder;
}
return new self($val);
}
/**
* @throws Exception
* @throws \PhpOffice\PhpSpreadsheet\Exception
*/
public function parse(Cell $cell): string
{
$this->getTableStructure($cell);
$cellRange = ($this->isRowReference()) ? $this->getRowReference($cell) : $this->getColumnReference();
$sheetName = '';
$worksheet = $this->table->getWorksheet();
if ($worksheet !== null && $worksheet !== $cell->getWorksheet()) {
$sheetName = "'" . $worksheet->getTitle() . "'!";
}
return $sheetName . $cellRange;
}
private function isRowReference(): bool
{
return str_contains($this->value, '[@')
|| str_contains($this->value, '[' . self::ITEM_SPECIFIER_THIS_ROW . ']');
}
/**
* @throws Exception
* @throws \PhpOffice\PhpSpreadsheet\Exception
*/
private function getTableStructure(Cell $cell): void
{
preg_match(self::TABLE_REFERENCE, $this->value, $matches);
$this->tableName = $matches[1];
$this->table = ($this->tableName === '')
? $this->getTableForCell($cell)
: $this->getTableByName($cell);
$this->reference = $matches[2];
$tableRange = Coordinate::getRangeBoundaries($this->table->getRange());
$this->headersRow = ($this->table->getShowHeaderRow()) ? (int) $tableRange[0][1] : null;
$this->firstDataRow = ($this->table->getShowHeaderRow()) ? (int) $tableRange[0][1] + 1 : $tableRange[0][1];
$this->totalsRow = ($this->table->getShowTotalsRow()) ? (int) $tableRange[1][1] : null;
$this->lastDataRow = ($this->table->getShowTotalsRow()) ? (int) $tableRange[1][1] - 1 : $tableRange[1][1];
$cellParam = $cell;
$worksheet = $this->table->getWorksheet();
if ($worksheet !== null && $worksheet !== $cell->getWorksheet()) {
$cellParam = $worksheet->getCell('A1');
}
$this->columns = $this->getColumns($cellParam, $tableRange);
}
/**
* @throws Exception
* @throws \PhpOffice\PhpSpreadsheet\Exception
*/
private function getTableForCell(Cell $cell): Table
{
$tables = $cell->getWorksheet()->getTableCollection();
foreach ($tables as $table) {
/** @var Table $table */
$range = $table->getRange();
if ($cell->isInRange($range) === true) {
$this->tableName = $table->getName();
return $table;
}
}
throw new Exception('Table for Structured Reference cannot be identified');
}
/**
* @throws Exception
* @throws \PhpOffice\PhpSpreadsheet\Exception
*/
private function getTableByName(Cell $cell): Table
{
$table = $cell->getWorksheet()->getTableByName($this->tableName);
if ($table === null) {
$spreadsheet = $cell->getWorksheet()->getParent();
if ($spreadsheet !== null) {
$table = $spreadsheet->getTableByName($this->tableName);
}
}
if ($table === null) {
throw new Exception("Table {$this->tableName} for Structured Reference cannot be located");
}
return $table;
}
/**
* @param array{array{string, int}, array{string, int}} $tableRange
*
* @return mixed[]
*/
private function getColumns(Cell $cell, array $tableRange): array
{
$worksheet = $cell->getWorksheet();
$cellReference = $cell->getCoordinate();
$columns = [];
$lastColumn = StringHelper::stringIncrement($tableRange[1][0]);
for ($column = $tableRange[0][0]; $column !== $lastColumn; StringHelper::stringIncrement($column)) {
/** @var string $column */
$columns[$column] = $worksheet
->getCell($column . ($this->headersRow ?? ($this->firstDataRow - 1)))
->getCalculatedValue();
}
$worksheet->getCell($cellReference);
return $columns;
}
private function getRowReference(Cell $cell): string
{
$reference = str_replace("\u{a0}", ' ', $this->reference);
/** @var string $reference */
$reference = str_replace('[' . self::ITEM_SPECIFIER_THIS_ROW . '],', '', $reference);
foreach ($this->columns as $columnId => $columnName) {
$columnName = str_replace("\u{a0}", ' ', $columnName); //* @phpstan-ignore-line
$reference = $this->adjustRowReference($columnName, $reference, $cell, $columnId);
}
return $this->validateParsedReference(trim($reference, '[]@, '));
}
private function adjustRowReference(string $columnName, string $reference, Cell $cell, string $columnId): string
{
if ($columnName !== '') {
$cellReference = $columnId . $cell->getRow();
$pattern1 = '/\[' . preg_quote($columnName, '/') . '\]/miu';
$pattern2 = '/@' . preg_quote($columnName, '/') . '/miu';
if (preg_match($pattern1, $reference) === 1) {
$reference = preg_replace($pattern1, $cellReference, $reference);
} elseif (preg_match($pattern2, $reference) === 1) {
$reference = preg_replace($pattern2, $cellReference, $reference);
}
/** @var string $reference */
}
return $reference;
}
/**
* @throws Exception
* @throws \PhpOffice\PhpSpreadsheet\Exception
*/
private function getColumnReference(): string
{
$reference = str_replace("\u{a0}", ' ', $this->reference);
$startRow = ($this->totalsRow === null) ? $this->lastDataRow : $this->totalsRow;
$endRow = ($this->headersRow === null) ? $this->firstDataRow : $this->headersRow;
[$startRow, $endRow] = $this->getRowsForColumnReference($reference, $startRow, $endRow);
$reference = $this->getColumnsForColumnReference($reference, $startRow, $endRow);
$reference = trim($reference, '[]@, ');
if (substr_count($reference, ':') > 1) {
$cells = explode(':', $reference);
$firstCell = array_shift($cells);
$lastCell = array_pop($cells);
$reference = "{$firstCell}:{$lastCell}";
}
return $this->validateParsedReference($reference);
}
/**
* @throws Exception
* @throws \PhpOffice\PhpSpreadsheet\Exception
*/
private function validateParsedReference(string $reference): string
{
if (preg_match('/^' . Calculation::CALCULATION_REGEXP_CELLREF . ':' . Calculation::CALCULATION_REGEXP_CELLREF . '$/miu', $reference) !== 1) {
if (preg_match('/^' . Calculation::CALCULATION_REGEXP_CELLREF . '$/miu', $reference) !== 1) {
throw new Exception(
"Invalid Structured Reference {$this->reference} {$reference}",
Exception::CALCULATION_ENGINE_PUSH_TO_STACK
);
}
}
return $reference;
}
private function fullData(int $startRow, int $endRow): string
{
$columns = array_keys($this->columns);
$firstColumn = array_shift($columns);
$lastColumn = (empty($columns)) ? $firstColumn : array_pop($columns);
return "{$firstColumn}{$startRow}:{$lastColumn}{$endRow}";
}
private function getMinimumRow(string $reference): int
{
return match ($reference) {
self::ITEM_SPECIFIER_ALL, self::ITEM_SPECIFIER_HEADERS => $this->headersRow ?? $this->firstDataRow,
self::ITEM_SPECIFIER_DATA => $this->firstDataRow,
self::ITEM_SPECIFIER_TOTALS => $this->totalsRow ?? $this->lastDataRow,
default => $this->headersRow ?? $this->firstDataRow,
};
}
private function getMaximumRow(string $reference): int
{
return match ($reference) {
self::ITEM_SPECIFIER_HEADERS => $this->headersRow ?? $this->firstDataRow,
self::ITEM_SPECIFIER_DATA => $this->lastDataRow,
self::ITEM_SPECIFIER_ALL, self::ITEM_SPECIFIER_TOTALS => $this->totalsRow ?? $this->lastDataRow,
default => $this->totalsRow ?? $this->lastDataRow,
};
}
public function value(): string
{
return $this->value;
}
/**
* @return array
*/
private function getRowsForColumnReference(string &$reference, int $startRow, int $endRow): array
{
$rowsSelected = false;
foreach (self::ITEM_SPECIFIER_ROWS_SET as $rowReference) {
$pattern = '/\[' . $rowReference . '\]/mui';
if (preg_match($pattern, $reference) === 1) {
if (($rowReference === self::ITEM_SPECIFIER_HEADERS) && ($this->table->getShowHeaderRow() === false)) {
throw new Exception(
'Table Headers are Hidden, and should not be Referenced',
Exception::CALCULATION_ENGINE_PUSH_TO_STACK
);
}
$rowsSelected = true;
$startRow = min($startRow, $this->getMinimumRow($rowReference));
$endRow = max($endRow, $this->getMaximumRow($rowReference));
$reference = preg_replace($pattern, '', $reference) ?? '';
}
}
if ($rowsSelected === false) {
// If there isn't any Special Item Identifier specified, then the selection defaults to data rows only.
$startRow = $this->firstDataRow;
$endRow = $this->lastDataRow;
}
return [$startRow, $endRow];
}
private function getColumnsForColumnReference(string $reference, int $startRow, int $endRow): string
{
$columnsSelected = false;
foreach ($this->columns as $columnId => $columnName) {
$columnName = str_replace("\u{a0}", ' ', $columnName ?? ''); //* @phpstan-ignore-line
$cellFrom = "{$columnId}{$startRow}";
$cellTo = "{$columnId}{$endRow}";
$cellReference = ($cellFrom === $cellTo) ? $cellFrom : "{$cellFrom}:{$cellTo}";
$pattern = '/\[' . preg_quote($columnName, '/') . '\]/mui';
if (preg_match($pattern, $reference) === 1) {
$columnsSelected = true;
$reference = preg_replace($pattern, $cellReference, $reference);
}
/** @var string $reference */
}
if ($columnsSelected === false) {
return $this->fullData($startRow, $endRow);
}
return $reference;
}
public function __toString(): string
{
return $this->value;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/BesselI.php
================================================
|float|string Result, or a string containing an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BESSELI(mixed $x, mixed $ord): array|string|float
{
if (is_array($x) || is_array($ord)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $x, $ord);
}
try {
$x = EngineeringValidations::validateFloat($x);
$ord = EngineeringValidations::validateInt($ord);
} catch (Exception $e) {
return $e->getMessage();
}
if ($ord < 0) {
return ExcelError::NAN();
}
$fResult = self::calculate($x, $ord);
return (is_nan($fResult)) ? ExcelError::NAN() : $fResult;
}
private static function calculate(float $x, int $ord): float
{
return match ($ord) {
0 => self::besselI0($x),
1 => self::besselI1($x),
default => self::besselI2($x, $ord),
};
}
private static function besselI0(float $x): float
{
$ax = abs($x);
if ($ax < 3.75) {
$y = $x / 3.75;
$y = $y * $y;
return 1.0 + $y * (3.5156229 + $y * (3.0899424 + $y * (1.2067492
+ $y * (0.2659732 + $y * (0.360768e-1 + $y * 0.45813e-2)))));
}
$y = 3.75 / $ax;
return (exp($ax) / sqrt($ax)) * (0.39894228 + $y * (0.1328592e-1 + $y * (0.225319e-2 + $y * (-0.157565e-2
+ $y * (0.916281e-2 + $y * (-0.2057706e-1 + $y * (0.2635537e-1
+ $y * (-0.1647633e-1 + $y * 0.392377e-2))))))));
}
private static function besselI1(float $x): float
{
$ax = abs($x);
if ($ax < 3.75) {
$y = $x / 3.75;
$y = $y * $y;
$ans = $ax * (0.5 + $y * (0.87890594 + $y * (0.51498869 + $y * (0.15084934 + $y * (0.2658733e-1
+ $y * (0.301532e-2 + $y * 0.32411e-3))))));
return ($x < 0.0) ? -$ans : $ans;
}
$y = 3.75 / $ax;
$ans = 0.2282967e-1 + $y * (-0.2895312e-1 + $y * (0.1787654e-1 - $y * 0.420059e-2));
$ans = 0.39894228 + $y * (-0.3988024e-1 + $y * (-0.362018e-2 + $y * (0.163801e-2
+ $y * (-0.1031555e-1 + $y * $ans))));
$ans *= exp($ax) / sqrt($ax);
return ($x < 0.0) ? -$ans : $ans;
}
private static function besselI2(float $x, int $ord): float
{
if ($x === 0.0) {
return 0.0;
}
$tox = 2.0 / abs($x);
$bip = 0;
$ans = 0.0;
$bi = 1.0;
for ($j = 2 * ($ord + (int) sqrt(40.0 * $ord)); $j > 0; --$j) {
$bim = $bip + $j * $tox * $bi;
$bip = $bi;
$bi = $bim;
if (abs($bi) > 1.0e+12) {
$ans *= 1.0e-12;
$bi *= 1.0e-12;
$bip *= 1.0e-12;
}
if ($j === $ord) {
$ans = $bip;
}
}
$ans *= self::besselI0($x) / $bi;
return ($x < 0.0 && (($ord % 2) === 1)) ? -$ans : $ans;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/BesselJ.php
================================================
8. This code provides a more accurate calculation
*
* @param mixed $x A float value at which to evaluate the function.
* If x is nonnumeric, BESSELJ returns the #VALUE! error value.
* Or can be an array of values
* @param mixed $ord The integer order of the Bessel function.
* If ord is not an integer, it is truncated.
* If $ord is nonnumeric, BESSELJ returns the #VALUE! error value.
* If $ord < 0, BESSELJ returns the #NUM! error value.
* Or can be an array of values
*
* @return array|float|string Result, or a string containing an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BESSELJ(mixed $x, mixed $ord): array|string|float
{
if (is_array($x) || is_array($ord)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $x, $ord);
}
try {
$x = EngineeringValidations::validateFloat($x);
$ord = EngineeringValidations::validateInt($ord);
} catch (Exception $e) {
return $e->getMessage();
}
if ($ord < 0) {
return ExcelError::NAN();
}
$fResult = self::calculate($x, $ord);
return (is_nan($fResult)) ? ExcelError::NAN() : $fResult;
}
private static function calculate(float $x, int $ord): float
{
return match ($ord) {
0 => self::besselJ0($x),
1 => self::besselJ1($x),
default => self::besselJ2($x, $ord),
};
}
private static function besselJ0(float $x): float
{
$ax = abs($x);
if ($ax < 8.0) {
$y = $x * $x;
$ans1 = 57568490574.0 + $y * (-13362590354.0 + $y * (651619640.7 + $y * (-11214424.18 + $y
* (77392.33017 + $y * (-184.9052456)))));
$ans2 = 57568490411.0 + $y * (1029532985.0 + $y * (9494680.718 + $y * (59272.64853 + $y
* (267.8532712 + $y * 1.0))));
return $ans1 / $ans2;
}
$z = 8.0 / $ax;
$y = $z * $z;
$xx = $ax - 0.785398164;
$ans1 = 1.0 + $y * (-0.1098628627e-2 + $y * (0.2734510407e-4 + $y * (-0.2073370639e-5 + $y * 0.2093887211e-6)));
$ans2 = -0.1562499995e-1 + $y * (0.1430488765e-3 + $y * (-0.6911147651e-5 + $y
* (0.7621095161e-6 - $y * 0.934935152e-7)));
return sqrt(0.636619772 / $ax) * (cos($xx) * $ans1 - $z * sin($xx) * $ans2);
}
private static function besselJ1(float $x): float
{
$ax = abs($x);
if ($ax < 8.0) {
$y = $x * $x;
$ans1 = $x * (72362614232.0 + $y * (-7895059235.0 + $y * (242396853.1 + $y
* (-2972611.439 + $y * (15704.48260 + $y * (-30.16036606))))));
$ans2 = 144725228442.0 + $y * (2300535178.0 + $y * (18583304.74 + $y * (99447.43394 + $y
* (376.9991397 + $y * 1.0))));
return $ans1 / $ans2;
}
$z = 8.0 / $ax;
$y = $z * $z;
$xx = $ax - 2.356194491;
$ans1 = 1.0 + $y * (0.183105e-2 + $y * (-0.3516396496e-4 + $y * (0.2457520174e-5 + $y * (-0.240337019e-6))));
$ans2 = 0.04687499995 + $y * (-0.2002690873e-3 + $y * (0.8449199096e-5 + $y
* (-0.88228987e-6 + $y * 0.105787412e-6)));
$ans = sqrt(0.636619772 / $ax) * (cos($xx) * $ans1 - $z * sin($xx) * $ans2);
return ($x < 0.0) ? -$ans : $ans;
}
private static function besselJ2(float $x, int $ord): float
{
$ax = abs($x);
if ($ax === 0.0) {
return 0.0;
}
if ($ax > $ord) {
return self::besselj2a($ax, $ord, $x);
}
return self::besselj2b($ax, $ord, $x);
}
private static function besselj2a(float $ax, int $ord, float $x): float
{
$tox = 2.0 / $ax;
$bjm = self::besselJ0($ax);
$bj = self::besselJ1($ax);
for ($j = 1; $j < $ord; ++$j) {
$bjp = $j * $tox * $bj - $bjm;
$bjm = $bj;
$bj = $bjp;
}
$ans = $bj;
return ($x < 0.0 && ($ord % 2) == 1) ? -$ans : $ans;
}
private static function besselj2b(float $ax, int $ord, float $x): float
{
$tox = 2.0 / $ax;
$jsum = false;
$bjp = $ans = $sum = 0.0;
$bj = 1.0;
for ($j = 2 * ($ord + (int) sqrt(40.0 * $ord)); $j > 0; --$j) {
$bjm = $j * $tox * $bj - $bjp;
$bjp = $bj;
$bj = $bjm;
if (abs($bj) > 1.0e+10) {
$bj *= 1.0e-10;
$bjp *= 1.0e-10;
$ans *= 1.0e-10;
$sum *= 1.0e-10;
}
if ($jsum === true) {
$sum += $bj;
}
$jsum = $jsum === false;
if ($j === $ord) {
$ans = $bjp;
}
}
$sum = 2.0 * $sum - $bj;
$ans /= $sum;
return ($x < 0.0 && ($ord % 2) === 1) ? -$ans : $ans;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/BesselK.php
================================================
|float|string Result, or a string containing an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BESSELK(mixed $x, mixed $ord): array|string|float
{
if (is_array($x) || is_array($ord)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $x, $ord);
}
try {
$x = EngineeringValidations::validateFloat($x);
$ord = EngineeringValidations::validateInt($ord);
} catch (Exception $e) {
return $e->getMessage();
}
if (($ord < 0) || ($x <= 0.0)) {
return ExcelError::NAN();
}
$fBk = self::calculate($x, $ord);
return (is_nan($fBk)) ? ExcelError::NAN() : $fBk;
}
private static function calculate(float $x, int $ord): float
{
return match ($ord) {
0 => self::besselK0($x),
1 => self::besselK1($x),
default => self::besselK2($x, $ord),
};
}
/**
* Mollify Phpstan.
*
* @codeCoverageIgnore
*/
private static function callBesselI(float $x, int $ord): float
{
$rslt = BesselI::BESSELI($x, $ord);
if (!is_float($rslt)) {
throw new Exception('Unexpected array or string');
}
return $rslt;
}
private static function besselK0(float $x): float
{
if ($x <= 2) {
$fNum2 = $x * 0.5;
$y = ($fNum2 * $fNum2);
return -log($fNum2) * self::callBesselI($x, 0)
+ (-0.57721566 + $y * (0.42278420 + $y * (0.23069756 + $y * (0.3488590e-1 + $y * (0.262698e-2 + $y
* (0.10750e-3 + $y * 0.74e-5))))));
}
$y = 2 / $x;
return exp(-$x) / sqrt($x)
* (1.25331414 + $y * (-0.7832358e-1 + $y * (0.2189568e-1 + $y * (-0.1062446e-1 + $y
* (0.587872e-2 + $y * (-0.251540e-2 + $y * 0.53208e-3))))));
}
private static function besselK1(float $x): float
{
if ($x <= 2) {
$fNum2 = $x * 0.5;
$y = ($fNum2 * $fNum2);
return log($fNum2) * self::callBesselI($x, 1)
+ (1 + $y * (0.15443144 + $y * (-0.67278579 + $y * (-0.18156897 + $y * (-0.1919402e-1 + $y
* (-0.110404e-2 + $y * (-0.4686e-4))))))) / $x;
}
$y = 2 / $x;
return exp(-$x) / sqrt($x)
* (1.25331414 + $y * (0.23498619 + $y * (-0.3655620e-1 + $y * (0.1504268e-1 + $y * (-0.780353e-2 + $y
* (0.325614e-2 + $y * (-0.68245e-3)))))));
}
private static function besselK2(float $x, int $ord): float
{
$fTox = 2 / $x;
$fBkm = self::besselK0($x);
$fBk = self::besselK1($x);
for ($n = 1; $n < $ord; ++$n) {
$fBkp = $fBkm + $n * $fTox * $fBk;
$fBkm = $fBk;
$fBk = $fBkp;
}
return $fBk;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/BesselY.php
================================================
|float|string Result, or a string containing an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BESSELY(mixed $x, mixed $ord): array|string|float
{
if (is_array($x) || is_array($ord)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $x, $ord);
}
try {
$x = EngineeringValidations::validateFloat($x);
$ord = EngineeringValidations::validateInt($ord);
} catch (Exception $e) {
return $e->getMessage();
}
if (($ord < 0) || ($x <= 0.0)) {
return ExcelError::NAN();
}
$fBy = self::calculate($x, $ord);
return (is_nan($fBy)) ? ExcelError::NAN() : $fBy;
}
private static function calculate(float $x, int $ord): float
{
return match ($ord) {
0 => self::besselY0($x),
1 => self::besselY1($x),
default => self::besselY2($x, $ord),
};
}
/**
* Mollify Phpstan.
*
* @codeCoverageIgnore
*/
private static function callBesselJ(float $x, int $ord): float
{
$rslt = BesselJ::BESSELJ($x, $ord);
if (!is_float($rslt)) {
throw new Exception('Unexpected array or string');
}
return $rslt;
}
private static function besselY0(float $x): float
{
if ($x < 8.0) {
$y = ($x * $x);
$ans1 = -2957821389.0 + $y * (7062834065.0 + $y * (-512359803.6 + $y * (10879881.29 + $y
* (-86327.92757 + $y * 228.4622733))));
$ans2 = 40076544269.0 + $y * (745249964.8 + $y * (7189466.438 + $y
* (47447.26470 + $y * (226.1030244 + $y))));
return $ans1 / $ans2 + 0.636619772 * self::callBesselJ($x, 0) * log($x);
}
$z = 8.0 / $x;
$y = ($z * $z);
$xx = $x - 0.785398164;
$ans1 = 1 + $y * (-0.1098628627e-2 + $y * (0.2734510407e-4 + $y * (-0.2073370639e-5 + $y * 0.2093887211e-6)));
$ans2 = -0.1562499995e-1 + $y * (0.1430488765e-3 + $y * (-0.6911147651e-5 + $y * (0.7621095161e-6 + $y
* (-0.934945152e-7))));
return sqrt(0.636619772 / $x) * (sin($xx) * $ans1 + $z * cos($xx) * $ans2);
}
private static function besselY1(float $x): float
{
if ($x < 8.0) {
$y = ($x * $x);
$ans1 = $x * (-0.4900604943e13 + $y * (0.1275274390e13 + $y * (-0.5153438139e11 + $y
* (0.7349264551e9 + $y * (-0.4237922726e7 + $y * 0.8511937935e4)))));
$ans2 = 0.2499580570e14 + $y * (0.4244419664e12 + $y * (0.3733650367e10 + $y * (0.2245904002e8 + $y
* (0.1020426050e6 + $y * (0.3549632885e3 + $y)))));
return ($ans1 / $ans2) + 0.636619772 * (self::callBesselJ($x, 1) * log($x) - 1 / $x);
}
$z = 8.0 / $x;
$y = $z * $z;
$xx = $x - 2.356194491;
$ans1 = 1.0 + $y * (0.183105e-2 + $y * (-0.3516396496e-4 + $y * (0.2457520174e-5 + $y * (-0.240337019e-6))));
$ans2 = 0.04687499995 + $y * (-0.2002690873e-3 + $y * (0.8449199096e-5 + $y
* (-0.88228987e-6 + $y * 0.105787412e-6)));
return sqrt(0.636619772 / $x) * (sin($xx) * $ans1 + $z * cos($xx) * $ans2);
}
private static function besselY2(float $x, int $ord): float
{
$fTox = 2.0 / $x;
$fBym = self::besselY0($x);
$fBy = self::besselY1($x);
for ($n = 1; $n < $ord; ++$n) {
$fByp = $n * $fTox * $fBy - $fBym;
$fBym = $fBy;
$fBy = $fByp;
}
return $fBy;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/BitWise.php
================================================
|bool|float|int|string $number1 Or can be an array of values
* @param null|array|bool|float|int|string $number2 Or can be an array of values
*
* @return array|int|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BITAND(null|array|bool|float|int|string $number1, null|array|bool|float|int|string $number2): array|string|int|float
{
if (is_array($number1) || is_array($number2)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $number1, $number2);
}
try {
$number1 = self::validateBitwiseArgument($number1);
$number2 = self::validateBitwiseArgument($number2);
} catch (Exception $e) {
return $e->getMessage();
}
$split1 = self::splitNumber($number1);
$split2 = self::splitNumber($number2);
return self::SPLIT_DIVISOR * ($split1[0] & $split2[0]) + ($split1[1] & $split2[1]);
}
/**
* BITOR.
*
* Returns the bitwise OR of two integer values.
*
* Excel Function:
* BITOR(number1, number2)
*
* @param null|array|bool|float|int|string $number1 Or can be an array of values
* @param null|array|bool|float|int|string $number2 Or can be an array of values
*
* @return array|int|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BITOR(null|array|bool|float|int|string $number1, null|array|bool|float|int|string $number2): array|string|int|float
{
if (is_array($number1) || is_array($number2)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $number1, $number2);
}
try {
$number1 = self::validateBitwiseArgument($number1);
$number2 = self::validateBitwiseArgument($number2);
} catch (Exception $e) {
return $e->getMessage();
}
$split1 = self::splitNumber($number1);
$split2 = self::splitNumber($number2);
return self::SPLIT_DIVISOR * ($split1[0] | $split2[0]) + ($split1[1] | $split2[1]);
}
/**
* BITXOR.
*
* Returns the bitwise XOR of two integer values.
*
* Excel Function:
* BITXOR(number1, number2)
*
* @param null|array|bool|float|int|string $number1 Or can be an array of values
* @param null|array|bool|float|int|string $number2 Or can be an array of values
*
* @return array|int|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BITXOR(null|array|bool|float|int|string $number1, null|array|bool|float|int|string $number2): array|string|int|float
{
if (is_array($number1) || is_array($number2)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $number1, $number2);
}
try {
$number1 = self::validateBitwiseArgument($number1);
$number2 = self::validateBitwiseArgument($number2);
} catch (Exception $e) {
return $e->getMessage();
}
$split1 = self::splitNumber($number1);
$split2 = self::splitNumber($number2);
return self::SPLIT_DIVISOR * ($split1[0] ^ $split2[0]) + ($split1[1] ^ $split2[1]);
}
/**
* BITLSHIFT.
*
* Returns the number value shifted left by shift_amount bits.
*
* Excel Function:
* BITLSHIFT(number, shift_amount)
*
* @param null|array|bool|float|int|string $number Or can be an array of values
* @param null|array|bool|float|int|string $shiftAmount Or can be an array of values
*
* @return array|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BITLSHIFT(null|array|bool|float|int|string $number, null|array|bool|float|int|string $shiftAmount): array|string|float
{
if (is_array($number) || is_array($shiftAmount)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $shiftAmount);
}
try {
$number = self::validateBitwiseArgument($number);
$shiftAmount = self::validateShiftAmount($shiftAmount);
} catch (Exception $e) {
return $e->getMessage();
}
$result = floor($number * (2 ** $shiftAmount));
if ($result > 2 ** 48 - 1) {
return ExcelError::NAN();
}
return $result;
}
/**
* BITRSHIFT.
*
* Returns the number value shifted right by shift_amount bits.
*
* Excel Function:
* BITRSHIFT(number, shift_amount)
*
* @param null|array|bool|float|int|string $number Or can be an array of values
* @param null|array|bool|float|int|string $shiftAmount Or can be an array of values
*
* @return array|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function BITRSHIFT(null|array|bool|float|int|string $number, null|array|bool|float|int|string $shiftAmount): array|string|float
{
if (is_array($number) || is_array($shiftAmount)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $shiftAmount);
}
try {
$number = self::validateBitwiseArgument($number);
$shiftAmount = self::validateShiftAmount($shiftAmount);
} catch (Exception $e) {
return $e->getMessage();
}
$result = floor($number / (2 ** $shiftAmount));
if ($result > 2 ** 48 - 1) { // possible because shiftAmount can be negative
return ExcelError::NAN();
}
return $result;
}
/**
* Validate arguments passed to the bitwise functions.
*/
private static function validateBitwiseArgument(mixed $value): float
{
$value = self::nullFalseTrueToNumber($value);
if (is_numeric($value)) {
$value = (float) $value;
if ($value == floor($value)) {
if (($value > 2 ** 48 - 1) || ($value < 0)) {
throw new Exception(ExcelError::NAN());
}
return floor($value);
}
throw new Exception(ExcelError::NAN());
}
throw new Exception(ExcelError::VALUE());
}
/**
* Validate arguments passed to the bitwise functions.
*/
private static function validateShiftAmount(mixed $value): int
{
$value = self::nullFalseTrueToNumber($value);
if (is_numeric($value)) {
if (abs($value + 0) > 53) {
throw new Exception(ExcelError::NAN());
}
return (int) $value;
}
throw new Exception(ExcelError::VALUE());
}
/**
* Many functions accept null/false/true argument treated as 0/0/1.
*/
private static function nullFalseTrueToNumber(mixed &$number): mixed
{
if ($number === null) {
$number = 0;
} elseif (is_bool($number)) {
$number = (int) $number;
}
return $number;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/Compare.php
================================================
|bool|float|int|string $a the first number
* Or can be an array of values
* @param array|bool|float|int|string $b The second number. If omitted, b is assumed to be zero.
* Or can be an array of values
*
* @return array|int|string (string in the event of an error)
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function DELTA(array|float|bool|string|int $a, array|float|bool|string|int $b = 0.0): array|string|int
{
if (is_array($a) || is_array($b)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $a, $b);
}
try {
$a = EngineeringValidations::validateFloat($a);
$b = EngineeringValidations::validateFloat($b);
} catch (Exception $e) {
return $e->getMessage();
}
return (int) (abs($a - $b) < 1.0e-15);
}
/**
* GESTEP.
*
* Excel Function:
* GESTEP(number[,step])
*
* Returns 1 if number >= step; returns 0 (zero) otherwise
* Use this function to filter a set of values. For example, by summing several GESTEP
* functions you calculate the count of values that exceed a threshold.
*
* @param array|bool|float|int|string $number the value to test against step
* Or can be an array of values
* @param null|array|bool|float|int|string $step The threshold value. If you omit a value for step, GESTEP uses zero.
* Or can be an array of values
*
* @return array|int|string (string in the event of an error)
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function GESTEP(array|float|bool|string|int $number, $step = 0.0): array|string|int
{
if (is_array($number) || is_array($step)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $step);
}
try {
$number = EngineeringValidations::validateFloat($number);
$step = EngineeringValidations::validateFloat($step ?? 0.0);
} catch (Exception $e) {
return $e->getMessage();
}
return (int) ($number >= $step);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/Complex.php
================================================
|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function COMPLEX(mixed $realNumber = 0.0, mixed $imaginary = 0.0, mixed $suffix = 'i'): array|string
{
if (is_array($realNumber) || is_array($imaginary) || is_array($suffix)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $realNumber, $imaginary, $suffix);
}
$realNumber = $realNumber ?? 0.0;
$imaginary = $imaginary ?? 0.0;
$suffix = $suffix ?? 'i';
try {
$realNumber = EngineeringValidations::validateFloat($realNumber);
$imaginary = EngineeringValidations::validateFloat($imaginary);
} catch (Exception $e) {
return $e->getMessage();
}
if (($suffix === 'i') || ($suffix === 'j') || ($suffix === '')) {
$complex = new ComplexObject($realNumber, $imaginary, $suffix);
return (string) $complex;
}
return ExcelError::VALUE();
}
/**
* IMAGINARY.
*
* Returns the imaginary coefficient of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMAGINARY(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the imaginary
* coefficient
* Or can be an array of values
*
* @return array|float|string (string if an error)
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMAGINARY($complexNumber): array|string|float
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return $complex->getImaginary();
}
/**
* IMREAL.
*
* Returns the real coefficient of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMREAL(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the real coefficient
* Or can be an array of values
*
* @return array|float|string (string if an error)
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMREAL($complexNumber): array|string|float
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return $complex->getReal();
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ComplexFunctions.php
================================================
|string $complexNumber the complex number for which you want the absolute value
* Or can be an array of values
*
* @return array|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMABS(array|string $complexNumber): array|float|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return $complex->abs();
}
/**
* IMARGUMENT.
*
* Returns the argument theta of a complex number, i.e. the angle in radians from the real
* axis to the representation of the number in polar coordinates.
*
* Excel Function:
* IMARGUMENT(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the argument theta
* Or can be an array of values
*
* @return array|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMARGUMENT(array|string $complexNumber): array|float|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
return ExcelError::DIV0();
}
return $complex->argument();
}
/**
* IMCONJUGATE.
*
* Returns the complex conjugate of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMCONJUGATE(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the conjugate
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMCONJUGATE(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->conjugate();
}
/**
* IMCOS.
*
* Returns the cosine of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMCOS(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the cosine
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMCOS(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->cos();
}
/**
* IMCOSH.
*
* Returns the hyperbolic cosine of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMCOSH(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the hyperbolic cosine
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMCOSH(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->cosh();
}
/**
* IMCOT.
*
* Returns the cotangent of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMCOT(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the cotangent
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMCOT(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->cot();
}
/**
* IMCSC.
*
* Returns the cosecant of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMCSC(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the cosecant
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMCSC(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->csc();
}
/**
* IMCSCH.
*
* Returns the hyperbolic cosecant of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMCSCH(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the hyperbolic cosecant
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMCSCH(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->csch();
}
/**
* IMSIN.
*
* Returns the sine of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMSIN(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the sine
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMSIN(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->sin();
}
/**
* IMSINH.
*
* Returns the hyperbolic sine of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMSINH(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the hyperbolic sine
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMSINH(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->sinh();
}
/**
* IMSEC.
*
* Returns the secant of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMSEC(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the secant
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMSEC(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->sec();
}
/**
* IMSECH.
*
* Returns the hyperbolic secant of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMSECH(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the hyperbolic secant
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMSECH(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->sech();
}
/**
* IMTAN.
*
* Returns the tangent of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMTAN(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the tangent
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMTAN(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->tan();
}
/**
* IMSQRT.
*
* Returns the square root of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMSQRT(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the square root
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMSQRT(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
$theta = self::IMARGUMENT($complexNumber);
if ($theta === ExcelError::DIV0()) {
return '0';
}
return (string) $complex->sqrt();
}
/**
* IMLN.
*
* Returns the natural logarithm of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMLN(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the natural logarithm
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMLN(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
return ExcelError::NAN();
}
return (string) $complex->ln();
}
/**
* IMLOG10.
*
* Returns the common logarithm (base 10) of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMLOG10(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the common logarithm
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMLOG10(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
return ExcelError::NAN();
}
return (string) $complex->log10();
}
/**
* IMLOG2.
*
* Returns the base-2 logarithm of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMLOG2(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the base-2 logarithm
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMLOG2(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
if ($complex->getReal() == 0.0 && $complex->getImaginary() == 0.0) {
return ExcelError::NAN();
}
return (string) $complex->log2();
}
/**
* IMEXP.
*
* Returns the exponential of a complex number in x + yi or x + yj text format.
*
* Excel Function:
* IMEXP(complexNumber)
*
* @param array|string $complexNumber the complex number for which you want the exponential
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMEXP(array|string $complexNumber): array|string
{
if (is_array($complexNumber)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $complexNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $complex->exp();
}
/**
* IMPOWER.
*
* Returns a complex number in x + yi or x + yj text format raised to a power.
*
* Excel Function:
* IMPOWER(complexNumber,realNumber)
*
* @param array|string $complexNumber the complex number you want to raise to a power
* Or can be an array of values
* @param array|float|int|string $realNumber the power to which you want to raise the complex number
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMPOWER(array|string $complexNumber, array|float|int|string $realNumber): array|string
{
if (is_array($complexNumber) || is_array($realNumber)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $complexNumber, $realNumber);
}
try {
$complex = new ComplexObject($complexNumber);
} catch (ComplexException) {
return ExcelError::NAN();
}
if (!is_numeric($realNumber)) {
return ExcelError::VALUE();
}
return (string) $complex->pow((float) $realNumber);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ComplexOperations.php
================================================
|string $complexDividend the complex numerator or dividend
* Or can be an array of values
* @param array|string $complexDivisor the complex denominator or divisor
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMDIV(array|string $complexDividend, array|string $complexDivisor): array|string
{
if (is_array($complexDividend) || is_array($complexDivisor)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $complexDividend, $complexDivisor);
}
try {
return (string) (new ComplexObject($complexDividend))->divideby(new ComplexObject($complexDivisor));
} catch (ComplexException) {
return ExcelError::NAN();
}
}
/**
* IMSUB.
*
* Returns the difference of two complex numbers in x + yi or x + yj text format.
*
* Excel Function:
* IMSUB(complexNumber1,complexNumber2)
*
* @param array|string $complexNumber1 the complex number from which to subtract complexNumber2
* Or can be an array of values
* @param array|string $complexNumber2 the complex number to subtract from complexNumber1
* Or can be an array of values
*
* @return array|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function IMSUB(array|string $complexNumber1, array|string $complexNumber2): array|string
{
if (is_array($complexNumber1) || is_array($complexNumber2)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $complexNumber1, $complexNumber2);
}
try {
return (string) (new ComplexObject($complexNumber1))->subtract(new ComplexObject($complexNumber2));
} catch (ComplexException) {
return ExcelError::NAN();
}
}
/**
* IMSUM.
*
* Returns the sum of two or more complex numbers in x + yi or x + yj text format.
*
* Excel Function:
* IMSUM(complexNumber[,complexNumber[,...]])
*
* @param string ...$complexNumbers Series of complex numbers to add
*/
public static function IMSUM(...$complexNumbers): string
{
// Return value
$returnValue = new ComplexObject(0.0);
$aArgs = Functions::flattenArray($complexNumbers);
try {
// Loop through the arguments
foreach ($aArgs as $complex) {
$returnValue = $returnValue->add(new ComplexObject($complex));
}
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $returnValue;
}
/**
* IMPRODUCT.
*
* Returns the product of two or more complex numbers in x + yi or x + yj text format.
*
* Excel Function:
* IMPRODUCT(complexNumber[,complexNumber[,...]])
*
* @param string ...$complexNumbers Series of complex numbers to multiply
*/
public static function IMPRODUCT(...$complexNumbers): string
{
// Return value
$returnValue = new ComplexObject(1.0);
$aArgs = Functions::flattenArray($complexNumbers);
try {
// Loop through the arguments
foreach ($aArgs as $complex) {
$returnValue = $returnValue->multiply(new ComplexObject($complex));
}
} catch (ComplexException) {
return ExcelError::NAN();
}
return (string) $returnValue;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/Constants.php
================================================
10) {
throw new Exception(ExcelError::NAN());
}
return (int) $places;
}
throw new Exception(ExcelError::VALUE());
}
/**
* Formats a number base string value with leading zeroes.
*
* @param string $value The "number" to pad
* @param ?int $places The length that we want to pad this value
*
* @return string The padded "number"
*/
protected static function nbrConversionFormat(string $value, ?int $places): string
{
if ($places !== null) {
if (strlen($value) <= $places) {
return substr(str_pad($value, $places, '0', STR_PAD_LEFT), -10);
}
return ExcelError::NAN();
}
return substr($value, -10);
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ConvertBinary.php
================================================
|bool|float|int|string $value The binary number (as a string) that you want to convert. The number
* cannot contain more than 10 characters (10 bits). The most significant
* bit of number is the sign bit. The remaining 9 bits are magnitude bits.
* Negative numbers are represented using two's-complement notation.
* If number is not a valid binary number, or if number contains more than
* 10 characters (10 bits), BIN2DEC returns the #NUM! error value.
* Or can be an array of values
*
* @return array|float|int|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toDecimal($value)
{
if (is_array($value)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $value);
}
try {
$value = self::validateValue($value);
$value = self::validateBinary($value);
} catch (Exception $e) {
return $e->getMessage();
}
if (strlen($value) == 10 && $value[0] === '1') {
// Two's Complement
$value = substr($value, -9);
return -(512 - bindec($value));
}
return bindec($value);
}
/**
* toHex.
*
* Return a binary value as hex.
*
* Excel Function:
* BIN2HEX(x[,places])
*
* @param array|bool|float|int|string $value The binary number (as a string) that you want to convert. The number
* cannot contain more than 10 characters (10 bits). The most significant
* bit of number is the sign bit. The remaining 9 bits are magnitude bits.
* Negative numbers are represented using two's-complement notation.
* If number is not a valid binary number, or if number contains more than
* 10 characters (10 bits), BIN2HEX returns the #NUM! error value.
* Or can be an array of values
* @param null|array|float|int|string $places The number of characters to use. If places is omitted, BIN2HEX uses the
* minimum number of characters necessary. Places is useful for padding the
* return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, BIN2HEX returns the #VALUE! error value.
* If places is negative, BIN2HEX returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toHex($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateBinary($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
if (strlen($value) == 10 && $value[0] === '1') {
$high2 = substr($value, 0, 2);
$low8 = substr($value, 2);
$xarr = ['00' => '00000000', '01' => '00000001', '10' => 'FFFFFFFE', '11' => 'FFFFFFFF'];
return $xarr[$high2] . strtoupper(substr('0' . dechex((int) bindec($low8)), -2));
}
$hexVal = (string) strtoupper(dechex((int) bindec($value)));
return self::nbrConversionFormat($hexVal, $places);
}
/**
* toOctal.
*
* Return a binary value as octal.
*
* Excel Function:
* BIN2OCT(x[,places])
*
* @param array|bool|float|int|string $value The binary number (as a string) that you want to convert. The number
* cannot contain more than 10 characters (10 bits). The most significant
* bit of number is the sign bit. The remaining 9 bits are magnitude bits.
* Negative numbers are represented using two's-complement notation.
* If number is not a valid binary number, or if number contains more than
* 10 characters (10 bits), BIN2OCT returns the #NUM! error value.
* Or can be an array of values
* @param null|array|float|int|string $places The number of characters to use. If places is omitted, BIN2OCT uses the
* minimum number of characters necessary. Places is useful for padding the
* return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, BIN2OCT returns the #VALUE! error value.
* If places is negative, BIN2OCT returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toOctal($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateBinary($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
if (strlen($value) == 10 && $value[0] === '1') { // Two's Complement
return str_repeat('7', 6) . strtoupper(decoct((int) bindec("11$value")));
}
$octVal = (string) decoct((int) bindec($value));
return self::nbrConversionFormat($octVal, $places);
}
protected static function validateBinary(string $value): string
{
if ((strlen($value) > preg_match_all('/[01]/', $value)) || (strlen($value) > 10)) {
throw new Exception(ExcelError::NAN());
}
return $value;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ConvertDecimal.php
================================================
|bool|float|int|string $value The decimal integer you want to convert. If number is negative,
* valid place values are ignored and DEC2BIN returns a 10-character
* (10-bit) binary number in which the most significant bit is the sign
* bit. The remaining 9 bits are magnitude bits. Negative numbers are
* represented using two's-complement notation.
* If number < -512 or if number > 511, DEC2BIN returns the #NUM! error
* value.
* If number is nonnumeric, DEC2BIN returns the #VALUE! error value.
* If DEC2BIN requires more than places characters, it returns the #NUM!
* error value.
* Or can be an array of values
* @param null|array|float|int|string $places The number of characters to use. If places is omitted, DEC2BIN uses
* the minimum number of characters necessary. Places is useful for
* padding the return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, DEC2BIN returns the #VALUE! error value.
* If places is zero or negative, DEC2BIN returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toBinary($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateDecimal($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
$value = (int) floor((float) $value);
if ($value > self::LARGEST_BINARY_IN_DECIMAL || $value < self::SMALLEST_BINARY_IN_DECIMAL) {
return ExcelError::NAN();
}
$r = decbin($value);
// Two's Complement
$r = substr($r, -10);
return self::nbrConversionFormat($r, $places);
}
/**
* toHex.
*
* Return a decimal value as hex.
*
* Excel Function:
* DEC2HEX(x[,places])
*
* @param array|bool|float|int|string $value The decimal integer you want to convert. If number is negative,
* places is ignored and DEC2HEX returns a 10-character (40-bit)
* hexadecimal number in which the most significant bit is the sign
* bit. The remaining 39 bits are magnitude bits. Negative numbers
* are represented using two's-complement notation.
* If number < -549,755,813,888 or if number > 549,755,813,887,
* DEC2HEX returns the #NUM! error value.
* If number is nonnumeric, DEC2HEX returns the #VALUE! error value.
* If DEC2HEX requires more than places characters, it returns the
* #NUM! error value.
* Or can be an array of values
* @param null|array|float|int|string $places The number of characters to use. If places is omitted, DEC2HEX uses
* the minimum number of characters necessary. Places is useful for
* padding the return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, DEC2HEX returns the #VALUE! error value.
* If places is zero or negative, DEC2HEX returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toHex($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateDecimal($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
$value = floor((float) $value);
if ($value > self::LARGEST_HEX_IN_DECIMAL || $value < self::SMALLEST_HEX_IN_DECIMAL) {
return ExcelError::NAN();
}
$r = strtoupper(dechex((int) $value));
$r = self::hex32bit($value, $r);
return self::nbrConversionFormat($r, $places);
}
public static function hex32bit(float $value, string $hexstr, bool $force = false): string
{
if (PHP_INT_SIZE === 4 || $force) {
if ($value >= 2 ** 32) {
$quotient = (int) ($value / (2 ** 32));
return strtoupper(substr('0' . dechex($quotient), -2) . $hexstr);
}
if ($value < -(2 ** 32)) {
$quotient = 256 - (int) ceil((-$value) / (2 ** 32));
return strtoupper(substr('0' . dechex($quotient), -2) . substr("00000000$hexstr", -8));
}
if ($value < 0) {
return "FF$hexstr";
}
}
return $hexstr;
}
/**
* toOctal.
*
* Return a decimal value as octal.
*
* Excel Function:
* DEC2OCT(x[,places])
*
* @param array|bool|float|int|string $value The decimal integer you want to convert. If number is negative,
* places is ignored and DEC2OCT returns a 10-character (30-bit)
* octal number in which the most significant bit is the sign bit.
* The remaining 29 bits are magnitude bits. Negative numbers are
* represented using two's-complement notation.
* If number < -536,870,912 or if number > 536,870,911, DEC2OCT
* returns the #NUM! error value.
* If number is nonnumeric, DEC2OCT returns the #VALUE! error value.
* If DEC2OCT requires more than places characters, it returns the
* #NUM! error value.
* Or can be an array of values
* @param array|int $places The number of characters to use. If places is omitted, DEC2OCT uses
* the minimum number of characters necessary. Places is useful for
* padding the return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, DEC2OCT returns the #VALUE! error value.
* If places is zero or negative, DEC2OCT returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toOctal($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateDecimal($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
$value = (int) floor((float) $value);
if ($value > self::LARGEST_OCTAL_IN_DECIMAL || $value < self::SMALLEST_OCTAL_IN_DECIMAL) {
return ExcelError::NAN();
}
$r = decoct($value);
$r = substr($r, -10);
return self::nbrConversionFormat($r, $places);
}
protected static function validateDecimal(string $value): string
{
if (strlen($value) > preg_match_all('/[-0123456789.]/', $value)) {
throw new Exception(ExcelError::VALUE());
}
return $value;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ConvertHex.php
================================================
|bool|float|string $value The hexadecimal number you want to convert.
* Number cannot contain more than 10 characters.
* The most significant bit of number is the sign bit (40th bit from the right).
* The remaining 9 bits are magnitude bits.
* Negative numbers are represented using two's-complement notation.
* If number is negative, HEX2BIN ignores places and returns a 10-character binary number.
* If number is negative, it cannot be less than FFFFFFFE00,
* and if number is positive, it cannot be greater than 1FF.
* If number is not a valid hexadecimal number, HEX2BIN returns the #NUM! error value.
* If HEX2BIN requires more than places characters, it returns the #NUM! error value.
* Or can be an array of values
* @param array|int $places The number of characters to use. If places is omitted,
* HEX2BIN uses the minimum number of characters necessary. Places
* is useful for padding the return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, HEX2BIN returns the #VALUE! error value.
* If places is negative, HEX2BIN returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toBinary($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateHex($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
$dec = self::toDecimal($value);
return ConvertDecimal::toBinary($dec, $places);
}
/**
* toDecimal.
*
* Return a hex value as decimal.
*
* Excel Function:
* HEX2DEC(x)
*
* @param array|bool|float|int|string $value The hexadecimal number you want to convert. This number cannot
* contain more than 10 characters (40 bits). The most significant
* bit of number is the sign bit. The remaining 39 bits are magnitude
* bits. Negative numbers are represented using two's-complement
* notation.
* If number is not a valid hexadecimal number, HEX2DEC returns the
* #NUM! error value.
* Or can be an array of values
*
* @return array|float|int|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toDecimal($value)
{
if (is_array($value)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $value);
}
try {
$value = self::validateValue($value);
$value = self::validateHex($value);
} catch (Exception $e) {
return $e->getMessage();
}
if (strlen($value) > 10) {
return ExcelError::NAN();
}
$binX = '';
foreach (mb_str_split($value, 1, 'UTF-8') as $char) {
$binX .= str_pad(base_convert($char, 16, 2), 4, '0', STR_PAD_LEFT);
}
if (strlen($binX) == 40 && $binX[0] == '1') {
for ($i = 0; $i < 40; ++$i) {
$binX[$i] = ($binX[$i] == '1' ? '0' : '1');
}
return (bindec($binX) + 1) * -1;
}
return bindec($binX);
}
/**
* toOctal.
*
* Return a hex value as octal.
*
* Excel Function:
* HEX2OCT(x[,places])
*
* @param array|bool|float|int|string $value The hexadecimal number you want to convert. Number cannot
* contain more than 10 characters. The most significant bit of
* number is the sign bit. The remaining 39 bits are magnitude
* bits. Negative numbers are represented using two's-complement
* notation.
* If number is negative, HEX2OCT ignores places and returns a
* 10-character octal number.
* If number is negative, it cannot be less than FFE0000000, and
* if number is positive, it cannot be greater than 1FFFFFFF.
* If number is not a valid hexadecimal number, HEX2OCT returns
* the #NUM! error value.
* If HEX2OCT requires more than places characters, it returns
* the #NUM! error value.
* Or can be an array of values
* @param array|int $places The number of characters to use. If places is omitted, HEX2OCT
* uses the minimum number of characters necessary. Places is
* useful for padding the return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, HEX2OCT returns the #VALUE! error
* value.
* If places is negative, HEX2OCT returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toOctal($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateHex($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
$decimal = self::toDecimal($value);
return ConvertDecimal::toOctal($decimal, $places);
}
protected static function validateHex(string $value): string
{
if (strlen($value) > preg_match_all('/[0123456789ABCDEF]/', $value)) {
throw new Exception(ExcelError::NAN());
}
return $value;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ConvertOctal.php
================================================
|bool|float|int|string $value The octal number you want to convert. Number may not
* contain more than 10 characters. The most significant
* bit of number is the sign bit. The remaining 29 bits
* are magnitude bits. Negative numbers are represented
* using two's-complement notation.
* If number is negative, OCT2BIN ignores places and returns
* a 10-character binary number.
* If number is negative, it cannot be less than 7777777000,
* and if number is positive, it cannot be greater than 777.
* If number is not a valid octal number, OCT2BIN returns
* the #NUM! error value.
* If OCT2BIN requires more than places characters, it
* returns the #NUM! error value.
* Or can be an array of values
* @param array|int $places The number of characters to use. If places is omitted,
* OCT2BIN uses the minimum number of characters necessary.
* Places is useful for padding the return value with
* leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, OCT2BIN returns the #VALUE!
* error value.
* If places is negative, OCT2BIN returns the #NUM! error
* value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toBinary($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateOctal($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
return ConvertDecimal::toBinary(self::toDecimal($value), $places);
}
/**
* toDecimal.
*
* Return an octal value as decimal.
*
* Excel Function:
* OCT2DEC(x)
*
* @param array|bool|float|int|string $value The octal number you want to convert. Number may not contain
* more than 10 octal characters (30 bits). The most significant
* bit of number is the sign bit. The remaining 29 bits are
* magnitude bits. Negative numbers are represented using
* two's-complement notation.
* If number is not a valid octal number, OCT2DEC returns the
* #NUM! error value.
* Or can be an array of values
*
* @return array|float|int|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toDecimal($value)
{
if (is_array($value)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $value);
}
try {
$value = self::validateValue($value);
$value = self::validateOctal($value);
} catch (Exception $e) {
return $e->getMessage();
}
$binX = '';
foreach (mb_str_split($value, 1, 'UTF-8') as $char) {
$binX .= str_pad(decbin((int) $char), 3, '0', STR_PAD_LEFT);
}
if (strlen($binX) == 30 && $binX[0] == '1') {
for ($i = 0; $i < 30; ++$i) {
$binX[$i] = ($binX[$i] == '1' ? '0' : '1');
}
return (bindec($binX) + 1) * -1;
}
return bindec($binX);
}
/**
* toHex.
*
* Return an octal value as hex.
*
* Excel Function:
* OCT2HEX(x[,places])
*
* @param array|bool|float|int|string $value The octal number you want to convert. Number may not contain
* more than 10 octal characters (30 bits). The most significant
* bit of number is the sign bit. The remaining 29 bits are
* magnitude bits. Negative numbers are represented using
* two's-complement notation.
* If number is negative, OCT2HEX ignores places and returns a
* 10-character hexadecimal number.
* If number is not a valid octal number, OCT2HEX returns the
* #NUM! error value.
* If OCT2HEX requires more than places characters, it returns
* the #NUM! error value.
* Or can be an array of values
* @param array|int $places The number of characters to use. If places is omitted, OCT2HEX
* uses the minimum number of characters necessary. Places is useful
* for padding the return value with leading 0s (zeros).
* If places is not an integer, it is truncated.
* If places is nonnumeric, OCT2HEX returns the #VALUE! error value.
* If places is negative, OCT2HEX returns the #NUM! error value.
* Or can be an array of values
*
* @return array|string Result, or an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function toHex($value, $places = null): array|string
{
if (is_array($value) || is_array($places)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $places);
}
try {
$value = self::validateValue($value);
$value = self::validateOctal($value);
$places = self::validatePlaces($places);
} catch (Exception $e) {
return $e->getMessage();
}
$hexVal = strtoupper(dechex((int) self::toDecimal($value)));
$hexVal = (PHP_INT_SIZE === 4 && strlen($value) === 10 && $value[0] >= '4') ? "FF{$hexVal}" : $hexVal;
return self::nbrConversionFormat($hexVal, $places);
}
protected static function validateOctal(string $value): string
{
$numDigits = (int) preg_match_all('/[01234567]/', $value);
if (strlen($value) > $numDigits || $numDigits > 10) {
throw new Exception(ExcelError::NAN());
}
return $value;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ConvertUOM.php
================================================
*/
private static array $conversionUnits = [
// Weight and Mass
'g' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Gram', 'AllowPrefix' => true],
'sg' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Slug', 'AllowPrefix' => false],
'lbm' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Pound mass (avoirdupois)', 'AllowPrefix' => false],
'u' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'U (atomic mass unit)', 'AllowPrefix' => true],
'ozm' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Ounce mass (avoirdupois)', 'AllowPrefix' => false],
'grain' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Grain', 'AllowPrefix' => false],
'cwt' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'U.S. (short) hundredweight', 'AllowPrefix' => false],
'shweight' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'U.S. (short) hundredweight', 'AllowPrefix' => false],
'uk_cwt' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Imperial hundredweight', 'AllowPrefix' => false],
'lcwt' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Imperial hundredweight', 'AllowPrefix' => false],
'hweight' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Imperial hundredweight', 'AllowPrefix' => false],
'stone' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Stone', 'AllowPrefix' => false],
'ton' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Ton', 'AllowPrefix' => false],
'uk_ton' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Imperial ton', 'AllowPrefix' => false],
'LTON' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Imperial ton', 'AllowPrefix' => false],
'brton' => ['Group' => self::CATEGORY_WEIGHT_AND_MASS, 'UnitName' => 'Imperial ton', 'AllowPrefix' => false],
// Distance
'm' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Meter', 'AllowPrefix' => true],
'mi' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Statute mile', 'AllowPrefix' => false],
'Nmi' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Nautical mile', 'AllowPrefix' => false],
'in' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Inch', 'AllowPrefix' => false],
'ft' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Foot', 'AllowPrefix' => false],
'yd' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Yard', 'AllowPrefix' => false],
'ang' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Angstrom', 'AllowPrefix' => true],
'ell' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Ell', 'AllowPrefix' => false],
'ly' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Light Year', 'AllowPrefix' => false],
'parsec' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Parsec', 'AllowPrefix' => false],
'pc' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Parsec', 'AllowPrefix' => false],
'Pica' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Pica (1/72 in)', 'AllowPrefix' => false],
'Picapt' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Pica (1/72 in)', 'AllowPrefix' => false],
'pica' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'Pica (1/6 in)', 'AllowPrefix' => false],
'survey_mi' => ['Group' => self::CATEGORY_DISTANCE, 'UnitName' => 'U.S survey mile (statute mile)', 'AllowPrefix' => false],
// Time
'yr' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Year', 'AllowPrefix' => false],
'day' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Day', 'AllowPrefix' => false],
'd' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Day', 'AllowPrefix' => false],
'hr' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Hour', 'AllowPrefix' => false],
'mn' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Minute', 'AllowPrefix' => false],
'min' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Minute', 'AllowPrefix' => false],
'sec' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Second', 'AllowPrefix' => true],
's' => ['Group' => self::CATEGORY_TIME, 'UnitName' => 'Second', 'AllowPrefix' => true],
// Pressure
'Pa' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'Pascal', 'AllowPrefix' => true],
'p' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'Pascal', 'AllowPrefix' => true],
'atm' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'Atmosphere', 'AllowPrefix' => true],
'at' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'Atmosphere', 'AllowPrefix' => true],
'mmHg' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'mm of Mercury', 'AllowPrefix' => true],
'psi' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'PSI', 'AllowPrefix' => true],
'Torr' => ['Group' => self::CATEGORY_PRESSURE, 'UnitName' => 'Torr', 'AllowPrefix' => true],
// Force
'N' => ['Group' => self::CATEGORY_FORCE, 'UnitName' => 'Newton', 'AllowPrefix' => true],
'dyn' => ['Group' => self::CATEGORY_FORCE, 'UnitName' => 'Dyne', 'AllowPrefix' => true],
'dy' => ['Group' => self::CATEGORY_FORCE, 'UnitName' => 'Dyne', 'AllowPrefix' => true],
'lbf' => ['Group' => self::CATEGORY_FORCE, 'UnitName' => 'Pound force', 'AllowPrefix' => false],
'pond' => ['Group' => self::CATEGORY_FORCE, 'UnitName' => 'Pond', 'AllowPrefix' => true],
// Energy
'J' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Joule', 'AllowPrefix' => true],
'e' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Erg', 'AllowPrefix' => true],
'c' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Thermodynamic calorie', 'AllowPrefix' => true],
'cal' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'IT calorie', 'AllowPrefix' => true],
'eV' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Electron volt', 'AllowPrefix' => true],
'ev' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Electron volt', 'AllowPrefix' => true],
'HPh' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Horsepower-hour', 'AllowPrefix' => false],
'hh' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Horsepower-hour', 'AllowPrefix' => false],
'Wh' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Watt-hour', 'AllowPrefix' => true],
'wh' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Watt-hour', 'AllowPrefix' => true],
'flb' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'Foot-pound', 'AllowPrefix' => false],
'BTU' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'BTU', 'AllowPrefix' => false],
'btu' => ['Group' => self::CATEGORY_ENERGY, 'UnitName' => 'BTU', 'AllowPrefix' => false],
// Power
'HP' => ['Group' => self::CATEGORY_POWER, 'UnitName' => 'Horsepower', 'AllowPrefix' => false],
'h' => ['Group' => self::CATEGORY_POWER, 'UnitName' => 'Horsepower', 'AllowPrefix' => false],
'W' => ['Group' => self::CATEGORY_POWER, 'UnitName' => 'Watt', 'AllowPrefix' => true],
'w' => ['Group' => self::CATEGORY_POWER, 'UnitName' => 'Watt', 'AllowPrefix' => true],
'PS' => ['Group' => self::CATEGORY_POWER, 'UnitName' => 'Pferdestärke', 'AllowPrefix' => false],
// Magnetism
'T' => ['Group' => self::CATEGORY_MAGNETISM, 'UnitName' => 'Tesla', 'AllowPrefix' => true],
'ga' => ['Group' => self::CATEGORY_MAGNETISM, 'UnitName' => 'Gauss', 'AllowPrefix' => true],
// Temperature
'C' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Degrees Celsius', 'AllowPrefix' => false],
'cel' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Degrees Celsius', 'AllowPrefix' => false],
'F' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Degrees Fahrenheit', 'AllowPrefix' => false],
'fah' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Degrees Fahrenheit', 'AllowPrefix' => false],
'K' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Kelvin', 'AllowPrefix' => false],
'kel' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Kelvin', 'AllowPrefix' => false],
'Rank' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Degrees Rankine', 'AllowPrefix' => false],
'Reau' => ['Group' => self::CATEGORY_TEMPERATURE, 'UnitName' => 'Degrees Réaumur', 'AllowPrefix' => false],
// Volume
'l' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Litre', 'AllowPrefix' => true],
'L' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Litre', 'AllowPrefix' => true],
'lt' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Litre', 'AllowPrefix' => true],
'tsp' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Teaspoon', 'AllowPrefix' => false],
'tspm' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Modern Teaspoon', 'AllowPrefix' => false],
'tbs' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Tablespoon', 'AllowPrefix' => false],
'oz' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Fluid Ounce', 'AllowPrefix' => false],
'cup' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cup', 'AllowPrefix' => false],
'pt' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'U.S. Pint', 'AllowPrefix' => false],
'us_pt' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'U.S. Pint', 'AllowPrefix' => false],
'uk_pt' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'U.K. Pint', 'AllowPrefix' => false],
'qt' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Quart', 'AllowPrefix' => false],
'uk_qt' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Imperial Quart (UK)', 'AllowPrefix' => false],
'gal' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Gallon', 'AllowPrefix' => false],
'uk_gal' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Imperial Gallon (UK)', 'AllowPrefix' => false],
'ang3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Angstrom', 'AllowPrefix' => true],
'ang^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Angstrom', 'AllowPrefix' => true],
'barrel' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'US Oil Barrel', 'AllowPrefix' => false],
'bushel' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'US Bushel', 'AllowPrefix' => false],
'in3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Inch', 'AllowPrefix' => false],
'in^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Inch', 'AllowPrefix' => false],
'ft3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Foot', 'AllowPrefix' => false],
'ft^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Foot', 'AllowPrefix' => false],
'ly3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Light Year', 'AllowPrefix' => false],
'ly^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Light Year', 'AllowPrefix' => false],
'm3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Meter', 'AllowPrefix' => true],
'm^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Meter', 'AllowPrefix' => true],
'mi3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Mile', 'AllowPrefix' => false],
'mi^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Mile', 'AllowPrefix' => false],
'yd3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Yard', 'AllowPrefix' => false],
'yd^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Yard', 'AllowPrefix' => false],
'Nmi3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Nautical Mile', 'AllowPrefix' => false],
'Nmi^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Nautical Mile', 'AllowPrefix' => false],
'Pica3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Pica', 'AllowPrefix' => false],
'Pica^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Pica', 'AllowPrefix' => false],
'Picapt3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Pica', 'AllowPrefix' => false],
'Picapt^3' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Cubic Pica', 'AllowPrefix' => false],
'GRT' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Gross Registered Ton', 'AllowPrefix' => false],
'regton' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Gross Registered Ton', 'AllowPrefix' => false],
'MTON' => ['Group' => self::CATEGORY_VOLUME, 'UnitName' => 'Measurement Ton (Freight Ton)', 'AllowPrefix' => false],
// Area
'ha' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Hectare', 'AllowPrefix' => true],
'uk_acre' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'International Acre', 'AllowPrefix' => false],
'us_acre' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'US Survey/Statute Acre', 'AllowPrefix' => false],
'ang2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Angstrom', 'AllowPrefix' => true],
'ang^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Angstrom', 'AllowPrefix' => true],
'ar' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Are', 'AllowPrefix' => true],
'ft2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Feet', 'AllowPrefix' => false],
'ft^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Feet', 'AllowPrefix' => false],
'in2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Inches', 'AllowPrefix' => false],
'in^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Inches', 'AllowPrefix' => false],
'ly2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Light Years', 'AllowPrefix' => false],
'ly^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Light Years', 'AllowPrefix' => false],
'm2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Meters', 'AllowPrefix' => true],
'm^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Meters', 'AllowPrefix' => true],
'Morgen' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Morgen', 'AllowPrefix' => false],
'mi2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Miles', 'AllowPrefix' => false],
'mi^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Miles', 'AllowPrefix' => false],
'Nmi2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Nautical Miles', 'AllowPrefix' => false],
'Nmi^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Nautical Miles', 'AllowPrefix' => false],
'Pica2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Pica', 'AllowPrefix' => false],
'Pica^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Pica', 'AllowPrefix' => false],
'Picapt2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Pica', 'AllowPrefix' => false],
'Picapt^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Pica', 'AllowPrefix' => false],
'yd2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Yards', 'AllowPrefix' => false],
'yd^2' => ['Group' => self::CATEGORY_AREA, 'UnitName' => 'Square Yards', 'AllowPrefix' => false],
// Information
'byte' => ['Group' => self::CATEGORY_INFORMATION, 'UnitName' => 'Byte', 'AllowPrefix' => true],
'bit' => ['Group' => self::CATEGORY_INFORMATION, 'UnitName' => 'Bit', 'AllowPrefix' => true],
// Speed
'm/s' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Meters per second', 'AllowPrefix' => true],
'm/sec' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Meters per second', 'AllowPrefix' => true],
'm/h' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Meters per hour', 'AllowPrefix' => true],
'm/hr' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Meters per hour', 'AllowPrefix' => true],
'mph' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Miles per hour', 'AllowPrefix' => false],
'admkn' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Admiralty Knot', 'AllowPrefix' => false],
'kn' => ['Group' => self::CATEGORY_SPEED, 'UnitName' => 'Knot', 'AllowPrefix' => false],
];
/**
* Details of the Multiplier prefixes that can be used with Units of Measure in CONVERTUOM().
*
* @var array
*/
private static array $conversionMultipliers = [
'Y' => ['multiplier' => 1E24, 'name' => 'yotta'],
'Z' => ['multiplier' => 1E21, 'name' => 'zetta'],
'E' => ['multiplier' => 1E18, 'name' => 'exa'],
'P' => ['multiplier' => 1E15, 'name' => 'peta'],
'T' => ['multiplier' => 1E12, 'name' => 'tera'],
'G' => ['multiplier' => 1E9, 'name' => 'giga'],
'M' => ['multiplier' => 1E6, 'name' => 'mega'],
'k' => ['multiplier' => 1E3, 'name' => 'kilo'],
'h' => ['multiplier' => 1E2, 'name' => 'hecto'],
'e' => ['multiplier' => 1E1, 'name' => 'dekao'],
'da' => ['multiplier' => 1E1, 'name' => 'dekao'],
'd' => ['multiplier' => 1E-1, 'name' => 'deci'],
'c' => ['multiplier' => 1E-2, 'name' => 'centi'],
'm' => ['multiplier' => 1E-3, 'name' => 'milli'],
'u' => ['multiplier' => 1E-6, 'name' => 'micro'],
'n' => ['multiplier' => 1E-9, 'name' => 'nano'],
'p' => ['multiplier' => 1E-12, 'name' => 'pico'],
'f' => ['multiplier' => 1E-15, 'name' => 'femto'],
'a' => ['multiplier' => 1E-18, 'name' => 'atto'],
'z' => ['multiplier' => 1E-21, 'name' => 'zepto'],
'y' => ['multiplier' => 1E-24, 'name' => 'yocto'],
];
/**
* Details of the Multiplier prefixes that can be used with Units of Measure in CONVERTUOM().
*
* @var array
*/
private static array $binaryConversionMultipliers = [
'Yi' => ['multiplier' => 2 ** 80, 'name' => 'yobi'],
'Zi' => ['multiplier' => 2 ** 70, 'name' => 'zebi'],
'Ei' => ['multiplier' => 2 ** 60, 'name' => 'exbi'],
'Pi' => ['multiplier' => 2 ** 50, 'name' => 'pebi'],
'Ti' => ['multiplier' => 2 ** 40, 'name' => 'tebi'],
'Gi' => ['multiplier' => 2 ** 30, 'name' => 'gibi'],
'Mi' => ['multiplier' => 2 ** 20, 'name' => 'mebi'],
'ki' => ['multiplier' => 2 ** 10, 'name' => 'kibi'],
];
/**
* Details of the Units of measure conversion factors, organised by group.
*
* @var array>
*/
private static array $unitConversions = [
// Conversion uses gram (g) as an intermediate unit
self::CATEGORY_WEIGHT_AND_MASS => [
'g' => 1.0,
'sg' => 6.85217658567918E-05,
'lbm' => 2.20462262184878E-03,
'u' => 6.02214179421676E+23,
'ozm' => 3.52739619495804E-02,
'grain' => 1.54323583529414E+01,
'cwt' => 2.20462262184878E-05,
'shweight' => 2.20462262184878E-05,
'uk_cwt' => 1.96841305522212E-05,
'lcwt' => 1.96841305522212E-05,
'hweight' => 1.96841305522212E-05,
'stone' => 1.57473044417770E-04,
'ton' => 1.10231131092439E-06,
'uk_ton' => 9.84206527611061E-07,
'LTON' => 9.84206527611061E-07,
'brton' => 9.84206527611061E-07,
],
// Conversion uses meter (m) as an intermediate unit
self::CATEGORY_DISTANCE => [
'm' => 1.0,
'mi' => 6.21371192237334E-04,
'Nmi' => 5.39956803455724E-04,
'in' => 3.93700787401575E+01,
'ft' => 3.28083989501312E+00,
'yd' => 1.09361329833771E+00,
'ang' => 1.0E+10,
'ell' => 8.74890638670166E-01,
'ly' => 1.05700083402462E-16,
'parsec' => 3.24077928966473E-17,
'pc' => 3.24077928966473E-17,
'Pica' => 2.83464566929134E+03,
'Picapt' => 2.83464566929134E+03,
'pica' => 2.36220472440945E+02,
'survey_mi' => 6.21369949494950E-04,
],
// Conversion uses second (s) as an intermediate unit
self::CATEGORY_TIME => [
'yr' => 3.16880878140289E-08,
'day' => 1.15740740740741E-05,
'd' => 1.15740740740741E-05,
'hr' => 2.77777777777778E-04,
'mn' => 1.66666666666667E-02,
'min' => 1.66666666666667E-02,
'sec' => 1.0,
's' => 1.0,
],
// Conversion uses Pascal (Pa) as an intermediate unit
self::CATEGORY_PRESSURE => [
'Pa' => 1.0,
'p' => 1.0,
'atm' => 9.86923266716013E-06,
'at' => 9.86923266716013E-06,
'mmHg' => 7.50063755419211E-03,
'psi' => 1.45037737730209E-04,
'Torr' => 7.50061682704170E-03,
],
// Conversion uses Newton (N) as an intermediate unit
self::CATEGORY_FORCE => [
'N' => 1.0,
'dyn' => 1.0E+5,
'dy' => 1.0E+5,
'lbf' => 2.24808923655339E-01,
'pond' => 1.01971621297793E+02,
],
// Conversion uses Joule (J) as an intermediate unit
self::CATEGORY_ENERGY => [
'J' => 1.0,
'e' => 9.99999519343231E+06,
'c' => 2.39006249473467E-01,
'cal' => 2.38846190642017E-01,
'eV' => 6.24145700000000E+18,
'ev' => 6.24145700000000E+18,
'HPh' => 3.72506430801000E-07,
'hh' => 3.72506430801000E-07,
'Wh' => 2.77777916238711E-04,
'wh' => 2.77777916238711E-04,
'flb' => 2.37304222192651E+01,
'BTU' => 9.47815067349015E-04,
'btu' => 9.47815067349015E-04,
],
// Conversion uses Horsepower (HP) as an intermediate unit
self::CATEGORY_POWER => [
'HP' => 1.0,
'h' => 1.0,
'W' => 7.45699871582270E+02,
'w' => 7.45699871582270E+02,
'PS' => 1.01386966542400E+00,
],
// Conversion uses Tesla (T) as an intermediate unit
self::CATEGORY_MAGNETISM => [
'T' => 1.0,
'ga' => 10000.0,
],
// Conversion uses litre (l) as an intermediate unit
self::CATEGORY_VOLUME => [
'l' => 1.0,
'L' => 1.0,
'lt' => 1.0,
'tsp' => 2.02884136211058E+02,
'tspm' => 2.0E+02,
'tbs' => 6.76280454036860E+01,
'oz' => 3.38140227018430E+01,
'cup' => 4.22675283773038E+00,
'pt' => 2.11337641886519E+00,
'us_pt' => 2.11337641886519E+00,
'uk_pt' => 1.75975398639270E+00,
'qt' => 1.05668820943259E+00,
'uk_qt' => 8.79876993196351E-01,
'gal' => 2.64172052358148E-01,
'uk_gal' => 2.19969248299088E-01,
'ang3' => 1.0E+27,
'ang^3' => 1.0E+27,
'barrel' => 6.28981077043211E-03,
'bushel' => 2.83775932584017E-02,
'in3' => 6.10237440947323E+01,
'in^3' => 6.10237440947323E+01,
'ft3' => 3.53146667214886E-02,
'ft^3' => 3.53146667214886E-02,
'ly3' => 1.18093498844171E-51,
'ly^3' => 1.18093498844171E-51,
'm3' => 1.0E-03,
'm^3' => 1.0E-03,
'mi3' => 2.39912758578928E-13,
'mi^3' => 2.39912758578928E-13,
'yd3' => 1.30795061931439E-03,
'yd^3' => 1.30795061931439E-03,
'Nmi3' => 1.57426214685811E-13,
'Nmi^3' => 1.57426214685811E-13,
'Pica3' => 2.27769904358706E+07,
'Pica^3' => 2.27769904358706E+07,
'Picapt3' => 2.27769904358706E+07,
'Picapt^3' => 2.27769904358706E+07,
'GRT' => 3.53146667214886E-04,
'regton' => 3.53146667214886E-04,
'MTON' => 8.82866668037215E-04,
],
// Conversion uses hectare (ha) as an intermediate unit
self::CATEGORY_AREA => [
'ha' => 1.0,
'uk_acre' => 2.47105381467165E+00,
'us_acre' => 2.47104393046628E+00,
'ang2' => 1.0E+24,
'ang^2' => 1.0E+24,
'ar' => 1.0E+02,
'ft2' => 1.07639104167097E+05,
'ft^2' => 1.07639104167097E+05,
'in2' => 1.55000310000620E+07,
'in^2' => 1.55000310000620E+07,
'ly2' => 1.11725076312873E-28,
'ly^2' => 1.11725076312873E-28,
'm2' => 1.0E+04,
'm^2' => 1.0E+04,
'Morgen' => 4.0E+00,
'mi2' => 3.86102158542446E-03,
'mi^2' => 3.86102158542446E-03,
'Nmi2' => 2.91553349598123E-03,
'Nmi^2' => 2.91553349598123E-03,
'Pica2' => 8.03521607043214E+10,
'Pica^2' => 8.03521607043214E+10,
'Picapt2' => 8.03521607043214E+10,
'Picapt^2' => 8.03521607043214E+10,
'yd2' => 1.19599004630108E+04,
'yd^2' => 1.19599004630108E+04,
],
// Conversion uses bit (bit) as an intermediate unit
self::CATEGORY_INFORMATION => [
'bit' => 1.0,
'byte' => 0.125,
],
// Conversion uses Meters per Second (m/s) as an intermediate unit
self::CATEGORY_SPEED => [
'm/s' => 1.0,
'm/sec' => 1.0,
'm/h' => 3.60E+03,
'm/hr' => 3.60E+03,
'mph' => 2.23693629205440E+00,
'admkn' => 1.94260256941567E+00,
'kn' => 1.94384449244060E+00,
],
];
/**
* getConversionGroups
* Returns a list of the different conversion groups for UOM conversions.
*
* @return string[]
*/
public static function getConversionCategories(): array
{
$conversionGroups = [];
foreach (self::$conversionUnits as $conversionUnit) {
$conversionGroups[] = $conversionUnit['Group'];
}
return array_merge(array_unique($conversionGroups));
}
/**
* getConversionGroupUnits
* Returns an array of units of measure, for a specified conversion group, or for all groups.
*
* @param ?string $category The group whose units of measure you want to retrieve
*
* @return string[][]
*/
public static function getConversionCategoryUnits(?string $category = null): array
{
$conversionGroups = [];
foreach (self::$conversionUnits as $conversionUnit => $conversionGroup) {
if (($category === null) || ($conversionGroup['Group'] == $category)) {
$conversionGroups[$conversionGroup['Group']][] = $conversionUnit;
}
}
return $conversionGroups;
}
/**
* getConversionGroupUnitDetails.
*
* @param ?string $category The group whose units of measure you want to retrieve
*
* @return array>>
*/
public static function getConversionCategoryUnitDetails(?string $category = null): array
{
$conversionGroups = [];
foreach (self::$conversionUnits as $conversionUnit => $conversionGroup) {
if (($category === null) || ($conversionGroup['Group'] == $category)) {
$conversionGroups[$conversionGroup['Group']][] = [
'unit' => $conversionUnit,
'description' => $conversionGroup['UnitName'],
];
}
}
return $conversionGroups;
}
/**
* getConversionMultipliers
* Returns an array of the Multiplier prefixes that can be used with Units of Measure in CONVERTUOM().
*
* @return array
*/
public static function getConversionMultipliers(): array
{
return self::$conversionMultipliers;
}
/**
* getBinaryConversionMultipliers
* Returns an array of the additional Multiplier prefixes that can be used with Information Units of Measure in CONVERTUOM().
*
* @return array
*/
public static function getBinaryConversionMultipliers(): array
{
return self::$binaryConversionMultipliers;
}
/**
* CONVERT.
*
* Converts a number from one measurement system to another.
* For example, CONVERT can translate a table of distances in miles to a table of distances
* in kilometers.
*
* Excel Function:
* CONVERT(value,fromUOM,toUOM)
*
* @param array|float|int|string $value the value in fromUOM to convert
* Or can be an array of values
* @param string|string[] $fromUOM the units for value
* Or can be an array of values
* @param string|string[] $toUOM the units for the result
* Or can be an array of values
*
* @return float|mixed[]|string Result, or a string containing an error
* If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function CONVERT($value, $fromUOM, $toUOM)
{
if (is_array($value) || is_array($fromUOM) || is_array($toUOM)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $fromUOM, $toUOM);
}
if (!is_numeric($value)) {
return ExcelError::VALUE();
}
try {
[$fromUOM, $fromCategory, $fromMultiplier] = self::getUOMDetails($fromUOM);
[$toUOM, $toCategory, $toMultiplier] = self::getUOMDetails($toUOM);
} catch (Exception) {
return ExcelError::NA();
}
if ($fromCategory !== $toCategory) {
return ExcelError::NA();
}
// @var float $value
$value *= $fromMultiplier;
if (($fromUOM === $toUOM) && ($fromMultiplier === $toMultiplier)) {
// We've already factored $fromMultiplier into the value, so we need
// to reverse it again
return $value / $fromMultiplier;
} elseif ($fromUOM === $toUOM) {
return $value / $toMultiplier;
} elseif ($fromCategory === self::CATEGORY_TEMPERATURE) {
return self::convertTemperature($fromUOM, $toUOM, $value);
}
$baseValue = $value * (1.0 / self::$unitConversions[$fromCategory][$fromUOM]);
return ($baseValue * self::$unitConversions[$fromCategory][$toUOM]) / $toMultiplier;
}
/** @return array{0: string, 1: string, 2: float} */
private static function getUOMDetails(string $uom): array
{
if (isset(self::$conversionUnits[$uom])) {
$unitCategory = self::$conversionUnits[$uom]['Group'];
return [$uom, $unitCategory, 1.0];
}
// Check 1-character standard metric multiplier prefixes
$multiplierType = substr($uom, 0, 1);
$uom = substr($uom, 1);
if (isset(self::$conversionUnits[$uom], self::$conversionMultipliers[$multiplierType])) {
if (self::$conversionUnits[$uom]['AllowPrefix'] === false) {
throw new Exception('Prefix not allowed for UoM');
}
$unitCategory = self::$conversionUnits[$uom]['Group'];
return [$uom, $unitCategory, self::$conversionMultipliers[$multiplierType]['multiplier']];
}
$multiplierType .= substr($uom, 0, 1);
$uom = substr($uom, 1);
// Check 2-character standard metric multiplier prefixes
if (isset(self::$conversionUnits[$uom], self::$conversionMultipliers[$multiplierType])) {
if (self::$conversionUnits[$uom]['AllowPrefix'] === false) {
throw new Exception('Prefix not allowed for UoM');
}
$unitCategory = self::$conversionUnits[$uom]['Group'];
return [$uom, $unitCategory, self::$conversionMultipliers[$multiplierType]['multiplier']];
}
// Check 2-character binary multiplier prefixes
if (isset(self::$conversionUnits[$uom], self::$binaryConversionMultipliers[$multiplierType])) {
if (self::$conversionUnits[$uom]['AllowPrefix'] === false) {
throw new Exception('Prefix not allowed for UoM');
}
$unitCategory = self::$conversionUnits[$uom]['Group'];
if ($unitCategory !== 'Information') {
throw new Exception('Binary Prefix is only allowed for Information UoM');
}
return [$uom, $unitCategory, self::$binaryConversionMultipliers[$multiplierType]['multiplier']];
}
throw new Exception('UoM Not Found');
}
protected static function convertTemperature(string $fromUOM, string $toUOM, float|int $value): float|int
{
$fromUOM = self::resolveTemperatureSynonyms($fromUOM);
$toUOM = self::resolveTemperatureSynonyms($toUOM);
if ($fromUOM === $toUOM) {
return $value;
}
// Convert to Kelvin
switch ($fromUOM) {
case 'F':
$value = ($value - 32) / 1.8 + 273.15;
break;
case 'C':
$value += 273.15;
break;
case 'Rank':
$value /= 1.8;
break;
case 'Reau':
$value = $value * 1.25 + 273.15;
break;
}
// Convert from Kelvin
switch ($toUOM) {
case 'F':
$value = ($value - 273.15) * 1.8 + 32.00;
break;
case 'C':
$value -= 273.15;
break;
case 'Rank':
$value *= 1.8;
break;
case 'Reau':
$value = ($value - 273.15) * 0.80000;
break;
}
return $value;
}
private static function resolveTemperatureSynonyms(string $uom): string
{
return match ($uom) {
'fah' => 'F',
'cel' => 'C',
'kel' => 'K',
default => $uom,
};
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/EngineeringValidations.php
================================================
|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function ERF(mixed $lower, mixed $upper = null): array|float|string
{
if (is_array($lower) || is_array($upper)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $lower, $upper);
}
if (is_numeric($lower)) {
if ($upper === null) {
return self::erfValue($lower);
}
if (is_numeric($upper)) {
return self::erfValue($upper) - self::erfValue($lower);
}
}
return ExcelError::VALUE();
}
/**
* ERFPRECISE.
*
* Returns the error function integrated between the lower and upper bound arguments.
*
* Excel Function:
* ERF.PRECISE(limit)
*
* @param mixed $limit Float bound for integrating ERF, other bound is zero
* Or can be an array of values
*
* @return array|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function ERFPRECISE(mixed $limit)
{
if (is_array($limit)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $limit);
}
return self::ERF($limit);
}
private static function makeFloat(mixed $value): float
{
return is_numeric($value) ? ((float) $value) : 0.0;
}
/**
* Method to calculate the erf value.
*/
public static function erfValue(float|int|string $value): float
{
$value = (float) $value;
if (abs($value) > 2.2) {
return 1 - self::makeFloat(ErfC::ERFC($value));
}
$sum = $term = $value;
$xsqr = ($value * $value);
$j = 1;
do {
$term *= $xsqr / $j;
$sum -= $term / (2 * $j + 1);
++$j;
$term *= $xsqr / $j;
$sum += $term / (2 * $j + 1);
++$j;
if ($sum == 0.0) {
break;
}
} while (abs($term / $sum) > Functions::PRECISION);
return self::TWO_SQRT_PI * $sum;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Engineering/ErfC.php
================================================
|float|string If an array of numbers is passed as an argument, then the returned result will also be an array
* with the same dimensions
*/
public static function ERFC(mixed $value)
{
if (is_array($value)) {
return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $value);
}
if (is_numeric($value)) {
return self::erfcValue($value);
}
return ExcelError::VALUE();
}
private const ONE_SQRT_PI = 0.564189583547756287;
/**
* Method to calculate the erfc value.
*/
private static function erfcValue(float|int|string $value): float|int
{
$value = (float) $value;
if (abs($value) < 2.2) {
return 1 - Erf::erfValue($value);
}
if ($value < 0) {
return 2 - self::erfcValue(-$value);
}
$a = $n = 1;
$b = $c = $value;
$d = ($value * $value) + 0.5;
$q2 = $b / $d;
do {
$t = $a * $n + $b * $value;
$a = $b;
$b = $t;
$t = $c * $n + $d * $value;
$c = $d;
$d = $t;
$n += 0.5;
$q1 = $q2;
$q2 = $b / $d;
} while ((abs($q1 - $q2) / $q2) > Functions::PRECISION);
return self::ONE_SQRT_PI * exp(-$value * $value) * $q2;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Exception.php
================================================
line = $line;
$e->file = $file;
throw $e;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/ExceptionHandler.php
================================================
getMessage();
}
$yearFracx = DateTimeExcel\YearFrac::fraction($purchased, $firstPeriod, $basis);
if (is_string($yearFracx)) {
return $yearFracx;
}
/** @var float $yearFrac */
$yearFrac = $yearFracx;
$amortiseCoeff = self::getAmortizationCoefficient($rate);
$rate *= $amortiseCoeff;
$rate = (float) (string) $rate; // ugly way to avoid rounding problem
$fNRate = round($yearFrac * $rate * $cost, 0);
$cost -= $fNRate;
$fRest = $cost - $salvage;
for ($n = 0; $n < $period; ++$n) {
$fNRate = round($rate * $cost, 0);
$fRest -= $fNRate;
if ($fRest < 0.0) {
return match ($period - $n) {
1 => round($cost * 0.5, 0),
default => 0.0,
};
}
$cost -= $fNRate;
}
return $fNRate;
}
/**
* AMORLINC.
*
* Returns the depreciation for each accounting period.
* This function is provided for the French accounting system. If an asset is purchased in
* the middle of the accounting period, the prorated depreciation is taken into account.
*
* Excel Function:
* AMORLINC(cost,purchased,firstPeriod,salvage,period,rate[,basis])
*
* @param mixed $cost The cost of the asset as a float
* @param mixed $purchased Date of the purchase of the asset
* @param mixed $firstPeriod Date of the end of the first period
* @param mixed $salvage The salvage value at the end of the life of the asset
* @param mixed $period The period as a float
* @param mixed $rate Rate of depreciation as float
* @param mixed $basis Integer indicating the type of day count to use.
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
*
* @return float|string (string containing the error type if there is an error)
*/
public static function AMORLINC(
mixed $cost,
mixed $purchased,
mixed $firstPeriod,
mixed $salvage,
mixed $period,
mixed $rate,
mixed $basis = FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
): string|float {
$cost = Functions::flattenSingleValue($cost);
$purchased = Functions::flattenSingleValue($purchased);
$firstPeriod = Functions::flattenSingleValue($firstPeriod);
$salvage = Functions::flattenSingleValue($salvage);
$period = Functions::flattenSingleValue($period);
$rate = Functions::flattenSingleValue($rate);
$basis = Functions::flattenSingleValue($basis) ?? FinancialConstants::BASIS_DAYS_PER_YEAR_NASD;
try {
$cost = FinancialValidations::validateFloat($cost);
$purchased = FinancialValidations::validateDate($purchased);
$firstPeriod = FinancialValidations::validateDate($firstPeriod);
$salvage = FinancialValidations::validateFloat($salvage);
$period = FinancialValidations::validateFloat($period);
$rate = FinancialValidations::validateFloat($rate);
$basis = FinancialValidations::validateBasis($basis);
} catch (Exception $e) {
return $e->getMessage();
}
$fOneRate = $cost * $rate;
$fCostDelta = $cost - $salvage;
// Note, quirky variation for leap years on the YEARFRAC for this function
$purchasedYear = DateTimeExcel\DateParts::year($purchased);
$yearFracx = DateTimeExcel\YearFrac::fraction($purchased, $firstPeriod, $basis);
if (is_string($yearFracx)) {
return $yearFracx;
}
/** @var float $yearFrac */
$yearFrac = $yearFracx;
if (
$basis == FinancialConstants::BASIS_DAYS_PER_YEAR_ACTUAL
&& $yearFrac < 1
) {
$temp = Functions::scalar($purchasedYear);
if (is_int($temp) || is_string($temp)) {
if (DateTimeExcel\Helpers::isLeapYear($temp)) {
$yearFrac *= 365 / 366;
}
}
}
$f0Rate = $yearFrac * $rate * $cost;
$nNumOfFullPeriods = (int) (($cost - $salvage - $f0Rate) / $fOneRate);
if ($period == 0) {
return $f0Rate;
} elseif ($period <= $nNumOfFullPeriods) {
return $fOneRate;
} elseif ($period == ($nNumOfFullPeriods + 1)) {
return $fCostDelta - $fOneRate * $nNumOfFullPeriods - $f0Rate;
}
return 0.0;
}
private static function getAmortizationCoefficient(float $rate): float
{
// The depreciation coefficients are:
// Life of assets (1/rate) Depreciation coefficient
// Less than 3 years 1
// Between 3 and 4 years 1.5
// Between 5 and 6 years 2
// More than 6 years 2.5
$fUsePer = 1.0 / $rate;
if ($fUsePer < 3.0) {
return 1.0;
} elseif ($fUsePer < 4.0) {
return 1.5;
} elseif ($fUsePer <= 6.0) {
return 2.0;
}
return 2.5;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/CashFlowValidations.php
================================================
getMessage();
}
// Validate parameters
if ($start < 1 || $start > $end) {
return ExcelError::NAN();
}
// Calculate
$interest = 0;
for ($per = $start; $per <= $end; ++$per) {
$ipmt = Interest::payment($rate, $per, $periods, $presentValue, 0, $type);
if (is_string($ipmt)) {
return $ipmt;
}
$interest += $ipmt;
}
return $interest;
}
/**
* CUMPRINC.
*
* Returns the cumulative principal paid on a loan between the start and end periods.
*
* Excel Function:
* CUMPRINC(rate,nper,pv,start,end[,type])
*
* @param mixed $rate The Interest rate
* @param mixed $periods The total number of payment periods as an integer
* @param mixed $presentValue Present Value
* @param mixed $start The first period in the calculation.
* Payment periods are numbered beginning with 1.
* @param mixed $end the last period in the calculation
* @param mixed $type A number 0 or 1 and indicates when payments are due:
* 0 or omitted At the end of the period.
* 1 At the beginning of the period.
*/
public static function principal(
mixed $rate,
mixed $periods,
mixed $presentValue,
mixed $start,
mixed $end,
mixed $type = FinancialConstants::PAYMENT_END_OF_PERIOD
): string|float|int {
$rate = Functions::flattenSingleValue($rate);
$periods = Functions::flattenSingleValue($periods);
$presentValue = Functions::flattenSingleValue($presentValue);
$start = Functions::flattenSingleValue($start);
$end = Functions::flattenSingleValue($end);
$type = Functions::flattenSingleValue($type) ?? FinancialConstants::PAYMENT_END_OF_PERIOD;
try {
$rate = CashFlowValidations::validateRate($rate);
$periods = CashFlowValidations::validateInt($periods);
$presentValue = CashFlowValidations::validatePresentValue($presentValue);
$start = CashFlowValidations::validateInt($start);
$end = CashFlowValidations::validateInt($end);
$type = CashFlowValidations::validatePeriodType($type);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($start < 1 || $start > $end) {
return ExcelError::VALUE();
}
// Calculate
$principal = 0;
for ($per = $start; $per <= $end; ++$per) {
$ppmt = Payments::interestPayment($rate, $per, $periods, $presentValue, 0, $type);
if (is_string($ppmt)) {
return $ppmt;
}
$principal += $ppmt;
}
return $principal;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Constant/Periodic/Interest.php
================================================
getMessage();
}
// Validate parameters
if ($period <= 0 || $period > $numberOfPeriods) {
return ExcelError::NAN();
}
// Calculate
$interestAndPrincipal = new InterestAndPrincipal(
$interestRate,
$period,
$numberOfPeriods,
$presentValue,
$futureValue,
$type
);
return $interestAndPrincipal->interest();
}
/**
* ISPMT.
*
* Returns the interest payment for an investment based on an interest rate and a constant payment schedule.
*
* Excel Function:
* =ISPMT(interest_rate, period, number_payments, pv)
*
* @param mixed $interestRate is the interest rate for the investment
* @param mixed $period is the period to calculate the interest rate. It must be between 1 and number_payments.
* @param mixed $numberOfPeriods is the number of payments for the annuity
* @param mixed $principleRemaining is the loan amount or present value of the payments
*/
public static function schedulePayment(mixed $interestRate, mixed $period, mixed $numberOfPeriods, mixed $principleRemaining): string|float
{
$interestRate = Functions::flattenSingleValue($interestRate);
$period = Functions::flattenSingleValue($period);
$numberOfPeriods = Functions::flattenSingleValue($numberOfPeriods);
$principleRemaining = Functions::flattenSingleValue($principleRemaining);
try {
$interestRate = CashFlowValidations::validateRate($interestRate);
$period = CashFlowValidations::validateInt($period);
$numberOfPeriods = CashFlowValidations::validateInt($numberOfPeriods);
$principleRemaining = CashFlowValidations::validateFloat($principleRemaining);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($period <= 0 || $period > $numberOfPeriods) {
return ExcelError::NAN();
}
// Return value
$returnValue = 0;
// Calculate
$principlePayment = ($principleRemaining * 1.0) / ($numberOfPeriods * 1.0);
for ($i = 0; $i <= $period; ++$i) {
$returnValue = $interestRate * $principleRemaining * -1;
$principleRemaining -= $principlePayment;
// principle needs to be 0 after the last payment, don't let floating point screw it up
if ($i == $numberOfPeriods) {
$returnValue = 0.0;
}
}
return $returnValue;
}
/**
* RATE.
*
* Returns the interest rate per period of an annuity.
* RATE is calculated by iteration and can have zero or more solutions.
* If the successive results of RATE do not converge to within 0.0000001 after 20 iterations,
* RATE returns the #NUM! error value.
*
* Excel Function:
* RATE(nper,pmt,pv[,fv[,type[,guess]]])
*
* @param mixed $numberOfPeriods The total number of payment periods in an annuity
* @param mixed $payment The payment made each period and cannot change over the life of the annuity.
* Typically, pmt includes principal and interest but no other fees or taxes.
* @param mixed $presentValue The present value - the total amount that a series of future payments is worth now
* @param mixed $futureValue The future value, or a cash balance you want to attain after the last payment is made.
* If fv is omitted, it is assumed to be 0 (the future value of a loan,
* for example, is 0).
* @param mixed $type A number 0 or 1 and indicates when payments are due:
* 0 or omitted At the end of the period.
* 1 At the beginning of the period.
* @param mixed $guess Your guess for what the rate will be.
* If you omit guess, it is assumed to be 10 percent.
*/
public static function rate(
mixed $numberOfPeriods,
mixed $payment,
mixed $presentValue,
mixed $futureValue = 0.0,
mixed $type = FinancialConstants::PAYMENT_END_OF_PERIOD,
mixed $guess = 0.1
): string|float {
$numberOfPeriods = Functions::flattenSingleValue($numberOfPeriods);
$payment = Functions::flattenSingleValue($payment);
$presentValue = Functions::flattenSingleValue($presentValue);
$futureValue = Functions::flattenSingleValue($futureValue) ?? 0.0;
$type = Functions::flattenSingleValue($type) ?? FinancialConstants::PAYMENT_END_OF_PERIOD;
$guess = Functions::flattenSingleValue($guess) ?? 0.1;
try {
$numberOfPeriods = CashFlowValidations::validateFloat($numberOfPeriods);
$payment = CashFlowValidations::validateFloat($payment);
$presentValue = CashFlowValidations::validatePresentValue($presentValue);
$futureValue = CashFlowValidations::validateFutureValue($futureValue);
$type = CashFlowValidations::validatePeriodType($type);
$guess = CashFlowValidations::validateFloat($guess);
} catch (Exception $e) {
return $e->getMessage();
}
$rate = $guess;
// rest of code adapted from python/numpy
$close = false;
$iter = 0;
while (!$close && $iter < self::FINANCIAL_MAX_ITERATIONS) {
$nextdiff = self::rateNextGuess($rate, $numberOfPeriods, $payment, $presentValue, $futureValue, $type);
if (!is_numeric($nextdiff)) {
break;
}
$rate1 = $rate - $nextdiff;
$close = abs($rate1 - $rate) < self::FINANCIAL_PRECISION;
++$iter;
$rate = $rate1;
}
return $close ? $rate : ExcelError::NAN();
}
private static function rateNextGuess(float $rate, float $numberOfPeriods, float $payment, float $presentValue, float $futureValue, int $type): string|float
{
if ($rate == 0.0) {
return ExcelError::NAN();
}
$tt1 = ($rate + 1) ** $numberOfPeriods;
$tt2 = ($rate + 1) ** ($numberOfPeriods - 1);
$numerator = $futureValue + $tt1 * $presentValue + $payment * ($tt1 - 1) * ($rate * $type + 1) / $rate;
$denominator = $numberOfPeriods * $tt2 * $presentValue - $payment * ($tt1 - 1)
* ($rate * $type + 1) / ($rate * $rate) + $numberOfPeriods
* $payment * $tt2 * ($rate * $type + 1) / $rate + $payment * ($tt1 - 1) * $type / $rate;
if ($denominator == 0) {
return ExcelError::NAN();
}
return $numerator / $denominator;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Constant/Periodic/InterestAndPrincipal.php
================================================
interest = $interest;
$this->principal = $principal;
}
public function interest(): float
{
return $this->interest;
}
public function principal(): float
{
return $this->principal;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Constant/Periodic/Payments.php
================================================
getMessage();
}
// Calculate
if ($interestRate != 0.0) {
return (-$futureValue - $presentValue * (1 + $interestRate) ** $numberOfPeriods)
/ (1 + $interestRate * $type) / (((1 + $interestRate) ** $numberOfPeriods - 1) / $interestRate);
}
return (-$presentValue - $futureValue) / $numberOfPeriods;
}
/**
* PPMT.
*
* Returns the interest payment for a given period for an investment based on periodic, constant payments
* and a constant interest rate.
*
* @param mixed $interestRate Interest rate per period
* @param mixed $period Period for which we want to find the interest
* @param mixed $numberOfPeriods Number of periods
* @param mixed $presentValue Present Value
* @param mixed $futureValue Future Value
* @param mixed $type Payment type: 0 = at the end of each period, 1 = at the beginning of each period
*
* @return float|string Result, or a string containing an error
*/
public static function interestPayment(
mixed $interestRate,
mixed $period,
mixed $numberOfPeriods,
mixed $presentValue,
mixed $futureValue = 0,
mixed $type = FinancialConstants::PAYMENT_END_OF_PERIOD
): string|float {
$interestRate = Functions::flattenSingleValue($interestRate);
$period = Functions::flattenSingleValue($period);
$numberOfPeriods = Functions::flattenSingleValue($numberOfPeriods);
$presentValue = Functions::flattenSingleValue($presentValue);
$futureValue = ($futureValue === null) ? 0.0 : Functions::flattenSingleValue($futureValue);
$type = Functions::flattenSingleValue($type) ?? FinancialConstants::PAYMENT_END_OF_PERIOD;
try {
$interestRate = CashFlowValidations::validateRate($interestRate);
$period = CashFlowValidations::validateInt($period);
$numberOfPeriods = CashFlowValidations::validateInt($numberOfPeriods);
$presentValue = CashFlowValidations::validatePresentValue($presentValue);
$futureValue = CashFlowValidations::validateFutureValue($futureValue);
$type = CashFlowValidations::validatePeriodType($type);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($period <= 0 || $period > $numberOfPeriods) {
return ExcelError::NAN();
}
// Calculate
$interestAndPrincipal = new InterestAndPrincipal(
$interestRate,
$period,
$numberOfPeriods,
$presentValue,
$futureValue,
$type
);
return $interestAndPrincipal->principal();
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Constant/Periodic.php
================================================
getMessage();
}
return self::calculateFutureValue($rate, $numberOfPeriods, $payment, $presentValue, $type);
}
/**
* PV.
*
* Returns the Present Value of a cash flow with constant payments and interest rate (annuities).
*
* @param mixed $rate Interest rate per period
* @param mixed $numberOfPeriods Number of periods as an integer
* @param mixed $payment Periodic payment (annuity)
* @param mixed $futureValue Future Value
* @param mixed $type Payment type: 0 = at the end of each period, 1 = at the beginning of each period
*
* @return float|string Result, or a string containing an error
*/
public static function presentValue(
mixed $rate,
mixed $numberOfPeriods,
mixed $payment = 0.0,
mixed $futureValue = 0.0,
mixed $type = FinancialConstants::PAYMENT_END_OF_PERIOD
): string|float {
$rate = Functions::flattenSingleValue($rate);
$numberOfPeriods = Functions::flattenSingleValue($numberOfPeriods);
$payment = Functions::flattenSingleValue($payment) ?? 0.0;
$futureValue = Functions::flattenSingleValue($futureValue) ?? 0.0;
$type = Functions::flattenSingleValue($type) ?? FinancialConstants::PAYMENT_END_OF_PERIOD;
try {
$rate = CashFlowValidations::validateRate($rate);
$numberOfPeriods = CashFlowValidations::validateInt($numberOfPeriods);
$payment = CashFlowValidations::validateFloat($payment);
$futureValue = CashFlowValidations::validateFutureValue($futureValue);
$type = CashFlowValidations::validatePeriodType($type);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($numberOfPeriods < 0) {
return ExcelError::NAN();
}
return self::calculatePresentValue($rate, $numberOfPeriods, $payment, $futureValue, $type);
}
/**
* NPER.
*
* Returns the number of periods for a cash flow with constant periodic payments (annuities), and interest rate.
*
* @param mixed $rate Interest rate per period
* @param mixed $payment Periodic payment (annuity)
* @param mixed $presentValue Present Value
* @param mixed $futureValue Future Value
* @param mixed $type Payment type: 0 = at the end of each period, 1 = at the beginning of each period
*
* @return float|string Result, or a string containing an error
*/
public static function periods(
mixed $rate,
mixed $payment,
mixed $presentValue,
mixed $futureValue = 0.0,
mixed $type = FinancialConstants::PAYMENT_END_OF_PERIOD
) {
$rate = Functions::flattenSingleValue($rate);
$payment = Functions::flattenSingleValue($payment);
$presentValue = Functions::flattenSingleValue($presentValue);
$futureValue = Functions::flattenSingleValue($futureValue) ?? 0.0;
$type = Functions::flattenSingleValue($type) ?? FinancialConstants::PAYMENT_END_OF_PERIOD;
try {
$rate = CashFlowValidations::validateRate($rate);
$payment = CashFlowValidations::validateFloat($payment);
$presentValue = CashFlowValidations::validatePresentValue($presentValue);
$futureValue = CashFlowValidations::validateFutureValue($futureValue);
$type = CashFlowValidations::validatePeriodType($type);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($payment == 0.0) {
return ExcelError::NAN();
}
return self::calculatePeriods($rate, $payment, $presentValue, $futureValue, $type);
}
private static function calculateFutureValue(
float $rate,
int $numberOfPeriods,
float $payment,
float $presentValue,
int $type
): float {
if ($rate != 0) {
return -$presentValue
* (1 + $rate) ** $numberOfPeriods - $payment * (1 + $rate * $type) * ((1 + $rate) ** $numberOfPeriods - 1)
/ $rate;
}
return -$presentValue - $payment * $numberOfPeriods;
}
private static function calculatePresentValue(
float $rate,
int $numberOfPeriods,
float $payment,
float $futureValue,
int $type
): float {
if ($rate != 0.0) {
return (-$payment * (1 + $rate * $type)
* (((1 + $rate) ** $numberOfPeriods - 1) / $rate) - $futureValue) / (1 + $rate) ** $numberOfPeriods;
}
return -$futureValue - $payment * $numberOfPeriods;
}
private static function calculatePeriods(
float $rate,
float $payment,
float $presentValue,
float $futureValue,
int $type
): string|float {
if ($rate != 0.0) {
if ($presentValue == 0.0) {
return ExcelError::NAN();
}
return log(($payment * (1 + $rate * $type) / $rate - $futureValue)
/ ($presentValue + $payment * (1 + $rate * $type) / $rate)) / log(1 + $rate);
}
return (-$presentValue - $futureValue) / $payment;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Single.php
================================================
getMessage();
}
return $principal;
}
/**
* PDURATION.
*
* Calculates the number of periods required for an investment to reach a specified value.
*
* @param mixed $rate Interest rate per period
* @param mixed $presentValue Present Value
* @param mixed $futureValue Future Value
*
* @return float|string Result, or a string containing an error
*/
public static function periods(mixed $rate, mixed $presentValue, mixed $futureValue): string|float
{
$rate = Functions::flattenSingleValue($rate);
$presentValue = Functions::flattenSingleValue($presentValue);
$futureValue = Functions::flattenSingleValue($futureValue);
try {
$rate = CashFlowValidations::validateRate($rate);
$presentValue = CashFlowValidations::validatePresentValue($presentValue);
$futureValue = CashFlowValidations::validateFutureValue($futureValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($rate <= 0.0 || $presentValue <= 0.0 || $futureValue <= 0.0) {
return ExcelError::NAN();
}
return (log($futureValue) - log($presentValue)) / log(1 + $rate);
}
/**
* RRI.
*
* Calculates the interest rate required for an investment to grow to a specified future value .
*
* @param mixed $periods The number of periods over which the investment is made, expect array|float
* @param mixed $presentValue Present Value, expect array|float
* @param mixed $futureValue Future Value, expect array|float
*
* @return float|string Result, or a string containing an error
*/
public static function interestRate(mixed $periods = 0.0, mixed $presentValue = 0.0, mixed $futureValue = 0.0): string|float
{
$periods = Functions::flattenSingleValue($periods);
$presentValue = Functions::flattenSingleValue($presentValue);
$futureValue = Functions::flattenSingleValue($futureValue);
try {
$periods = CashFlowValidations::validateFloat($periods);
$presentValue = CashFlowValidations::validatePresentValue($presentValue);
$futureValue = CashFlowValidations::validateFutureValue($futureValue);
} catch (Exception $e) {
return $e->getMessage();
}
// Validate parameters
if ($periods <= 0.0 || $presentValue <= 0.0 || $futureValue < 0.0) {
return ExcelError::NAN();
}
return ($futureValue / $presentValue) ** (1 / $periods) - 1;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Variable/NonPeriodic.php
================================================
$values A series of cash flow payments, expecting float[]
* The series of values must contain at least one positive value & one negative value
* @param array $dates A series of payment dates
* The first payment date indicates the beginning of the schedule of payments
* All other dates must be later than this date, but they may occur in any order
* @param mixed $guess An optional guess at the expected answer
*/
public static function rate(mixed $values, $dates, mixed $guess = self::DEFAULT_GUESS): float|string
{
$rslt = self::xirrPart1($values, $dates);
/** @var array $dates */
if ($rslt !== '') {
return $rslt;
}
// create an initial range, with a root somewhere between 0 and guess
$guess = Functions::flattenSingleValue($guess) ?? self::DEFAULT_GUESS;
if (!is_numeric($guess)) {
return ExcelError::VALUE();
}
$guess = ($guess + 0.0) ?: self::DEFAULT_GUESS;
$x1 = 0.0;
$x2 = $guess + 0.0;
$f1 = self::xnpvOrdered($x1, $values, $dates, false);
$f2 = self::xnpvOrdered($x2, $values, $dates, false);
$found = false;
for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
if (!is_numeric($f1)) {
return $f1;
}
if (!is_numeric($f2)) {
return $f2;
}
$f1 = (float) $f1;
$f2 = (float) $f2;
if (($f1 * $f2) < 0.0) {
$found = true;
break;
} elseif (abs($f1) < abs($f2)) {
$x1 += 1.6 * ($x1 - $x2);
$f1 = self::xnpvOrdered($x1, $values, $dates, false);
} else {
$x2 += 1.6 * ($x2 - $x1);
$f2 = self::xnpvOrdered($x2, $values, $dates, false);
}
}
if ($found) {
return self::xirrPart3($values, $dates, $x1, $x2);
}
// Newton-Raphson didn't work - try bisection
$x1 = $guess - 0.5;
$x2 = $guess + 0.5;
for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
$f1 = self::xnpvOrdered($x1, $values, $dates, false, true);
$f2 = self::xnpvOrdered($x2, $values, $dates, false, true);
if (!is_numeric($f1) || !is_numeric($f2)) {
break;
}
if ($f1 * $f2 <= 0) {
$found = true;
break;
}
$x1 -= 0.5;
$x2 += 0.5;
}
if ($found) {
/** @var array $dates */
return self::xirrBisection($values, $dates, $x1, $x2);
}
return ExcelError::NAN();
}
/**
* XNPV.
*
* Returns the net present value for a schedule of cash flows that is not necessarily periodic.
* To calculate the net present value for a series of cash flows that is periodic, use the NPV function.
*
* Excel Function:
* =XNPV(rate,values,dates)
*
* @param mixed $rate the discount rate to apply to the cash flows, expect array|float
* @param array $values A series of cash flows that corresponds to a schedule of payments in dates, expecting float[].
* The first payment is optional and corresponds to a cost or payment that occurs
* at the beginning of the investment.
* If the first value is a cost or payment, it must be a negative value.
* All succeeding payments are discounted based on a 365-day year.
* The series of values must contain at least one positive value and one negative value.
* @param mixed $dates A schedule of payment dates that corresponds to the cash flow payments, expecting mixed[].
* The first payment date indicates the beginning of the schedule of payments.
* All other dates must be later than this date, but they may occur in any order.
*/
public static function presentValue(mixed $rate, mixed $values, mixed $dates): float|string
{
return self::xnpvOrdered($rate, $values, $dates, true);
}
private static function bothNegAndPos(bool $neg, bool $pos): bool
{
return $neg && $pos;
}
/** @param array $values */
private static function xirrPart1(mixed &$values, mixed &$dates): string
{
/** @var array */
$temp = Functions::flattenArray($values);
$values = $temp;
$dates = Functions::flattenArray($dates);
$valuesIsArray = count($values) > 1;
$datesIsArray = count($dates) > 1;
if (!$valuesIsArray && !$datesIsArray) {
return ExcelError::NA();
}
if (count($values) != count($dates)) {
return ExcelError::NAN();
}
$datesCount = count($dates);
for ($i = 0; $i < $datesCount; ++$i) {
try {
$dates[$i] = DateTimeExcel\Helpers::getDateValue($dates[$i]);
} catch (Exception $e) {
return $e->getMessage();
}
}
return self::xirrPart2($values);
}
/** @param array $values */
private static function xirrPart2(array &$values): string
{
$valCount = count($values);
$foundpos = false;
$foundneg = false;
for ($i = 0; $i < $valCount; ++$i) {
$fld = $values[$i];
if (!is_numeric($fld)) { //* @phpstan-ignore-line
return ExcelError::VALUE();
} elseif ($fld > 0) {
$foundpos = true;
} elseif ($fld < 0) {
$foundneg = true;
}
}
if (!self::bothNegAndPos($foundneg, $foundpos)) {
return ExcelError::NAN();
}
return '';
}
/**
* @param array $values
* @param array $dates
*/
private static function xirrPart3(array $values, array $dates, float $x1, float $x2): float|string
{
$f = self::xnpvOrdered($x1, $values, $dates, false);
if ($f < 0.0) {
$rtb = $x1;
$dx = $x2 - $x1;
} else {
$rtb = $x2;
$dx = $x1 - $x2;
}
$rslt = ExcelError::VALUE();
for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
$dx *= 0.5;
$x_mid = $rtb + $dx;
$f_mid = (float) self::xnpvOrdered($x_mid, $values, $dates, false);
if ($f_mid <= 0.0) {
$rtb = $x_mid;
}
if ((abs($f_mid) < self::FINANCIAL_PRECISION) || (abs($dx) < self::FINANCIAL_PRECISION)) {
$rslt = $x_mid;
break;
}
}
return $rslt;
}
/**
* @param array $values
* @param array $dates
*/
private static function xirrBisection(array $values, array $dates, float $x1, float $x2): string|float
{
$rslt = ExcelError::NAN();
for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
$rslt = ExcelError::NAN();
$f1 = self::xnpvOrdered($x1, $values, $dates, false, true);
$f2 = self::xnpvOrdered($x2, $values, $dates, false, true);
if (!is_numeric($f1) || !is_numeric($f2)) {
break;
}
$f1 = (float) $f1;
$f2 = (float) $f2;
if (abs($f1) < self::FINANCIAL_PRECISION && abs($f2) < self::FINANCIAL_PRECISION) {
break;
}
if ($f1 * $f2 > 0) {
break;
}
$rslt = ($x1 + $x2) / 2;
$f3 = self::xnpvOrdered($rslt, $values, $dates, false, true);
if (!is_float($f3)) {
break;
}
if ($f3 * $f1 < 0) {
$x2 = $rslt;
} else {
$x1 = $rslt;
}
if (abs($f3) < self::FINANCIAL_PRECISION) {
break;
}
}
return $rslt;
}
/** @param array $values> */
private static function xnpvOrdered(mixed $rate, mixed $values, mixed $dates, bool $ordered = true, bool $capAtNegative1 = false): float|string
{
$rate = Functions::flattenSingleValue($rate);
if (!is_numeric($rate)) {
return ExcelError::VALUE();
}
$values = Functions::flattenArray($values);
$dates = Functions::flattenArray($dates);
$valCount = count($values);
try {
self::validateXnpv($rate, $values, $dates);
if ($capAtNegative1 && $rate <= -1) {
$rate = -1.0 + 1.0E-10;
}
$date0 = DateTimeExcel\Helpers::getDateValue($dates[0]);
} catch (Exception $e) {
return $e->getMessage();
}
$xnpv = 0.0;
for ($i = 0; $i < $valCount; ++$i) {
if (!is_numeric($values[$i])) {
return ExcelError::VALUE();
}
try {
$datei = DateTimeExcel\Helpers::getDateValue($dates[$i]);
} catch (Exception $e) {
return $e->getMessage();
}
if ($date0 > $datei) {
$dif = $ordered ? ExcelError::NAN() : -((int) DateTimeExcel\Difference::interval($datei, $date0, 'd'));
} else {
$dif = Functions::scalar(DateTimeExcel\Difference::interval($date0, $datei, 'd'));
}
if (!is_numeric($dif)) {
return StringHelper::convertToString($dif);
}
if ($rate <= -1.0) {
$xnpv += -abs($values[$i] + 0) / (-1 - $rate) ** ($dif / 365);
} else {
$xnpv += $values[$i] / (1 + $rate) ** ($dif / 365);
}
}
return is_finite($xnpv) ? $xnpv : ExcelError::VALUE();
}
/**
* @param mixed[] $values
* @param mixed[] $dates
*/
private static function validateXnpv(mixed $rate, array $values, array $dates): void
{
if (!is_numeric($rate)) {
throw new Exception(ExcelError::VALUE());
}
$valCount = count($values);
if ($valCount != count($dates)) {
throw new Exception(ExcelError::NAN());
}
if (count($values) > 1 && ((min($values) > 0) || (max($values) < 0))) {
throw new Exception(ExcelError::NAN());
}
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/CashFlow/Variable/Periodic.php
================================================
0.0) {
return ExcelError::VALUE();
}
$f = self::presentValue($x1, $values);
if ($f < 0.0) {
$rtb = $x1;
$dx = $x2 - $x1;
} else {
$rtb = $x2;
$dx = $x1 - $x2;
}
for ($i = 0; $i < self::FINANCIAL_MAX_ITERATIONS; ++$i) {
$dx *= 0.5;
$x_mid = $rtb + $dx;
$f_mid = self::presentValue($x_mid, $values);
if ($f_mid <= 0.0) {
$rtb = $x_mid;
}
if ((abs($f_mid) < self::FINANCIAL_PRECISION) || (abs($dx) < self::FINANCIAL_PRECISION)) {
return $x_mid;
}
}
return ExcelError::VALUE();
}
/**
* MIRR.
*
* Returns the modified internal rate of return for a series of periodic cash flows. MIRR considers both
* the cost of the investment and the interest received on reinvestment of cash.
*
* Excel Function:
* MIRR(values,finance_rate, reinvestment_rate)
*
* @param mixed $values An array or a reference to cells that contain a series of payments and
* income occurring at regular intervals.
* Payments are negative value, income is positive values.
* @param mixed $financeRate The interest rate you pay on the money used in the cash flows
* @param mixed $reinvestmentRate The interest rate you receive on the cash flows as you reinvest them
*
* @return float|string Result, or a string containing an error
*/
public static function modifiedRate(mixed $values, mixed $financeRate, mixed $reinvestmentRate): string|float
{
if (!is_array($values)) {
return ExcelError::DIV0();
}
$values = Functions::flattenArray($values);
/** @var float */
$financeRate = Functions::flattenSingleValue($financeRate);
/** @var float */
$reinvestmentRate = Functions::flattenSingleValue($reinvestmentRate);
$n = count($values);
$rr = 1.0 + $reinvestmentRate;
$fr = 1.0 + $financeRate;
$npvPos = $npvNeg = 0.0;
foreach ($values as $i => $v) {
/** @var float $v */
if ($v >= 0) {
$npvPos += $v / $rr ** $i;
} else {
$npvNeg += $v / $fr ** $i;
}
}
if ($npvNeg === 0.0 || $npvPos === 0.0) {
return ExcelError::DIV0();
}
$mirr = ((-$npvPos * $rr ** $n)
/ ($npvNeg * ($rr))) ** (1.0 / ($n - 1)) - 1.0;
return is_finite($mirr) ? $mirr : ExcelError::NAN();
}
/**
* NPV.
*
* Returns the Net Present Value of a cash flow series given a discount rate.
*
* @param array $args
*/
public static function presentValue(mixed $rate, ...$args): int|float
{
$returnValue = 0;
/** @var float */
$rate = Functions::flattenSingleValue($rate);
$aArgs = Functions::flattenArray($args);
// Calculate
$countArgs = count($aArgs);
for ($i = 1; $i <= $countArgs; ++$i) {
// Is it a numeric value?
if (is_numeric($aArgs[$i - 1])) {
$returnValue += $aArgs[$i - 1] / (1 + $rate) ** $i;
}
}
return $returnValue;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/Constants.php
================================================
getMessage();
}
$daysPerYear = Helpers::daysPerYear(Functions::scalar(DateTimeExcel\DateParts::year($settlement)), $basis);
if (is_string($daysPerYear)) {
return ExcelError::VALUE();
}
$prev = self::couponFirstPeriodDate($settlement, $maturity, $frequency, self::PERIOD_DATE_PREVIOUS);
if ($basis === FinancialConstants::BASIS_DAYS_PER_YEAR_ACTUAL) {
return abs((float) DateTimeExcel\Days::between($prev, $settlement));
}
return (float) DateTimeExcel\YearFrac::fraction($prev, $settlement, $basis) * $daysPerYear;
}
/**
* COUPDAYS.
*
* Returns the number of days in the coupon period that contains the settlement date.
*
* Excel Function:
* COUPDAYS(settlement,maturity,frequency[,basis])
*
* @param mixed $settlement The security's settlement date.
* The security settlement date is the date after the issue
* date when the security is traded to the buyer.
* @param mixed $maturity The security's maturity date.
* The maturity date is the date when the security expires.
* @param mixed $frequency The number of coupon payments per year.
* Valid frequency values are:
* 1 Annual
* 2 Semi-Annual
* 4 Quarterly
* @param mixed $basis The type of day count to use (int).
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
*/
public static function COUPDAYS(
mixed $settlement,
mixed $maturity,
mixed $frequency,
mixed $basis = FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
): string|int|float {
$settlement = Functions::flattenSingleValue($settlement);
$maturity = Functions::flattenSingleValue($maturity);
$frequency = Functions::flattenSingleValue($frequency);
$basis = Functions::flattenSingleValue($basis) ?? FinancialConstants::BASIS_DAYS_PER_YEAR_NASD;
try {
$settlement = FinancialValidations::validateSettlementDate($settlement);
$maturity = FinancialValidations::validateMaturityDate($maturity);
self::validateCouponPeriod($settlement, $maturity);
$frequency = FinancialValidations::validateFrequency($frequency);
$basis = FinancialValidations::validateBasis($basis);
} catch (Exception $e) {
return $e->getMessage();
}
switch ($basis) {
case FinancialConstants::BASIS_DAYS_PER_YEAR_365:
// Actual/365
return 365 / $frequency;
case FinancialConstants::BASIS_DAYS_PER_YEAR_ACTUAL:
// Actual/actual
if ($frequency == FinancialConstants::FREQUENCY_ANNUAL) {
$daysPerYear = (int) Helpers::daysPerYear(Functions::scalar(DateTimeExcel\DateParts::year($settlement)), $basis);
return $daysPerYear / $frequency;
}
$prev = self::couponFirstPeriodDate($settlement, $maturity, $frequency, self::PERIOD_DATE_PREVIOUS);
$next = self::couponFirstPeriodDate($settlement, $maturity, $frequency, self::PERIOD_DATE_NEXT);
return $next - $prev;
default:
// US (NASD) 30/360, Actual/360 or European 30/360
return 360 / $frequency;
}
}
/**
* COUPDAYSNC.
*
* Returns the number of days from the settlement date to the next coupon date.
*
* Excel Function:
* COUPDAYSNC(settlement,maturity,frequency[,basis])
*
* @param mixed $settlement The security's settlement date.
* The security settlement date is the date after the issue
* date when the security is traded to the buyer.
* @param mixed $maturity The security's maturity date.
* The maturity date is the date when the security expires.
* @param mixed $frequency The number of coupon payments per year.
* Valid frequency values are:
* 1 Annual
* 2 Semi-Annual
* 4 Quarterly
* @param mixed $basis The type of day count to use (int) .
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
*/
public static function COUPDAYSNC(
mixed $settlement,
mixed $maturity,
mixed $frequency,
mixed $basis = FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
): string|float {
$settlement = Functions::flattenSingleValue($settlement);
$maturity = Functions::flattenSingleValue($maturity);
$frequency = Functions::flattenSingleValue($frequency);
$basis = Functions::flattenSingleValue($basis) ?? FinancialConstants::BASIS_DAYS_PER_YEAR_NASD;
try {
$settlement = FinancialValidations::validateSettlementDate($settlement);
$maturity = FinancialValidations::validateMaturityDate($maturity);
self::validateCouponPeriod($settlement, $maturity);
$frequency = FinancialValidations::validateFrequency($frequency);
$basis = FinancialValidations::validateBasis($basis);
} catch (Exception $e) {
return $e->getMessage();
}
/** @var int $daysPerYear */
$daysPerYear = Helpers::daysPerYear(Functions::Scalar(DateTimeExcel\DateParts::year($settlement)), $basis);
$next = self::couponFirstPeriodDate($settlement, $maturity, $frequency, self::PERIOD_DATE_NEXT);
if ($basis === FinancialConstants::BASIS_DAYS_PER_YEAR_NASD) {
$settlementDate = Date::excelToDateTimeObject($settlement);
$settlementEoM = Helpers::isLastDayOfMonth($settlementDate);
if ($settlementEoM) {
++$settlement;
}
}
return (float) DateTimeExcel\YearFrac::fraction($settlement, $next, $basis) * $daysPerYear;
}
/**
* COUPNCD.
*
* Returns the next coupon date after the settlement date.
*
* Excel Function:
* COUPNCD(settlement,maturity,frequency[,basis])
*
* @param mixed $settlement The security's settlement date.
* The security settlement date is the date after the issue
* date when the security is traded to the buyer.
* @param mixed $maturity The security's maturity date.
* The maturity date is the date when the security expires.
* @param mixed $frequency The number of coupon payments per year.
* Valid frequency values are:
* 1 Annual
* 2 Semi-Annual
* 4 Quarterly
* @param mixed $basis The type of day count to use (int).
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
*
* @return float|string Excel date/time serial value or error message
*/
public static function COUPNCD(
mixed $settlement,
mixed $maturity,
mixed $frequency,
mixed $basis = FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
): string|float {
$settlement = Functions::flattenSingleValue($settlement);
$maturity = Functions::flattenSingleValue($maturity);
$frequency = Functions::flattenSingleValue($frequency);
$basis = Functions::flattenSingleValue($basis) ?? FinancialConstants::BASIS_DAYS_PER_YEAR_NASD;
try {
$settlement = FinancialValidations::validateSettlementDate($settlement);
$maturity = FinancialValidations::validateMaturityDate($maturity);
self::validateCouponPeriod($settlement, $maturity);
$frequency = FinancialValidations::validateFrequency($frequency);
FinancialValidations::validateBasis($basis);
} catch (Exception $e) {
return $e->getMessage();
}
return self::couponFirstPeriodDate($settlement, $maturity, $frequency, self::PERIOD_DATE_NEXT);
}
/**
* COUPNUM.
*
* Returns the number of coupons payable between the settlement date and maturity date,
* rounded up to the nearest whole coupon.
*
* Excel Function:
* COUPNUM(settlement,maturity,frequency[,basis])
*
* @param mixed $settlement The security's settlement date.
* The security settlement date is the date after the issue
* date when the security is traded to the buyer.
* @param mixed $maturity The security's maturity date.
* The maturity date is the date when the security expires.
* @param mixed $frequency The number of coupon payments per year.
* Valid frequency values are:
* 1 Annual
* 2 Semi-Annual
* 4 Quarterly
* @param mixed $basis The type of day count to use (int).
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
*/
public static function COUPNUM(
mixed $settlement,
mixed $maturity,
mixed $frequency,
mixed $basis = FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
): string|int {
$settlement = Functions::flattenSingleValue($settlement);
$maturity = Functions::flattenSingleValue($maturity);
$frequency = Functions::flattenSingleValue($frequency);
$basis = Functions::flattenSingleValue($basis) ?? FinancialConstants::BASIS_DAYS_PER_YEAR_NASD;
try {
$settlement = FinancialValidations::validateSettlementDate($settlement);
$maturity = FinancialValidations::validateMaturityDate($maturity);
self::validateCouponPeriod($settlement, $maturity);
$frequency = FinancialValidations::validateFrequency($frequency);
FinancialValidations::validateBasis($basis);
} catch (Exception $e) {
return $e->getMessage();
}
$yearsBetweenSettlementAndMaturity = DateTimeExcel\YearFrac::fraction(
$settlement,
$maturity,
FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
);
return (int) ceil((float) $yearsBetweenSettlementAndMaturity * $frequency);
}
/**
* COUPPCD.
*
* Returns the previous coupon date before the settlement date.
*
* Excel Function:
* COUPPCD(settlement,maturity,frequency[,basis])
*
* @param mixed $settlement The security's settlement date.
* The security settlement date is the date after the issue
* date when the security is traded to the buyer.
* @param mixed $maturity The security's maturity date.
* The maturity date is the date when the security expires.
* @param mixed $frequency The number of coupon payments per year.
* Valid frequency values are:
* 1 Annual
* 2 Semi-Annual
* 4 Quarterly
* @param mixed $basis The type of day count to use (int).
* 0 or omitted US (NASD) 30/360
* 1 Actual/actual
* 2 Actual/360
* 3 Actual/365
* 4 European 30/360
*
* @return float|string Excel date/time serial value or error message
*/
public static function COUPPCD(
mixed $settlement,
mixed $maturity,
mixed $frequency,
mixed $basis = FinancialConstants::BASIS_DAYS_PER_YEAR_NASD
): string|float {
$settlement = Functions::flattenSingleValue($settlement);
$maturity = Functions::flattenSingleValue($maturity);
$frequency = Functions::flattenSingleValue($frequency);
$basis = Functions::flattenSingleValue($basis) ?? FinancialConstants::BASIS_DAYS_PER_YEAR_NASD;
try {
$settlement = FinancialValidations::validateSettlementDate($settlement);
$maturity = FinancialValidations::validateMaturityDate($maturity);
self::validateCouponPeriod($settlement, $maturity);
$frequency = FinancialValidations::validateFrequency($frequency);
FinancialValidations::validateBasis($basis);
} catch (Exception $e) {
return $e->getMessage();
}
return self::couponFirstPeriodDate($settlement, $maturity, $frequency, self::PERIOD_DATE_PREVIOUS);
}
private static function monthsDiff(DateTime $result, int $months, string $plusOrMinus, int $day, bool $lastDayFlag): void
{
$result->setDate((int) $result->format('Y'), (int) $result->format('m'), 1);
$result->modify("$plusOrMinus $months months");
$daysInMonth = (int) $result->format('t');
$result->setDate((int) $result->format('Y'), (int) $result->format('m'), $lastDayFlag ? $daysInMonth : min($day, $daysInMonth));
}
private static function couponFirstPeriodDate(float $settlement, float $maturity, int $frequency, bool $next): float
{
$months = 12 / $frequency;
$result = Date::excelToDateTimeObject($maturity);
$day = (int) $result->format('d');
$lastDayFlag = Helpers::isLastDayOfMonth($result);
while ($settlement < Date::PHPToExcel($result)) {
self::monthsDiff($result, $months, '-', $day, $lastDayFlag);
}
if ($next === true) {
self::monthsDiff($result, $months, '+', $day, $lastDayFlag);
}
return (float) Date::PHPToExcel($result);
}
private static function validateCouponPeriod(float $settlement, float $maturity): void
{
if ($settlement >= $maturity) {
throw new Exception(ExcelError::NAN());
}
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/Depreciation.php
================================================
getMessage();
}
if ($cost === self::$zeroPointZero) {
return 0.0;
}
// Set Fixed Depreciation Rate
$fixedDepreciationRate = 1 - ($salvage / $cost) ** (1 / $life);
$fixedDepreciationRate = round($fixedDepreciationRate, 3);
// Loop through each period calculating the depreciation
// TODO Handle period value between 0 and 1 (e.g. 0.5)
$previousDepreciation = 0;
$depreciation = 0;
for ($per = 1; $per <= $period; ++$per) {
if ($per == 1) {
$depreciation = $cost * $fixedDepreciationRate * $month / 12;
} elseif ($per == ($life + 1)) {
$depreciation = ($cost - $previousDepreciation) * $fixedDepreciationRate * (12 - $month) / 12;
} else {
$depreciation = ($cost - $previousDepreciation) * $fixedDepreciationRate;
}
$previousDepreciation += $depreciation;
}
return $depreciation;
}
/**
* DDB.
*
* Returns the depreciation of an asset for a specified period using the
* double-declining balance method or some other method you specify.
*
* Excel Function:
* DDB(cost,salvage,life,period[,factor])
*
* @param mixed $cost Initial cost of the asset
* @param mixed $salvage Value at the end of the depreciation.
* (Sometimes called the salvage value of the asset)
* @param mixed $life Number of periods over which the asset is depreciated.
* (Sometimes called the useful life of the asset)
* @param mixed $period The period for which you want to calculate the
* depreciation. Period must use the same units as life.
* @param mixed $factor The rate at which the balance declines.
* If factor is omitted, it is assumed to be 2 (the
* double-declining balance method).
*/
public static function DDB(mixed $cost, mixed $salvage, mixed $life, mixed $period, mixed $factor = 2.0): float|string
{
$cost = Functions::flattenSingleValue($cost);
$salvage = Functions::flattenSingleValue($salvage);
$life = Functions::flattenSingleValue($life);
$period = Functions::flattenSingleValue($period);
$factor = Functions::flattenSingleValue($factor);
try {
$cost = self::validateCost($cost);
$salvage = self::validateSalvage($salvage);
$life = self::validateLife($life);
$period = self::validatePeriod($period);
$factor = self::validateFactor($factor);
} catch (Exception $e) {
return $e->getMessage();
}
if ($period > $life) {
return ExcelError::NAN();
}
// Loop through each period calculating the depreciation
// TODO Handling for fractional $period values
$previousDepreciation = 0;
$depreciation = 0;
for ($per = 1; $per <= $period; ++$per) {
$depreciation = min(
($cost - $previousDepreciation) * ($factor / $life),
($cost - $salvage - $previousDepreciation)
);
$previousDepreciation += $depreciation;
}
return $depreciation;
}
/**
* SLN.
*
* Returns the straight-line depreciation of an asset for one period
*
* @param mixed $cost Initial cost of the asset
* @param mixed $salvage Value at the end of the depreciation
* @param mixed $life Number of periods over which the asset is depreciated
*
* @return float|string Result, or a string containing an error
*/
public static function SLN(mixed $cost, mixed $salvage, mixed $life): string|float
{
$cost = Functions::flattenSingleValue($cost);
$salvage = Functions::flattenSingleValue($salvage);
$life = Functions::flattenSingleValue($life);
try {
$cost = self::validateCost($cost, true);
$salvage = self::validateSalvage($salvage, true);
$life = self::validateLife($life, true);
} catch (Exception $e) {
return $e->getMessage();
}
if ($life === self::$zeroPointZero) {
return ExcelError::DIV0();
}
return ($cost - $salvage) / $life;
}
/**
* SYD.
*
* Returns the sum-of-years' digits depreciation of an asset for a specified period.
*
* @param mixed $cost Initial cost of the asset
* @param mixed $salvage Value at the end of the depreciation
* @param mixed $life Number of periods over which the asset is depreciated
* @param mixed $period Period
*
* @return float|string Result, or a string containing an error
*/
public static function SYD(mixed $cost, mixed $salvage, mixed $life, mixed $period): string|float
{
$cost = Functions::flattenSingleValue($cost);
$salvage = Functions::flattenSingleValue($salvage);
$life = Functions::flattenSingleValue($life);
$period = Functions::flattenSingleValue($period);
try {
$cost = self::validateCost($cost, true);
$salvage = self::validateSalvage($salvage);
$life = self::validateLife($life);
$period = self::validatePeriod($period);
} catch (Exception $e) {
return $e->getMessage();
}
if ($period > $life) {
return ExcelError::NAN();
}
$syd = (($cost - $salvage) * ($life - $period + 1) * 2) / ($life * ($life + 1));
return $syd;
}
private static function validateCost(mixed $cost, bool $negativeValueAllowed = false): float
{
$cost = FinancialValidations::validateFloat($cost);
if ($cost < 0.0 && $negativeValueAllowed === false) {
throw new Exception(ExcelError::NAN());
}
return $cost;
}
private static function validateSalvage(mixed $salvage, bool $negativeValueAllowed = false): float
{
$salvage = FinancialValidations::validateFloat($salvage);
if ($salvage < 0.0 && $negativeValueAllowed === false) {
throw new Exception(ExcelError::NAN());
}
return $salvage;
}
private static function validateLife(mixed $life, bool $negativeValueAllowed = false): float
{
$life = FinancialValidations::validateFloat($life);
if ($life < 0.0 && $negativeValueAllowed === false) {
throw new Exception(ExcelError::NAN());
}
return $life;
}
private static function validatePeriod(mixed $period, bool $negativeValueAllowed = false): float
{
$period = FinancialValidations::validateFloat($period);
if ($period <= 0.0 && $negativeValueAllowed === false) {
throw new Exception(ExcelError::NAN());
}
return $period;
}
private static function validateMonth(mixed $month): int
{
$month = FinancialValidations::validateInt($month);
if ($month < 1) {
throw new Exception(ExcelError::NAN());
}
return $month;
}
private static function validateFactor(mixed $factor): float
{
$factor = FinancialValidations::validateFloat($factor);
if ($factor <= 0.0) {
throw new Exception(ExcelError::NAN());
}
return $factor;
}
}
================================================
FILE: src/PhpSpreadsheet/Calculation/Financial/Dollar.php
================================================
|string If an array of values is passed for either of the arguments, then the returned result
* will also be an array with matching dimensions
*/
public static function format(mixed $number, mixed $precision = 2)
{
return Format::DOLLAR($number, $precision);
}
/**
* DOLLARDE.
*
* Converts a dollar price expressed as an integer part and a fraction
* part into a dollar price expressed as a decimal number.
* Fractional dollar numbers are sometimes used for security prices.
*
* Excel Function:
* DOLLARDE(fractional_dollar,fraction)
*
* @param mixed $fractionalDollar Fractional Dollar
* Or can be an array of values
* @param mixed $fraction Fraction
* Or can be an array of values
*
* @return array|float|string
*/
public static function decimal(mixed $fractionalDollar = null, mixed $fraction = 0): array|string|float
{
if (is_array($fractionalDollar) || is_array($fraction)) {
return self::evaluateArrayArguments([self::class, __FUNCTION__], $fractionalDollar, $fraction);
}
try {
$fractionalDollar = FinancialValidations::validateFloat(
Functions::flattenSingleValue($fractionalDollar) ?? 0.0
);
$fraction = FinancialValidations::validateInt(Functions::flattenSingleValue($fraction));
} catch (Exception $e) {
return $e->getMessage();
}
// Additional parameter validations
if ($fraction < 0) {
return ExcelError::NAN();
}
if ($fraction == 0) {
return ExcelError::DIV0();
}
$dollars = ($fractionalDollar < 0) ? ceil($fractionalDollar) : floor($fractionalDollar);
$cents = fmod($fractionalDollar, 1.0);
$cents /= $fraction;
$cents *= 10 ** ceil(log10($fraction));
return $dollars + $cents;
}
/**
* DOLLARFR.
*
* Converts a dollar price expressed as a decimal number into a dollar price
* expressed as a fraction.
* Fractional dollar numbers are sometimes used for security prices.
*
* Excel Function:
* DOLLARFR(decimal_dollar,fraction)
*
* @param mixed $decimalDollar Decimal Dollar
* Or can be an array of values
* @param mixed $fraction Fraction
* Or can be an array of values
*
* @return array
' . 'samples/templates/' . $inputFileName . '');
$helper->log('Read ' . $codePath . ' with conditional formatting');
$reader = IOFactory::createReader('Xlsx');
$reader->setReadDataOnly(false);
$spreadsheet = $reader->load($inputFilePath);
$helper->log('Enable conditional formatting output');
function writerCallback(HtmlWriter $writer): void
{
$writer->setPreCalculateFormulas(true);
$writer->setConditionalFormatting(true);
}
// Save
$helper->write($spreadsheet, __FILE__, ['Html'], false, writerCallback: writerCallback(...));
================================================
FILE: samples/Html/html_02_More_Conditional_Formatting.php
================================================
isCli() ? ('samples/templates/' . $inputFileName) : ('' . 'samples/templates/' . $inputFileName . '');
$helper->log('Read ' . $codePath . ' with conditional formatting');
$reader = IOFactory::createReader('Xlsx');
$reader->setReadDataOnly(false);
$spreadsheet = $reader->load($inputFilePath);
$helper->log('Enable conditional formatting output');
function writerCallback(HtmlWriter $writer): void
{
$writer->setPreCalculateFormulas(true);
$writer->setConditionalFormatting(true);
}
// Save
$helper->write($spreadsheet, __FILE__, ['Html'], false, writerCallback: writerCallback(...));
================================================
FILE: samples/Html/html_03_Color_Scale.php
================================================
isCli() ? ('samples/templates/' . $inputFileName) : ('' . 'samples/templates/' . $inputFileName . '');
$helper->log('Read ' . $codePath . ' with color scale');
$reader = IOFactory::createReader('Xlsx');
$reader->setReadDataOnly(false);
$spreadsheet = $reader->load($inputFilePath);
$helper->log('Enable conditional formatting output');
function writerCallback(HtmlWriter $writer): void
{
$writer->setPreCalculateFormulas(true);
$writer->setConditionalFormatting(true);
}
// Save
$helper->write($spreadsheet, __FILE__, ['Html'], false, writerCallback: writerCallback(...));
================================================
FILE: samples/Html/html_04_Table_Format_without_Conditional.php
================================================
isCli() ? ('samples/templates/' . $inputFileName) : ('' . 'samples/templates/' . $inputFileName . '');
$helper->log('Read ' . $codePath);
$reader = IOFactory::createReader('Xlsx');
$reader->setReadDataOnly(false);
$spreadsheet = $reader->load($inputFilePath);
$helper->log('Enable table formatting output');
function writerCallback(HtmlWriter $writer): void
{
$writer->setPreCalculateFormulas(true);
$writer->setTableFormats(true);
}
// Save
$helper->write($spreadsheet, __FILE__, ['Html'], false, writerCallback: writerCallback(...));
================================================
FILE: samples/Html/html_05_Table_Format_with_Conditional.php
================================================
isCli() ? ('samples/templates/' . $inputFileName) : ('' . 'samples/templates/' . $inputFileName . '');
$helper->log('Read ' . $codePath);
$reader = IOFactory::createReader('Xlsx');
$reader->setReadDataOnly(false);
$spreadsheet = $reader->load($inputFilePath);
$helper->log('Enable table formatting output');
$helper->log('Enable conditional formatting output');
function writerCallback(HtmlWriter $writer): void
{
$writer->setPreCalculateFormulas(true);
$writer->setTableFormats(true);
$writer->setConditionalFormatting(true);
}
// Save
$helper->write($spreadsheet, __FILE__, ['Html'], false, writerCallback: writerCallback(...));
================================================
FILE: samples/Html/html_06_Table_Cellspacing.php
================================================
log('Emulate table border, cellspacing, cellpadding attributes');
function addCellspacing(string $html): string
{
return str_replace(
'table { border-collapse:collapse }',
'table { border-collapse:separate; border-spacing: 5px; }'
. "\ntable.sheet0 {border: 1px solid red}"
. "\ntd, th {padding: 3px}",
$html
);
}
function writerCallback(HtmlWriter $writer): void
{
$writer->setLineEnding("\n")
->writeAllSheets()
->setEditHtmlCallback(addCellspacing(...));
}
$spreadsheet = new Spreadsheet();
$helper->log('Sheet1 will have no borders inside, red border outside from callback');
$sheet1 = $spreadsheet->getActiveSheet();
$sheet1->setTitle('Sheet1');
$sheet1->setShowGridlines(false);
$sheet1->setPrintGridlines(false);
$sheet1->fromArray([
[11, 12, 13],
[14, 15, 16],
]);
$helper->log('Sheet2 will have no borders (display), separate borders (print) from callback');
$sheet2 = $spreadsheet->createSheet();
$sheet2->setTitle('Sheet2');
$sheet2->setShowGridlines(false);
$sheet2->setPrintGridlines(true);
$sheet2->fromArray([
[21, 22, 23],
[24, 25, 26],
]);
$helper->log('Sheet3 will have no borders (print), separate borders (display) from callback');
$sheet3 = $spreadsheet->createSheet();
$sheet3->setTitle('Sheet3');
$sheet3->setShowGridlines(true);
$sheet3->setPrintGridlines(false);
$sheet3->fromArray([
[31, 32, 33],
[34, 35, 36],
]);
$helper->log('Sheet4 will have separate borders (print and display) from callback');
$sheet4 = $spreadsheet->createSheet();
$sheet4->setTitle('Sheet4');
$sheet4->setShowGridlines(true);
$sheet4->setPrintGridlines(true);
$sheet4->fromArray([
[41, 42, 43],
[44, 45, 46],
]);
$helper->log('Auto-size column dimensions');
foreach ([$sheet1, $sheet2, $sheet3, $sheet4] as $sheet) {
$sheet->getColumnDimension('A')->setAutoSize(true);
$sheet->getColumnDimension('B')->setAutoSize(true);
$sheet->getColumnDimension('C')->setAutoSize(true);
}
// Save
$helper->write($spreadsheet, __FILE__, ['Html'], false, writerCallback: writerCallback(...));
================================================
FILE: samples/LookupRef/ADDRESS.php
================================================
log('Returns a text reference to a single cell in a worksheet.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$worksheet->getCell('A1')->setValue('=ADDRESS(2,3)');
$worksheet->getCell('A2')->setValue('=ADDRESS(2,3,2)');
$worksheet->getCell('A3')->setValue('=ADDRESS(2,3,2,FALSE)');
$worksheet->getCell('A4')->setValue('=ADDRESS(2,3,1,FALSE,"[Book1.xlsx]Sheet1")');
$worksheet->getCell('A5')->setValue('=ADDRESS(2,3,1,FALSE,"EXCEL SHEET")');
for ($row = 1; $row <= 5; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/COLUMN.php
================================================
log('Returns the column index of a cell.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$calculation = Calculation::getInstance($spreadsheet);
$calculation->setInstanceArrayReturnType(
Calculation::RETURN_ARRAY_AS_VALUE
);
$worksheet = $spreadsheet->getActiveSheet();
$worksheet->getCell('A1')->setValue('=COLUMN(C13)');
$worksheet->getCell('A2')->setValue('=COLUMN(E13:G15)');
$worksheet->getCell('F1')->setValue('=COLUMN()');
for ($row = 1; $row <= 2; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
$cell = $worksheet->getCell('F1');
$helper->log('F1: ' . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
================================================
FILE: samples/LookupRef/COLUMNS.php
================================================
log('Returns the number of columns in an array or reference.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$worksheet->getCell('A1')->setValue('=COLUMNS(C1:G4)');
$worksheet->getCell('A2')->setValue('=COLUMNS({1,2,3;4,5,6})');
$worksheet->getCell('A3')->setValue('=ROWS(C1:E4 D3:G5)');
$worksheet->getCell('A4')->setValue('=COLUMNS(1:1)');
for ($row = 1; $row <= 4; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/INDEX.php
================================================
log('Returns the row index of a cell.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$data1 = [
['Apples', 'Lemons'],
['Bananas', 'Pears'],
];
$data2 = [
[4, 6],
[5, 3],
[6, 9],
[7, 5],
[8, 3],
];
$worksheet->fromArray($data1, null, 'A1');
$worksheet->fromArray($data2, null, 'C1');
$worksheet->getCell('A11')->setValue('=INDEX(A1:B2, 2, 2)');
$worksheet->getCell('A12')->setValue('=INDEX(A1:B2, 2, 1)');
$worksheet->getCell('A13')->setValue('=INDEX({1,2;3,4}, 0, 2)');
$worksheet->getCell('A14')->setValue('=INDEX(C1:C5, 5)');
$worksheet->getCell('A15')->setValue('=INDEX(C1:D5, 5, 2)');
$worksheet->getCell('A16')->setValue('=SUM(INDEX(C1:D5, 5, 0))');
for ($row = 11; $row <= 16; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/INDIRECT.php
================================================
log('Returns the cell specified by a text string.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$data = [
[8, 9, 0],
[3, 4, 5],
[9, 1, 3],
[4, 6, 2],
];
$worksheet->fromArray($data, null, 'C1');
$spreadsheet->addNamedRange(new NamedRange('NAMED_RANGE_FOR_CELL_D4', $worksheet, '="$D$4"'));
$worksheet->getCell('A1')->setValue('=INDIRECT("C1")');
$worksheet->getCell('A2')->setValue('=INDIRECT("D"&4)');
$worksheet->getCell('A3')->setValue('=INDIRECT("E"&ROW())');
$worksheet->getCell('A4')->setValue('=SUM(INDIRECT("$C$4:$E$4"))');
$worksheet->getCell('A5')->setValue('=INDIRECT(NAMED_RANGE_FOR_CELL_D4)');
for ($row = 1; $row <= 5; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/OFFSET.php
================================================
log('Returns a cell range that is a specified number of rows and columns from a cell or range of cells.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$data = [
[null, 'Week 1', 'Week 2', 'Week 3', 'Week 4'],
['Sunday', 4500, 2200, 3800, 1500],
['Monday', 5500, 6100, 5200, 4800],
['Tuesday', 7000, 6200, 5000, 7100],
['Wednesday', 8000, 4000, 3900, 7600],
['Thursday', 5900, 5500, 6900, 7100],
['Friday', 4900, 6300, 6900, 5200],
['Saturday', 3500, 3900, 5100, 4100],
];
$worksheet->fromArray($data, null, 'A3');
$worksheet->getCell('H1')->setValue('=OFFSET(A3, 3, 1)');
$worksheet->getCell('H2')->setValue('=SUM(OFFSET(A3, 3, 1, 1, 4))');
$worksheet->getCell('H3')->setValue('=SUM(OFFSET(B3:E3, 3, 0))');
$worksheet->getCell('H4')->setValue('=SUM(OFFSET(E3, 1, -3, 7))');
for ($row = 1; $row <= 4; ++$row) {
$cell = $worksheet->getCell("H{$row}");
$helper->log("H{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/ROW.php
================================================
log('Returns the row index of a cell.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$worksheet->getCell('A1')->setValue('=ROW(C13)');
$worksheet->getCell('A2')->setValue('=ROW(E19:G21)');
$worksheet->getCell('A3')->setValue('=ROW()');
for ($row = 1; $row <= 3; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/ROWS.php
================================================
log('Returns the row index of a cell.');
// Create new PhpSpreadsheet object
$spreadsheet = new Spreadsheet();
$worksheet = $spreadsheet->getActiveSheet();
$worksheet->getCell('A1')->setValue('=ROWS(C1:E4)');
$worksheet->getCell('A2')->setValue('=ROWS({1,2,3;4,5,6})');
$worksheet->getCell('A3')->setValue('=ROWS(C1:E4 D3:G5)');
for ($row = 1; $row <= 3; ++$row) {
$cell = $worksheet->getCell("A{$row}");
$helper->log("A{$row}: " . $cell->getValueString() . ' => ' . $cell->getCalculatedValueString());
}
================================================
FILE: samples/LookupRef/SortExcel.php
================================================
arrayCol] : $rowA;
$b = is_array($rowB) ? $rowB[$this->arrayCol] : $rowB;
if ($a instanceof Stringable) {
$a = (string) $a;
}
if ($b instanceof Stringable) {
$b = (string) $b;
}
if (is_array($a) || is_object($a) || is_resource($a) || is_array($b) || is_object($b) || is_resource($b)) {
throw new Exception('Invalid datatype');
}
// null sorts highest
if ($a === null) {
return ($b === null) ? 0 : $this->ascending;
}
if ($b === null) {
return -$this->ascending;
}
// int|float sorts lowest
$numericA = is_int($a) || is_float($a);
$numericB = is_int($b) || is_float($b);
if ($numericA && $numericB) {
if ($a == $b) {
return 0;
}
return ($a < $b) ? -$this->ascending : $this->ascending;
}
if ($numericA) {
return -$this->ascending;
}
if ($numericB) {
return $this->ascending;
}
// bool sorts higher than string
if (is_bool($a)) {
if (!is_bool($b)) {
return $this->ascending;
}
if ($a) {
return $b ? 0 : $this->ascending;
}
return $b ? -$this->ascending : 0;
}
if (is_bool($b)) {
return -$this->ascending;
}
// special handling for numeric strings starting with -
/** @var string $a */
$a2 = (string) preg_replace('/^-(\d)+$/', '$1', $a);
/** @var string $b */
$b2 = (string) preg_replace('/^-(\d)+$/', '$1', $b);
// strings sort case-insensitive
return $this->ascending * strcasecmp($a2, $b2);
}
/**
* @param mixed[] $array
*/
public function sortArray(array &$array, int $ascending = self::ASCENDING, int $arrayCol = 0): void
{
if ($ascending !== 1 && $ascending !== -1) {
throw new Exception('ascending must be 1 or -1');
}
$this->ascending = $ascending;
$this->arrayCol = $arrayCol;
usort($array, $this->cmp(...));
}
}
require __DIR__ . '/../Header.php';
/** @var Sample $helper */
$helper->log('Emulating how Excel sorts different DataTypes');
/** @param mixed[] $original */
function displaySorted(array $original, Sample $helper): void
{
$sorted = $original;
$sortExcel = new SortExcel();
$sortExcel->sortArray($sorted);
$outArray = [['Original', 'Sorted']];
$count = count($original);
for ($i = 0; $i < $count; ++$i) {
$outArray[] = [$original[$i], $sorted[$i]];
}
$helper->displayGrid($outArray, TextGridRightAlign::floatOrInt);
}
$helper->log('First example');
$original = ['-3', '40', 'A', 'B', true, false, '+3', '1', '10', '2', '25', 1, 0, -1];
displaySorted($original, $helper);
$helper->log('Second example');
$original = ['a', 'A', null, 'x', 'X', true, false, -3, 1];
displaySorted($original, $helper);
================================================
FILE: samples/LookupRef/SortExcelCols.php
================================================
arrayCol] : $rowA;
$b = is_array($rowB) ? $rowB[$this->arrayCol] : $rowB;
if ($a instanceof Stringable) {
$a = (string) $a;
}
if ($b instanceof Stringable) {
$b = (string) $b;
}
if (is_array($a) || is_object($a) || is_resource($a) || is_array($b) || is_object($b) || is_resource($b)) {
throw new Exception('Invalid datatype');
}
// null sorts highest
if ($a === null) {
return ($b === null) ? 0 : $this->ascending;
}
if ($b === null) {
return -$this->ascending;
}
// int|float sorts lowest
$numericA = is_int($a) || is_float($a);
$numericB = is_int($b) || is_float($b);
if ($numericA && $numericB) {
if ($a == $b) {
return 0;
}
return ($a < $b) ? -$this->ascending : $this->ascending;
}
if ($numericA) {
return -$this->ascending;
}
if ($numericB) {
return $this->ascending;
}
// bool sorts higher than string
if (is_bool($a)) {
if (!is_bool($b)) {
return $this->ascending;
}
if ($a) {
return $b ? 0 : $this->ascending;
}
return $b ? -$this->ascending : 0;
}
if (is_bool($b)) {
return -$this->ascending;
}
// special handling for numeric strings starting with -
/** @var string $a */
$a2 = (string) preg_replace('/^-(\d)+$/', '$1', $a);
/** @var string $b */
$b2 = (string) preg_replace('/^-(\d)+$/', '$1', $b);
// strings sort case-insensitive
return $this->ascending * strcasecmp($a2, $b2);
}
/**
* @param mixed[] $array
*/
public function sortArray(array &$array, int $ascending = self::ASCENDING, int $arrayCol = 0): void
{
if ($ascending !== 1 && $ascending !== -1) {
throw new Exception('ascending must be 1 or -1');
}
$this->ascending = $ascending;
$this->arrayCol = $arrayCol;
usort($array, $this->cmp(...));
}
}
require __DIR__ . '/../Header.php';
/** @var Sample $helper */
$helper->log('Emulating how Excel sorts different DataTypes by Column');
$array = [
['a', 'a', 'a'],
['a', 'a', 'b'],
['a', null, 'c'],
['b', 'b', 1],
['b', 'c', 2],
['b', 'c', true],
['c', 1, false],
['c', 1, 'a'],
['c', 2, 'b'],
[1, 2, 'c'],
[1, true, 1],
[1, true, 2],
[2, false, true],
[2, false, false],
[2, 'a', false],
[true, 'b', true],
[true, 'c', 2],
[true, 1, 1],
[false, 2, 'a'],
[false, true, 'b'],
[false, false, 'c'],
];
/** @param arraySerif
$lorem
Sans-Serif
$lorem
Monospace
$lorem
EOF; return preg_replace($bodystring, $bodyrepl, $html) ?? throw new SpreadsheetException('preg failed'); } require __DIR__ . '/../Header.php'; /** @var PhpOffice\PhpSpreadsheet\Spreadsheet */ $spreadsheet = require __DIR__ . '/../templates/sampleSpreadsheet.php'; /** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */ $helper->log('Hide grid lines'); $spreadsheet->getActiveSheet()->setShowGridLines(false); $helper->log('Set orientation to landscape'); $spreadsheet->getActiveSheet()->getPageSetup()->setOrientation(PageSetup::ORIENTATION_LANDSCAPE); $helper->log('Write to Dompdf'); IOFactory::registerWriter('Pdf', Dompdf::class); $filename = str_replace('.php', '_dompdf.php', __FILE__); $helper->write( $spreadsheet, $filename, ['Pdf'], false, function (Dompdf $writer): void { $writer->setEditHtmlCallback('replaceBody'); } ); $helper->log('Write to Mpdf'); IOFactory::registerWriter('Pdf', Mpdf::class); $filename = str_replace('.php', '_mpdf.php', __FILE__); $helper->write( $spreadsheet, $filename, ['Pdf'], false, function (Mpdf $writer): void { $writer->setEditHtmlCallback('replaceBody'); } ); $helper->log('Write to Tcpdf'); IOFactory::registerWriter('Pdf', TcpdfClass::class); $filename = str_replace('.php', '_tcpdf.php', __FILE__); $helper->write( $spreadsheet, $filename, ['Pdf'], false, function (TcpdfClass $writer): void { $writer->setEditHtmlCallback('replaceBody'); } ); ================================================ FILE: samples/Pdf/21d_FitToHeightPdf.php ================================================ log('Read spreadsheet'); $filename = '21d_FitToHeightPdf.xlsx'; $fileWithPath = __DIR__ . "/../templates/$filename"; $reader = new Xlsx(); $spreadsheet = $reader->load($fileWithPath); $sheet = $spreadsheet->getActiveSheet(); $helper->log('Write to Mpdf'); IOFactory::registerWriter('Pdf', PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf::class); $helper->write($spreadsheet, __FILE__, ['Pdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21e_UnusualFont_mpdf.php ================================================ getProperties() ->setCreator('PhpSpreadsheet') ->setTitle('Unusual Font'); $helper->log('Show print grid lines'); $sheet = $spreadsheet->getActiveSheet(); $sheet->setPrintGridLines(true); $sheet->getCell('A1')->setValue('First Cell'); $sheet->getCell('A2')->setValue('Second Cell'); $sheet->getCell('B1')->setValue('Third Cell'); $sheet->getCell('B2')->setValue('Fourth Cell'); $helper->log('Set style to unusual font'); $sheet->getStyle('A1:B2')->getFont()->setName('Shadows Into Light'); $helper->log('Write to Mpdf'); $writer = new Mpdf2($spreadsheet); $filename = $helper->getFileName(__FILE__, 'pdf'); $writer->save($filename); $helper->log("Saved $filename"); if (PHP_SAPI !== 'cli') { echo 'Download ' . basename($filename) . ''; } $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21f_Drawing.php ================================================ getActiveSheet(); $sheet->getCell('A1')->setValue('A1'); $sheet->getCell('B1')->setValue('B'); $sheet->getCell('C1')->setValue('C'); $sheet->getCell('D1')->setValue('D'); $sheet->getCell('E1')->setValue('E'); $sheet->getCell('F1')->setValue('F'); $sheet->getCell('G1')->setValue('G'); $sheet->getCell('A2')->setValue('A2'); $sheet->getCell('A3')->setValue('A3'); $sheet->getCell('A4')->setValue('A4'); $sheet->getCell('A5')->setValue('A5'); $sheet->getCell('A6')->setValue('A6'); $sheet->getCell('A7')->setValue('A7'); $sheet->getCell('A8')->setValue('A8'); $helper->log('Add drawing to worksheet'); $drawing = new Drawing(); $drawing->setName('Blue Square'); $path = __DIR__ . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'images/blue_square.png'; $drawing->setPath($path); $drawing->setResizeProportional(false); $drawing->setWidth(320); $drawing->setCoordinates('B2'); $drawing->setCoordinates2('G6'); $drawing->setWorksheet($sheet, true); $helper->log('Merge drawing cells for Pdf'); $spreadsheet->mergeDrawingCellsForPdf(); $helper->log('Write to Mpdf'); $helper->write($spreadsheet, __FILE__, ['Mpdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21g_Direction.php ================================================ getActiveSheet(); $sheet1 = $spreadsheet->getActiveSheet(); $sheet2 = $spreadsheet->createSheet(); $sheet3 = $spreadsheet->createSheet(); $cells = [ ['a1', 'b1', 'c1'], ['a2', 'b2', 'c2'], ]; $sheet1->fromArray($cells); $sheet1->setRightToLeft(true); $sheet2->fromArray($cells); $sheet3->fromArray($cells); $sheet3->setRightToLeft(true); $helper->log('Write to html, mpdf, tcpdf'); // Save $helper->write($spreadsheet, __FILE__, ['Html', 'Mpdf', 'Tcpdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/21h_DirectionMultiple.php ================================================ getActiveSheet(); $sheet1 = $spreadsheet->getActiveSheet(); $sheet2 = $spreadsheet->createSheet(); $sheet3 = $spreadsheet->createSheet(); $cells = [ ['a1', 'b1', 'c1'], ['a2', 'b2', 'c2'], ]; $sheet1->fromArray($cells); $sheet1->setRightToLeft(true); $sheet2->fromArray($cells); $sheet3->fromArray($cells); $sheet3->setRightToLeft(true); $helper->log('Write to html, mpdf'); // Save $helper->write( $spreadsheet, __FILE__, ['Html', 'Mpdf'], writerCallback: function (HtmlWriter $writer): void { $writer->writeAllSheets(); } ); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/Dompdf_Canvas_Headers.php ================================================ getCanvas()->page_script(function ( int $pageNumber, int $pageCount, Canvas $canvas, FontMetrics $fontMetrics ): void { // Get font metrics for dynamic content like page numbers $fontName = 'helvetica'; // note lowercase $fontType = 'bold'; // note lowercase $font = $fontMetrics->getFont($fontName, $fontType) ?? throw new Exception("no font metrics for $fontName $fontType"); // Example text placement (adjust coordinates and font as needed) if ($pageNumber === 1) { $header = 'Dompdf First Page'; } elseif ($pageNumber % 2 === 0) { $header = 'Dompdf Even Page'; } else { $header = 'Dompdf Odd Page'; } $text = "$header Page $pageNumber of $pageCount"; $canvas->text(40, 20, $text, $font, 12); }); } } $spreadsheet = new Spreadsheet(); $sheet = $spreadsheet->getActiveSheet(); $counter = 0; /** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */ $helper->log('Populate spreadsheet'); for ($row = 1; $row < 1001; ++$row) { $sheet->getCell("A$row")->setValue(++$counter); // Add many styles by using slight variations of font color for each. $sheet->getCell("A$row")->getStyle()->getFont() ->getColor()->setRgb(sprintf('%06x', $counter)); $sheet->getCell("B$row")->setValue(++$counter); $sheet->getCell("C$row")->setValue(++$counter); } $helper->log('Write to Dompdf with headers added by page_script'); IOFactory::registerWriter('Pdf', Dompdf_Canvas_Headers::class); $helper->write($spreadsheet, __FILE__, ['Pdf']); $spreadsheet->disconnectWorksheets(); ================================================ FILE: samples/Pdf/Dompdf_Custom_Headers.php ================================================ header { position: fixed; top: -0.5in; /* Position in top margin area */ height: 0.5in; width: 100%; text-align: center; } footer { position: fixed; bottom: -0.5in; /* Position in bottom margin area */ height: 0.5in; width: 100%; text-align: right; } .pagenum:before {content: counter(page);} EOF; $endhead = ''; $html = str_replace($endhead, "$headerFooter$endhead", $html); $bodystring = ''; $bodyrepl = <<
Worksheet Names
'); $helper->log('- ');
foreach ($worksheetNames as $worksheetName) {
$helper->log('
- ' . $worksheetName . ' '); } $helper->log('
Worksheet Information
'); $helper->log('- ');
foreach ($worksheetData as $worksheet) {
$helper->log('
- ' . $worksheet['worksheetName']); $helper->log('Rows: ' . $worksheet['totalRows'] . ' Columns: ' . $worksheet['totalColumns']); $helper->log('Cell Range: A1:' . $worksheet['lastColumnLetter'] . $worksheet['totalRows']); $helper->log(' '); } $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log( "\$wizard = new Wizard\\Accounting('{$_POST['currency']}', {$_POST['decimals']}, Wizard\\Number::" . (isset($_POST['thousands']) ? 'WITH_THOUSANDS_SEPARATOR' : 'WITHOUT_THOUSANDS_SEPARATOR') . ', Wizard\Currency::' . (((bool) $_POST['position']) ? 'LEADING_SYMBOL' : 'TRAILING_SYMBOL') . ');' ); $helper->log('$mask = $wizard->format();'); $helper->log('
echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Currency.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } $negatives = [ CurrencyNegative::minus, CurrencyNegative::redMinus, CurrencyNegative::parentheses, CurrencyNegative::redParentheses, ]; $negativesString = [ 'CurrencyNegative::minus', 'CurrencyNegative::redMinus', 'CurrencyNegative::parentheses', 'CurrencyNegative::redParentheses', ]; $currencies = [ '$' => 'US Dollars ($)', '€' => 'Euro (€)', '¥' => 'Japanese Yen (¥)', '£' => 'Pound Sterling (£)', '₹' => 'Rupee (₹)', '₽' => 'Rouble (₽)', ]; $postNegative = StringHelper::convertPostToString('negative'); if (!in_array($postNegative, ['0', '1', '2', '3'], true)) { $postNegative = '0'; } $postNegative = (int) $postNegative; ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } elseif (!in_array($_POST['currency'], array_keys($currencies), true)) { $helper->log('Unrecognized currency symbol'); } else { try { $negative = $negatives[$postNegative]; $wizard = new Wizard\Currency($_POST['currency'], (int) $_POST['decimals'], isset($_POST['thousands']), (bool) $_POST['position']); $wizard->setNegative($negative); $mask = $wizard->format(); $example = (string) NumberFormat::toFormattedString((float) $_POST['number'], $mask, [HtmlWriter::class, 'formatColorStatic']); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\CurrencyNegative;'); $helper->log( "\$wizard = new Wizard\\Currency('{$_POST['currency']}', {$_POST['decimals']}, Wizard\\Number::" . (isset($_POST['thousands']) ? 'WITH_THOUSANDS_SEPARATOR' : 'WITHOUT_THOUSANDS_SEPARATOR') . ', Wizard\Currency::' . (((bool) $_POST['position']) ? 'LEADING_SYMBOL' : 'TRAILING_SYMBOL') . ');' ); $helper->log('$wizard->setNegative(' . $negativesString[$postNegative] . ');'); $helper->log('$mask = $wizard->format();'); $helper->log('
echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Number.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } else { try { $wizard = new Wizard\Number((int) $_POST['decimals'], isset($_POST['thousands'])); $mask = $wizard->format(); $example = NumberFormat::toFormattedString((float) $_POST['number'], $mask); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log( "\$mask = Wizard\\Number({$_POST['decimals']}, Wizard\\Number::" . (isset($_POST['thousands']) ? 'WITH_THOUSANDS_SEPARATOR' : 'WITHOUT_THOUSANDS_SEPARATOR') . ');
' ); $helper->log('echo (string) $mask;'); $helper->log('
Mask:'); $helper->log($mask); $helper->log('Example:'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Percentage.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } else { try { $wizard = new Wizard\Percentage((int) $_POST['decimals']); $mask = $wizard->format(); $example = (string) NumberFormat::toFormattedString((float) $_POST['number'], $mask); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log("\$mask = Wizard\\Percentage({$_POST['decimals']});
"); $helper->log('echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/Wizards/NumberFormat/Scientific.php ================================================ isCli()) { $helper->log('This example should only be run from a Web Browser' . PHP_EOL); return; } ?> log('The Sample Number Value must be numeric'); } elseif (!is_numeric($_POST['decimals']) || str_contains((string) $_POST['decimals'], '.') || (int) $_POST['decimals'] < 0) { $helper->log('The Decimal Places value must be positive integer'); } else { try { $wizard = new Wizard\Scientific((int) $_POST['decimals']); $mask = $wizard->format(); $example = (string) NumberFormat::toFormattedString((float) $_POST['number'], $mask); $helper->log('
Code:
'); $helper->log('use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;'); $helper->log("\$mask = Wizard\\Scientific({$_POST['decimals']});
"); $helper->log('echo (string) $mask;'); $helper->log('
Mask:
'); $helper->log($mask . '
'); $helper->log('
Example:
'); $helper->log($example); } catch (SpreadsheetException $e) { $helper->log("Exception: {$e->getMessage()}"); } } } ================================================ FILE: samples/bootstrap/css/phpspreadsheet.css ================================================ body { padding-top: 20px; padding-bottom: 20px; } .navbar { margin-bottom: 20px; } .navbar + h1 { margin-top: 70px; } .passed { color: #339900; } .failed { color: #ff0000; } ================================================ FILE: samples/download.php ================================================ getTemporaryFolder(), $filename, $filetype); $downloader->download(); } catch (Exception $e) { exit($e->getMessage()); } ================================================ FILE: samples/index.php ================================================ version_compare(PHP_VERSION, '8.1', '>='), 'PHP extension XML' => extension_loaded('xml'), 'PHP extension xmlwriter' => extension_loaded('xmlwriter'), 'PHP extension mbstring' => extension_loaded('mbstring'), 'PHP extension ZipArchive' => extension_loaded('zip'), 'PHP extension GD (optional)' => extension_loaded('gd'), 'PHP extension dom (optional)' => extension_loaded('dom'), ]; /** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */ if (!$helper->isCli()) { ?>
Welcome to PHPSpreadsheet, a library written in pure PHP and providing a set of classes that allow you to read from and to write to different spreadsheet file formats, like Excel and LibreOffice Calc.
- ';
foreach ($requirements as $label => $result) {
$status = $result ? 'passed' : 'failed';
echo "
- {$label} ... {$status} "; } echo '
| Color Name | HEX | Color |
|---|---|---|
| Black | #000000 | |
| Blue | #0000FF | |
| Green | #008000 | |
| Cyan | #00FFFF | |
| Purple | #800080 | |
| Grey | #808080 | |
| SkyBlue | #87CEEB | |
| Brown | #A52A2A | |
| Silver | #C0C0C0 | |
| Chocolate | #D2691E | |
| Tan | #D2B48C | |
| Violet | #EE82EE | |
| Red | #FF0000 | |
| Pink | #FFC0CB | |
| Gold | #FFD700 | |
| Yellow | #FFFF00 | |
| LightYellow | #FFFFE0 | |
| White | #FFFFFF |