# ColumnarDataTablePHP

**Repository Path**: imflyou/columnar-data-table-php

## Basic Information

- **Project Name**: ColumnarDataTablePHP
- **Description**: PHP 轻量级、内存高效的列式存储数据表。基于列式存储优化内存占用，支持行遍历、JSON 序列化及常见数据操作。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ColumnarDataTable

[![PHP Version Require](https://img.shields.io/badge/php-%3E%3D8.0-8892BF.svg)](https://www.php.net/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

轻量级、内存高效的 PHP 列式存储数据表，专为多字段、大数据量场景优化内存占用，相比传统行式数组（`array<array>`）大幅降低内存开销，同时支持常用数据操作与标准接口兼容。

## 核心特性

- 🚀 列式存储：避免行式数组冗余内存消耗，字段越多、空值越多，内存优势越明显
- 📋 严格校验：初始化时校验字段非空、无重复、类型合规，保障数据合法性
- 🔄 便捷操作：支持单行/批量添加、分页获取、行遍历、数据清空等核心功能
- 🎯 接口兼容：实现 `IteratorAggregate` 和 `JsonSerializable`，支持 `foreach` 遍历与 `json_encode` 序列化
- 🚨 健壮异常：清晰的错误提示，覆盖字段非法、索引越界等常见异常场景

## 安装

### 前提条件

- PHP 版本 ≥ 8.0
- Composer 包管理工具

### 安装命令

```bash
composer require imflyou/columnar-data-table-php
````

## 核心方法

| **方法签名**                                  | **功能描述**   | **参数说明**                                | **返回值**            | **可能抛出的异常**                                                            |
|-------------------------------------------|------------|-----------------------------------------|--------------------|------------------------------------------------------------------------|
| `addRow(array $row): void`                | 添加单行数据     | `$row` - 行数据数组（键为字段名）                   | 无                  | `InvalidArgumentException` - 传入非数组时                                    |
| `addRows(array $rows): void`              | 批量添加多行数据   | `$rows` - 二维数组，每行结构同 `addRow`           | 无                  | `InvalidArgumentException` - 传入非二维数组时                                  |
| `getRow(int $index): array`               | 获取指定索引的行数据 | `$index` - 行索引（0-based）                 | 该行的键值对数组           | `OutOfRangeException` - 索引越界时                                          |
| `getRows(int $offset, int $limit): array` | 分页获取行数据    | `$offset` - 起始索引；`$limit` - 获取行数（需 > 0） | 分页后的行数据数组          | `InvalidArgumentException` - limit≤0；`OutOfRangeException` - offset 越界 |
| `clear(): void`                           | 清空所有行数据    | 无                                       | 无                  | 无                                                                      |
| `getRowCount(): int`                      | 获取当前总行数    | 无                                       | 总行数（int）           | 无                                                                      |
| `getColumns(): array`                     | 获取字段名列表    | 无                                       | 字段名数组（string []）   | 无                                                                      |
| `getColumnData(): array`                  | 获取原始列式存储数据 | 无                                       | 键为字段名、值为对应字段所有值的数组 | 无                                                                      |

```php
<?php

// 1. 初始化数据表（定义字段列表）
$table = new ColumnarDataTable(['id', 'name', 'age', 'email']);

// 2. 添加单行数据（缺失字段自动填充 null）
$table->addRow([
    'id' => 1,
    'name' => 'Alice',
    'age' => 25,
    'email' => 'alice@example.com'
]);

// 3. 批量添加多行数据（推荐，性能优于循环调用 addRow）
$table->addRows([
    [
        'id' => 2,
        'name' => 'Bob',
        'age' => 30,
        'email' => 'bob@example.com'
    ],
    [
        'id' => 3,
        'name' => 'Charlie',
        'age' => 35
        // email 字段缺失，自动填充 null
    ]
]);

// 4. 遍历所有行（支持 foreach，得益于 IteratorAggregate 接口）
foreach ($table as $row) {
    echo "ID: {$row['id']}, Name: {$row['name']}\n";
}

// 5. JSON 序列化（支持 json_encode，得益于 JsonSerializable 接口）
echo json_encode($table, JSON_PRETTY_PRINT);

// 6. 核心操作示例
echo "总行数：" . $table->getRowCount() . "\n"; // 输出：3
echo "字段列表：" . implode(', ', $table->getColumns()) . "\n"; // 输出：id, name, age, email
print_r($table->getRow(1)); // 获取索引为 1 的行（第二行）
print_r($table->getRows(0, 2)); // 分页：从索引 0 开始，获取 2 行数据

// 7. 清空数据（保留字段定义，可重新添加数据）
$table->clear();
echo "清空后总行数：" . $table->getRowCount() . "\n"; // 输出：0
```