README

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

核心特性

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

安装

前提条件

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

安装命令

composer require imflyou/columnar-data-table-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