Skip to content

Commit f75ba8e

Browse files
AlkarexAlkarex
committed
Better documentation
1 parent 7216e80 commit f75ba8e

File tree

3 files changed

+120
-98
lines changed

3 files changed

+120
-98
lines changed

‎README.md‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -41,31 +41,36 @@ require 'vendor/alexandrainst/XlsxFastEditor/autoload.php';
4141
<?php
4242

4343
use alexandrainst\XlsxFastEditor\XlsxFastEditor;
44+
use alexandrainst\XlsxFastEditor\XlsxFastEditorException;
4445

45-
$xlsxFastEditor = new XlsxFastEditor('test.xlsx');
46+
try {
47+
$xlsxFastEditor = new XlsxFastEditor('test.xlsx');
4648

47-
$worksheetId1 = $xlsxFastEditor->getWorksheetNumber('Sheet1');
48-
$worksheetId2 = $xlsxFastEditor->getWorksheetNumber('Sheet2');
49+
$worksheetId1 = $xlsxFastEditor->getWorksheetNumber('Sheet1');
50+
$worksheetId2 = $xlsxFastEditor->getWorksheetNumber('Sheet2');
4951

50-
$fx = $xlsxFastEditor->readFormula($worksheetId1, 'A1');
51-
$f = $xlsxFastEditor->readFloat($worksheetId1, 'B2');
52-
$i = $xlsxFastEditor->readInt($worksheetId1, 'C3');
53-
$s = $xlsxFastEditor->readString($worksheetId2, 'D4');
52+
$fx = $xlsxFastEditor->readFormula($worksheetId1, 'A1');
53+
$f = $xlsxFastEditor->readFloat($worksheetId1, 'B2');
54+
$i = $xlsxFastEditor->readInt($worksheetId1, 'C3');
55+
$s = $xlsxFastEditor->readString($worksheetId2, 'D4');
5456

55-
// If you want to force Excel to recalculate formulas on next load:
56-
$xlsxFastEditor->setFullCalcOnLoad($worksheetId2, true);
57+
// If you want to force Excel to recalculate formulas on next load:
58+
$xlsxFastEditor->setFullCalcOnLoad($worksheetId2, true);
5759

58-
$xlsxFastEditor->writeFormula($worksheetId1, 'A1', '=B2*3');
59-
$xlsxFastEditor->writeFloat($worksheetId1, 'B2', 3.14);
60-
$xlsxFastEditor->writeInt($worksheetId1, 'C3', 13);
61-
$xlsxFastEditor->writeString($worksheetId2, 'D4', 'Hello');
60+
$xlsxFastEditor->writeFormula($worksheetId1, 'A1', '=B2*3');
61+
$xlsxFastEditor->writeFloat($worksheetId1, 'B2', 3.14);
62+
$xlsxFastEditor->writeInt($worksheetId1, 'C3', 13);
63+
$xlsxFastEditor->writeString($worksheetId2, 'D4', 'Hello');
6264

63-
// Regex search & replace operating globally on all the worksheets:
64-
$xlsxFastEditor->textReplace('/Hello/i', 'World');
65+
// Regex search & replace operating globally on all the worksheets:
66+
$xlsxFastEditor->textReplace('/Hello/i', 'World');
6567

66-
$xlsxFastEditor->save();
67-
// If you do not want to save, call `close()` instead:
68-
// $xlsxFastEditor->close();
68+
$xlsxFastEditor->save();
69+
// If you do not want to save, call `close()` instead:
70+
// $xlsxFastEditor->close();
71+
} catch (XlsxFastEditorException $xlsxe) {
72+
die($xlsxe->getMessage());
73+
}
6974
```
7075

7176
## Requirements

‎src/XlsxFastEditor.php‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,29 @@
11
<?php
22

3+
/**
4+
* PHP library to make basic but fast read & write operations on existing Excel workbooks.
5+
* Originally written by [Alexandre Alapetite](https://github.com/Alkarex) for the [Alexandra Institute](https://alexandra.dk/), 2023.
6+
*
7+
* @author Alexandre Alapetite <[email protected]>
8+
* @category PHP
9+
* @license https://gnu.org/licenses/agpl.html GNU AGPL
10+
* @link https://github.com/alexandrainst/php-xlsx-fast-editor
11+
* @package XlsxFastEditor
12+
*/
13+
314
namespace alexandrainst\XlsxFastEditor;
415

516
/**
6-
* Fast edit an existing XLSX/XLSM document (Microsoft Excel 2007+, Office Open XML Workbook)
17+
* Main class to fast edit an existing XLSX/XLSM document (Microsoft Excel 2007+, Office Open XML Workbook)
718
* using low-level ZIP and XML manipulation.
819
*/
920
final class XlsxFastEditor
1021
{
1122
private const OXML_NAMESPACE = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
23+
24+
private const CALC_CHAIN_CACHE_PATH = 'xl/calcChain.xml';
1225
private const SHARED_STRINGS_PATH = 'xl/sharedStrings.xml';
1326
private const WORKBOOK_PATH = 'xl/workbook.xml';
14-
private const CALC_CHAIN_CACHE_PATH = 'xl/calcChain.xml';
1527

1628
private \ZipArchive $zip;
1729

‎tests/test.php‎

Lines changed: 83 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -8,84 +8,89 @@
88
require(__DIR__ . '/../autoload.php');
99

1010
use alexandrainst\XlsxFastEditor\XlsxFastEditor;
11+
use alexandrainst\XlsxFastEditor\XlsxFastEditorException;
1112

1213
copy(__DIR__ . '/test.xlsx', __DIR__ . '/copy.xlsx');
1314

14-
$xlsxFastEditor = new XlsxFastEditor(__DIR__ . '/copy.xlsx');
15-
16-
$sheet1 = $xlsxFastEditor->getWorksheetNumber('Sheet1');
17-
assert($sheet1 === 1);
18-
19-
assert($xlsxFastEditor->readFloat($sheet1, 'D2') === 3.14159);
20-
assert($xlsxFastEditor->readFloat($sheet1, 'D4') === -1.0);
21-
assert($xlsxFastEditor->readFloat($sheet1, 'e5') === null);
22-
assert($xlsxFastEditor->readInt($sheet1, 'c3') === -5);
23-
assert($xlsxFastEditor->readInt($sheet1, 'F6') === null);
24-
assert($xlsxFastEditor->readString($sheet1, 'b4') === 'naïveté');
25-
assert($xlsxFastEditor->readString($sheet1, 'F7') === null);
26-
27-
$sheet2 = $xlsxFastEditor->getWorksheetNumber('Sheet2');
28-
assert($sheet2 === 2);
29-
30-
assert($xlsxFastEditor->readFormula($sheet2, 'c2') === '=Sheet1!C2*2');
31-
assert($xlsxFastEditor->readFloat($sheet2, 'D2') === 3.14159 * 2);
32-
assert($xlsxFastEditor->readFloat($sheet2, 'D4') === -1.0 * 2);
33-
assert($xlsxFastEditor->readInt($sheet2, 'c3') === -5 * 2);
34-
assert($xlsxFastEditor->readString($sheet2, 'B3') === 'déjà-vu');
35-
36-
// Existing cells
37-
$xlsxFastEditor->writeFormula($sheet1, 'c2', '=2*3');
38-
$xlsxFastEditor->writeString($sheet1, 'b4', 'α');
39-
$xlsxFastEditor->writeInt($sheet1, 'c4', 15);
40-
$xlsxFastEditor->writeFloat($sheet1, 'd4', -66.6);
41-
42-
// Existing cells with formulas
43-
$xlsxFastEditor->writeFormula($sheet2, 'c2', '=Sheet1!C2*3');
44-
$xlsxFastEditor->writeString($sheet2, 'B3', 'β');
45-
$xlsxFastEditor->writeInt($sheet2, 'C3', -7);
46-
$xlsxFastEditor->writeFloat($sheet2, 'D3', 273.15);
47-
48-
// Non-existing cells but existing lines
49-
$xlsxFastEditor->writeFormula($sheet2, 'I2', '=7*3');
50-
$xlsxFastEditor->writeString($sheet2, 'F2', 'γ');
51-
$xlsxFastEditor->writeInt($sheet2, 'G3', -7);
52-
$xlsxFastEditor->writeFloat($sheet2, 'H4', 273.15);
53-
54-
// Non-existing lines
55-
$xlsxFastEditor->writeFormula($sheet2, 'E11', '=7*5');
56-
$xlsxFastEditor->writeString($sheet2, 'B10', 'δ');
57-
$xlsxFastEditor->writeInt($sheet2, 'C9', 13);
58-
$xlsxFastEditor->writeFloat($sheet2, 'D10', -273.15);
59-
60-
assert($xlsxFastEditor->textReplace('/Hello/i', 'World') > 0);
61-
62-
$xlsxFastEditor->save();
63-
64-
$xlsxFastEditor = new XlsxFastEditor(__DIR__ . '/copy.xlsx');
65-
66-
assert($xlsxFastEditor->readFormula($sheet1, 'c2') === '=2*3');
67-
assert($xlsxFastEditor->readString($sheet1, 'B4') === 'α');
68-
assert($xlsxFastEditor->readInt($sheet1, 'C4') === 15);
69-
assert($xlsxFastEditor->readFloat($sheet1, 'D4') === -66.6);
70-
71-
assert($xlsxFastEditor->readFormula($sheet2, 'c2') === '=Sheet1!C2*3');
72-
assert($xlsxFastEditor->readString($sheet2, 'B3') === 'β');
73-
assert($xlsxFastEditor->readInt($sheet2, 'C3') === -7);
74-
assert($xlsxFastEditor->readFloat($sheet2, 'D3') === 273.15);
75-
76-
assert($xlsxFastEditor->readFormula($sheet2, 'I2') === '=7*3');
77-
assert($xlsxFastEditor->readString($sheet2, 'F2') === 'γ');
78-
assert($xlsxFastEditor->readInt($sheet2, 'G3') === -7);
79-
assert($xlsxFastEditor->readFloat($sheet2, 'H4') === 273.15);
80-
81-
assert($xlsxFastEditor->readFormula($sheet2, 'E11') === '=7*5');
82-
assert($xlsxFastEditor->readString($sheet2, 'B10') === 'δ');
83-
assert($xlsxFastEditor->readInt($sheet2, 'C9') === 13);
84-
assert($xlsxFastEditor->readFloat($sheet2, 'D10') === -273.15);
85-
86-
assert($xlsxFastEditor->readString($sheet1, 'B2') === 'World');
87-
88-
$xlsxFastEditor->close();
89-
90-
// Verify by hand that the resulting file opens without warning in Microsoft Excel
91-
// unlink(__DIR__ . '/copy.xlsx');
15+
try {
16+
$xlsxFastEditor = new XlsxFastEditor(__DIR__ . '/copy.xlsx');
17+
18+
$sheet1 = $xlsxFastEditor->getWorksheetNumber('Sheet1');
19+
assert($sheet1 === 1);
20+
21+
assert($xlsxFastEditor->readFloat($sheet1, 'D2') === 3.14159);
22+
assert($xlsxFastEditor->readFloat($sheet1, 'D4') === -1.0);
23+
assert($xlsxFastEditor->readFloat($sheet1, 'e5') === null);
24+
assert($xlsxFastEditor->readInt($sheet1, 'c3') === -5);
25+
assert($xlsxFastEditor->readInt($sheet1, 'F6') === null);
26+
assert($xlsxFastEditor->readString($sheet1, 'b4') === 'naïveté');
27+
assert($xlsxFastEditor->readString($sheet1, 'F7') === null);
28+
29+
$sheet2 = $xlsxFastEditor->getWorksheetNumber('Sheet2');
30+
assert($sheet2 === 2);
31+
32+
assert($xlsxFastEditor->readFormula($sheet2, 'c2') === '=Sheet1!C2*2');
33+
assert($xlsxFastEditor->readFloat($sheet2, 'D2') === 3.14159 * 2);
34+
assert($xlsxFastEditor->readFloat($sheet2, 'D4') === -1.0 * 2);
35+
assert($xlsxFastEditor->readInt($sheet2, 'c3') === -5 * 2);
36+
assert($xlsxFastEditor->readString($sheet2, 'B3') === 'déjà-vu');
37+
38+
// Existing cells
39+
$xlsxFastEditor->writeFormula($sheet1, 'c2', '=2*3');
40+
$xlsxFastEditor->writeString($sheet1, 'b4', 'α');
41+
$xlsxFastEditor->writeInt($sheet1, 'c4', 15);
42+
$xlsxFastEditor->writeFloat($sheet1, 'd4', -66.6);
43+
44+
// Existing cells with formulas
45+
$xlsxFastEditor->writeFormula($sheet2, 'c2', '=Sheet1!C2*3');
46+
$xlsxFastEditor->writeString($sheet2, 'B3', 'β');
47+
$xlsxFastEditor->writeInt($sheet2, 'C3', -7);
48+
$xlsxFastEditor->writeFloat($sheet2, 'D3', 273.15);
49+
50+
// Non-existing cells but existing lines
51+
$xlsxFastEditor->writeFormula($sheet2, 'I2', '=7*3');
52+
$xlsxFastEditor->writeString($sheet2, 'F2', 'γ');
53+
$xlsxFastEditor->writeInt($sheet2, 'G3', -7);
54+
$xlsxFastEditor->writeFloat($sheet2, 'H4', 273.15);
55+
56+
// Non-existing lines
57+
$xlsxFastEditor->writeFormula($sheet2, 'E11', '=7*5');
58+
$xlsxFastEditor->writeString($sheet2, 'B10', 'δ');
59+
$xlsxFastEditor->writeInt($sheet2, 'C9', 13);
60+
$xlsxFastEditor->writeFloat($sheet2, 'D10', -273.15);
61+
62+
assert($xlsxFastEditor->textReplace('/Hello/i', 'World') > 0);
63+
64+
$xlsxFastEditor->save();
65+
66+
$xlsxFastEditor = new XlsxFastEditor(__DIR__ . '/copy.xlsx');
67+
68+
assert($xlsxFastEditor->readFormula($sheet1, 'c2') === '=2*3');
69+
assert($xlsxFastEditor->readString($sheet1, 'B4') === 'α');
70+
assert($xlsxFastEditor->readInt($sheet1, 'C4') === 15);
71+
assert($xlsxFastEditor->readFloat($sheet1, 'D4') === -66.6);
72+
73+
assert($xlsxFastEditor->readFormula($sheet2, 'c2') === '=Sheet1!C2*3');
74+
assert($xlsxFastEditor->readString($sheet2, 'B3') === 'β');
75+
assert($xlsxFastEditor->readInt($sheet2, 'C3') === -7);
76+
assert($xlsxFastEditor->readFloat($sheet2, 'D3') === 273.15);
77+
78+
assert($xlsxFastEditor->readFormula($sheet2, 'I2') === '=7*3');
79+
assert($xlsxFastEditor->readString($sheet2, 'F2') === 'γ');
80+
assert($xlsxFastEditor->readInt($sheet2, 'G3') === -7);
81+
assert($xlsxFastEditor->readFloat($sheet2, 'H4') === 273.15);
82+
83+
assert($xlsxFastEditor->readFormula($sheet2, 'E11') === '=7*5');
84+
assert($xlsxFastEditor->readString($sheet2, 'B10') === 'δ');
85+
assert($xlsxFastEditor->readInt($sheet2, 'C9') === 13);
86+
assert($xlsxFastEditor->readFloat($sheet2, 'D10') === -273.15);
87+
88+
assert($xlsxFastEditor->readString($sheet1, 'B2') === 'World');
89+
90+
$xlsxFastEditor->close();
91+
92+
// Verify by hand that the resulting file opens without warning in Microsoft Excel
93+
// unlink(__DIR__ . '/copy.xlsx');
94+
} catch (XlsxFastEditorException $xlsxe) {
95+
die($xlsxe);
96+
}

0 commit comments

Comments
 (0)