README

PHP Excel 助手 - 基于PhpSpreadsheet的简单方式编写和读取电子表格

这个库是一个封装了PhpSpreadsheet (文档) 的助手库，用于简单使用。

概述

演示
安装
要求
使用

限制
- 性能问题

演示

写入 Excel

将 Excel 文件输出到浏览器供下载

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    ->addRow(['ID', 'Name', 'Email'])
    ->addRows([
        ['1', 'Nick','myintaer@gmail.com'],
        ['2', 'Eric','eric@.....'],
    ])
    ->output('My Excel');

从 Excel 读取

导入上述 Excel 文件，并返回包含行>列的二维数组数据电子表格

$data = \yidas\phpSpreadsheet\Helper::newSpreadsheet('/tmp/My Excel.xlsx')
    ->getRows();
    
print_r($data);

输出结果

Array
(
    [0] => Array
        (
            [0] => ID
            [1] => Name
            [2] => Email
        )

    [1] => Array
        (
            [0] => 1
            [1] => Nick
            [2] => myintaer@gmail.com
        )

    [2] => Array
        (
            [0] => 2
            [1] => Eric
            [2] => eric@.....
        )

)

要求

此库需要以下内容

依赖于PhpSpreadsheet
- PHP 5.6.0+
- PHP 扩展 php-zip 启用
- PHP 扩展 php-xml 启用
- PHP 扩展 php-gd2 启用（如果未编译在内）

安装

在您的项目中运行 Composer

composer require yidas/phpspreadsheet-helper

然后，根据您的 PHP 框架加载 Composer 后，您就可以调用它了

require __DIR__ . '/vendor/autoload.php';

\yidas\phpSpreadsheet\Helper::newSpreadsheet();

使用方法

导入 & 导出

简单地读取一个 Excel 文件，然后输出到浏览器

\yidas\phpSpreadsheet\Helper::newSpreadsheet('/tmp/excel.xlsx')
    ->addRow(['Modified A1'])
    ->output();

newSpreadsheet()

创建或加载一个 PhpSpreadsheet 对象

public static array newSpreadsheet(object|string $spreadSheet=null)

output()

将文件输出到浏览器

public static void output(string $filename='excel', string $format='Xlsx')

$format 列表：Xlsx、Xls、Html、Csv、Ods

save()

保存为文件

public static string save(string $filename='excel', string $format='Xlsx')

示例

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    ->addRow(['Add A1'])
    ->save("/tmp/save");
// /tmp/save.xlsx

获取行

getRow()

从 PhpSpreadsheet 的活动工作表中获取行的数据

public static array getRow(boolean $toString=true, array $options=[], callable $callback=null)

示例

use \yidas\phpSpreadsheet\Helper;

$row1 = Helper::newSpreadsheet($filepath)
    ->getRow();

$row2 = Helper::getRow();

print_r($row1);
print_r($row2);

按行获取内容示例（示例代码）

$helper = \yidas\phpSpreadsheet\Helper::newSpreadsheet($filepath);

while ($row = $helper->getRow()) {
    // Each row data process
}

getRows()

从 PhpSpreadsheet 的活动工作表中获取行

public static array getRows(boolean $toString=true, array $options=[], callable $callback=null)

getRows() 示例

添加行

addRow()

向 PhpSpreadsheet 的活动工作表中添加一行

public static self addRow(array $rowData, array $rowAttributes=null)

$rowData 值：一个包含字符串或属性的数组的每个单元格
$rowAttributes 值：字符串或属性的每个单元格的数组的每个行

addRow() 示例

设置每个单元格属性的示例

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    ->addRow([['value'=>'ID'], ['value'=>'Name'], ['value'=>'Email']])
    ->addRow(['ID', 'Name', 'Email']);

设置每行属性的示例

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    // Set width as 25 to all cells of this row
    ->addRow([['value'=>'ID'], ['value'=>'Name'], ['value'=>'Email']], ['width'=>25]);

addRows()

向 PhpSpreadsheet 的活动工作表中添加多行

public static self addRows(array $data, array $rowAttributes=null)

$data 值：来自 addRow() 的每个 $rowData 的数组
$rowAttributes 值：字符串或属性的每个行的数组的每个行

addRows() 示例

属性

属性是一个标准的数组，用于定义单元格或甚至整行，键如下所示

key、value、col、row、skip、width、style

PhpSpreadsheet 原始用法集成

这个助手非常灵活，您可以用它注入或提取原始PhpSpreadsheet，当您需要操作一些与助手集成的PhpSpreadsheet方法时。

注入 PhpSpreadsheet

// Get a new PhpSpreadsheet object
$objSpreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet;
$objSpreadsheet->getProperties()
    ->setCreator("Nick Tsai")
    ->setTitle("Office 2007 XLSX Document");
    
// Get the actived sheet object from PhpSpreadsheet
$objSheet = $objSpreadsheet->setActiveSheetIndex(0);
$objSheet->setTitle('Sheet');
$objSheet->setCellValue('A1', 'SN');

// Inject PhpSpreadsheet Object and Sheet Object to Helper
\yidas\phpSpreadsheet\Helper::newSpreadsheet($objSpreadsheet)
    ->setSheet($objSheet)
    ->setRowOffset(1) // Point to 1nd row from 0
    ->addRows([
        ['1'],
        ['2'],
    ])
    ->output();

提取 PhpSpreadsheet

use \yidas\phpSpreadsheet\Helper;

Helper::newSpreadsheet()
    ->setSheet(0, 'Sheet')
    ->addRow(['SN']);
    
// Get the PhpSpreadsheet object created by Helper
$objSpreadsheet = Helper::getSpreadsheet();
$objSpreadsheet->getProperties()
    ->setCreator("Nick Tsai")
    ->setTitle("Office 2007 XLSX Document");
    
// Get the actived sheet object created by Helper
$objSheet = Helper::getSheet();
$objSheet->setCellValue('A2', '1');
$objSheet->setCellValue('A3', '2');

Helper::output();

合并单元格

通过定义每个单元格的跨距属性，合并单元格非常容易。

row：要合并的跨行单元格数。
col：要合并的跨列单元格数。
skip：要跳过的跨列单元格数。

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    ->addRows([
        [['value'=>'SN', 'row'=>2], ['value'=>'Language', 'col'=>2], ['value'=>'Block', 'row'=>2, 'col'=>2]],
        ['','English','繁體中文',['skip'=>2]],
    ])
    ->addRows([
        ['1', 'Computer','電腦','#15'],
        ['2', 'Phone','手機','#4','#62'],
    ])
    ->output('Merged Excel');

多个工作表

setSheet()

设置活动PhpSpreadsheet工作表。

public static self setSheet($sheet=0, $title=NULL, $normalizeTitle=false)

getSheet()

从缓存中获取PhpSpreadsheet工作表对象。

public static object getSheet($identity=null, $autoCreate=false)

示例

use \yidas\phpSpreadsheet\Helper;

Helper::newSpreadsheet()
    ->setSheet(0, 'First Sheet')
    ->addRow(['Sheet Index', 'Sheet Count'])
    ->addRows([
        [Helper::getActiveSheetIndex(), Helper::getSheetCount()],
    ]);
    
// Set another sheet object without giving index 
Helper::setSheet(null, '2nd Sheet')
    ->addRow(['Sheet Index', 'Sheet Count'])
    ->addRows([
        [Helper::getActiveSheetIndex(), Helper::getSheetCount()],
    ]);
    
// Get a sheet which does not exsit with auto creating it  
$obj = Helper::getSheet('3nd Sheet', true);

// Set a sheet with the title which has been auto-normalized
Helper::setSheet(null, '*This [sheet] name has been auto-nomalizing', true)
    ->addRow(['Sheet Index', 'Sheet Count'])
    ->addRows([
        [Helper::getActiveSheetIndex(), Helper::getSheetCount()],
    ]);

Helper::output('MultiSheets');

getActiveSheetIndex()：获取活动工作表索引。
getSheetCount()：获取工作表数量。

坐标和范围的映射

use \yidas\phpSpreadsheet\Helper;

Helper::newSpreadsheet()
    ->addRows([
        [
            ['value'=>'SN', 'row'=>2, 'key'=>'sn'], 
            ['value'=>'Language', 'col'=>2, 'key'=>'lang'], 
            ['value'=>'Block', 'row'=>2, 'col'=>2, 'key'=>'block'],
        ],
        [   
            '',
            ['value'=>'English', 'key'=>'lang-en'],
            ['value'=>'繁體中文', 'key'=>'lang-zh'],
            ['skip'=>2, 'key'=>'block-skip'],
        ],
    ])
    ->addRows([
        ['1', 'Computer','電腦','#15'],
        ['2', 'Phone','手機','#4','#62'],
    ]);
// ->output('Merged Excel');  

print_r(Helper::getCoordinateMap());
print_r(Helper::getRangeMap());
// print_r(Helper::getColumnMap());
// print_r(Helper::getRowMap());
echo "sn start cell: ". Helper::getCoordinateMap('sn');
echo "\nsn start column: ". Helper::getColumnMap('sn');
echo "\nsn start row: ". Helper::getRowMap('sn');
echo "\nsn range: ". Helper::getRangeMap('sn');
echo "\nAll range: ". Helper::getRangeAll();

结果可以是

Array
(
    [sn] => A1
    [lang] => B1
    [block] => D1
    [lang-en] => B2
    [lang-zh] => C2
    [block-skip] => D2
)
Array
(
    [sn] => A1:A2
    [lang] => B1:C1
    [block] => D1:E2
    [lang-en] => B2:B2
    [lang-zh] => C2:C2
    [block-skip] => D2:E2
)
sn start cell: A1
sn start column: A
sn start row: 1
sn range: A1:A2
All range: A1:E4

样式属性

样式属性可以设置在单个单元格、单个行或甚至单元格范围上。

style：属性指向applyFromArray()进行样式设置。

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    // Each cell with each style attributes
    ->addRow([
        'Percentage', 
        '10%', 
        ['value'=>'content', 'style'=> [
            'font' => [
                'bold' => true,
                'color' => ['argb' => 'FFFF0000']
            ],
            'alignment' => ['horizontal' => 'right'],
            'borders' => [
                'top' => ['borderStyle' => 'thin'],
            ],
            'fill' => [
                'fillType' => 'linear',
                'rotation' => 90,
                'startColor' => ['argb' => 'FFA0A0A0'],
                'endColor' => ['argb' => 'FFFFFFFF'],
            ],
        ]],
        ['value'=>'10000', 'style'=> [
            'numberFormat' => [
                'formatCode' => '#,##0',
            ],
        ]],
    ])
    // Row with thousands separator format style
    ->addRow(['1000', '2000', '3000', '4000'], ['style' => [
        'numberFormat' => [
            // const FORMAT_NUMBER_COMMA_SEPARATED1 = '#,##0.00';
            'formatCode' => \PhpOffice\PhpSpreadsheet\Style\NumberFormat::FORMAT_NUMBER_COMMA_SEPARATED1,
        ],
    ]]) 
    // Row with percentage format style
    ->addRow(['0.1', '0.15', '0.3145', '0.855'], ['style' => [
        'numberFormat' => [
            // const FORMAT_PERCENTAGE_00 = '0.00%';
            'formatCode' => \PhpOffice\PhpSpreadsheet\Style\NumberFormat::FORMAT_PERCENTAGE_00,
        ],
    ]]) 
    ->output();

样式数组键/值/常量引用样式applyFromArray()的有效数组键或源类。

列格式

每个单元格数据的选项。

width：使用setWidth()设置列宽。

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    ->addRow([['value'=>'ID', 'width'=>10], ['value'=>'Name', 'width'=>25], ['value'=>'Email', 'width'=>50]])
    ->addRows([
        ['1', 'Nick','myintaer@gmail.com'],
        ['2', 'Eric','eric@.....'],
    ])
    ->output('My Excel');

所有单元格格式

本节专注于应用工作表上的所有活动单元格或范围单元格，而不仅仅是单个单元格、行或列。

setStyle()

为所有活动单元格设置样式或通过给活动工作表指定范围来设置样式。

public static self setStyle(array $styleArray, string $range=NULL)

示例

\yidas\phpSpreadsheet\Helper::newSpreadsheet()
    ->addRow(['Title', 'Content'])
    ->addRows([
        ['Basic Plan', "*Interface\n*Search Tool"],
        ['Advanced Plan', "*Interface\n*Search Tool\n*Statistics"],
    ])
    ->setWrapText()
    // ->setWrapText('B2')
    ->setAutoSize()
    // ->setAutoSize('B')
    ->setStyle([
        'borders' => [
            'inside' => ['borderStyle' => 'hair'],
            'outline' => ['borderStyle' => 'thin'],
        ],
        'fill' => [
            'fillType' => 'solid',
            'startColor' => ['argb' => 'FFCCCCCC'],
        ],
    ])
    ->output('Formatted Excel');

setWrapText()

为所有活动单元格设置自动换行或通过给活动工作表指定范围来设置自动换行。

public static self setWrapText(string $range=NULL, string $value=true)

setAutoSize()

为所有活动单元格设置自动大小或通过给活动工作表指定列范围来设置自动大小。

public static self setAutoSize(string $colAlphaStart=NULL, string $colAlphaEnd=NULL, boolean $value=true)

限制

性能问题

如果您正在使用XLSX构建大型单元格数据，您可能会遇到内存使用和执行时间方面的性能问题。

box/spout 电子表格库支持以高性能构建Excel文件，如果您不需要更多的样式和格式要求，可以使用此库。

yidas / phpspreadsheet-helper

维护者

详细信息