README

Standalone spreadsheet writing tool for agentic document creation.

PHP 8.2+ library for writing valid xlsx files from a JSON-shaped schema. Zero framework dependencies in the core (just ext-zip). An optional Laravel adapter — service provider, facade, artisan command — sits in HolySheet\Laravel\* and only loads when used. No HTTP routes, no controllers, no opinions about how your app exposes the writer; that's your pipeline's job.

Framework-agnostic by design

The package ships no HTTP endpoints. If you need an "Export to xlsx" route, you write the controller — Holy Sheet gives you the writer + facade.

Installation

composer require particle-academy/holy-sheet

Laravel apps auto-discover the optional adapter. Non-Laravel projects use HolySheet\Agent::* directly.

Quick start

Plain PHP (Symfony, Laminas, CLI, anywhere)

use HolySheet\Agent;

Agent::write([
    'sheets' => [[
        'name' => 'Q4 Sales',
        'columns' => [
            ['header' => 'Region', 'type' => 'string'],
            ['header' => 'Revenue', 'type' => 'currency', 'currency' => 'USD'],
            ['header' => 'YoY', 'type' => 'percent', 'decimals' => 1],
        ],
        'rows' => [
            ['North America', 4_820_000, 0.124],
            ['Europe',        3_210_000, 0.081],
            ['APAC',          2_895_000, 0.227],
        ],
        'totals' => ['Revenue' => 'sum', 'YoY' => 'avg'],
        'theme' => 'default',
    ]],
], '/tmp/q4.xlsx');

Laravel (via the facade)

use HolySheet\Laravel\Facades\HolySheet;

HolySheet::write($schema, $path);   // write to disk
$bytes = HolySheet::toBytes($schema); // raw bytes for streaming/queue jobs
$errors = HolySheet::validate($schema); // dry-run, returns structured errors
$tool = HolySheet::toolDefinition();  // JSON Schema for agent tool wiring

Why this exists

Existing PHP spreadsheet libraries are either:

• Heavy and slow (PhpSpreadsheet pulls dozens of transitive deps), or
• Tightly coupled to a single output format

Agentic flows need something different: a small, deterministic API where an LLM can describe the sheet as data (rows, columns, types, formats) and the package writes the file in one pass — no per-cell ceremony, no global state, no surprise dependencies.

Features

• ✅ Multi-sheet workbooks, inline strings, scalar types, formulas with optional cached values
• ✅ Full styling — bold/italic, text alignment, font color/size, fills, borders
• ✅ Number formats — currency (USD/EUR/GBP/JPY/CNY/INR/AUD/CAD/CHF/KRW + ISO fallback), percent, date, datetime, integer, decimals
• ✅ Date conversion — ISO strings + DateTimeInterface → Excel serial numbers
• ✅ Themes — default, business, minimal, plain
• ✅ Symbolic totals — 'totals' => ['Revenue' => 'sum'] → SUM/AVG/COUNT/MIN/MAX formulas
• ✅ Merged cells, column widths (px), frozen rows/cols
• ✅ Comments with author + color
• ✅ Cross-sheet formula references (Sheet2!A1)
• ✅ Style deduplication — every unique format becomes one record
• ✅ Zero third-party runtime dependencies (uses PHP's built-in ZipArchive)
• ✅ Structured validation errors with path, expected, got, value, hint
• ✅ Read path (1.1+) — Agent::describe(path) round-trips an existing xlsx back to a Holy Sheet schema with full feature parity
• ✅ Schema repair (1.1+) — Agent::validateAndRepair($schema) applies conservative auto-fixes (singular sheet → sheets, stringified numerics, object-as-list, etc.)
• ✅ Schema builders (1.1+) — Agent::fromArray(), Agent::fromCsv(), HolySheet::fromQuery() (Laravel) — typed schemas from rows / CSV / Eloquent with no hand-crafting
• ✅ Formula linter (1.2+) — Agent::lint($schema) evaluates every formula and reports #VALUE! / #REF! / #DIV/0! / #NAME? / #CIRC! errors. Catches the LLM-classic header-row off-by-one (B1*12 when B1 is "Annual" and B2 is the data) with a "Did you mean B2?" hint
• ✅ =-formula promotion (1.3+) — a bare string cell beginning with = (e.g. '=A2+B2', '=SUM(B2:B10)') is stored as a real formula, not literal text. Use the object form {'value': '=text'} for a genuine leading-= string
• ✅ dumpJson() (1.3+) — Agent::dumpJson($schema, ?DumpOptions) serializes a schema to JSON (values + formulas). The read-tool counterpart to describe(): describe gives shape, dumpJson gives content. Compaction + a byte ceiling keep agent token cost bounded
• ✅ Agent toolkit (1.3+) — HolySheet\Toolkit\Toolkit ships the canonical Build / Write / Read / Lint / Describe tools as framework-agnostic descriptors (name + description + JSON-Schema parameters + callable handler) plus a shipped agent prompt. Map them onto any SDK in a few lines (see Agent toolkit)

Agent toolkit

Every team building a spreadsheet agent on Holy Sheet hand-writes the same Build / Write / Read / Lint tools and the same validate → lint → repair loop. That layer is shipped — framework-agnostic, zero coupling:

use HolySheet\Toolkit\Toolkit;
use HolySheet\Toolkit\ArraySchemaStore;

$kit = Toolkit::for(new ArraySchemaStore());        // or your own SchemaStore
$system = Toolkit::instructions();                  // the shipped agent prompt

foreach ($kit->tools() as $tool) {
    // $tool->name, $tool->description, $tool->parameters (JSON Schema), $tool->handler
    $sdk->registerTool($tool->name, $tool->description, $tool->parameters, $tool->handler);
}

The host provides three things by implementing SchemaStore (getSchema(), setSchema(), getId()) — where the workbook lives, the agent loop, and the UI. The toolkit provides the tools, the prompts, and the self-correcting write behavior (write_xlsx validates → lints → and only persists when clean; on error it returns the issues so the agent fixes and retries).

Recipe: laravel/ai

laravel/ai consumes the same four fields. Wrap each descriptor in a Tool — no extra package required:

use Laravel\Ai\Tools\Tool;
use HolySheet\Toolkit\Toolkit;

$descriptors = Toolkit::for($store)->byName();

$tools = array_map(
    fn ($d) => Tool::make($d->name)
        ->description($d->description)
        ->schema($d->parameters)
        ->using(fn (array $args) => $d->call($args)),
    $descriptors,
);

return $agent->withInstructions(Toolkit::instructions())->withTools($tools)->stream($prompt);

Compatibility

Documentation

Run the demo

php examples/sales-report.php /tmp/sales.xlsx

Writes a 3-sheet workbook (Sales / Notes / Status) demonstrating every feature — currency + percent + date columns, totals row, frozen header, merged title cell, comment, custom theme. See examples/README.md for the full walkthrough.

Three entry points, one schema

Need an HTTP route? Build your own controller around the facade — Holy Sheet doesn't ship one. See docs/LaravelAdapter.md for the recommended shape.

License

MIT

⭐ Star Fancy UI

If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!