PHPackages                             particle-academy/holy-sheet - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. particle-academy/holy-sheet

ActiveLibrary[PDF & Document Generation](/categories/documents)

particle-academy/holy-sheet
===========================

Standalone spreadsheet writing tool for agentic document creation. Framework-agnostic core with optional Laravel 10-13 integration.

v1.3.0(1mo ago)0477↑30%MITPHPPHP ^8.2CI passing

Since May 5Pushed 1mo agoCompare

[ Source](https://github.com/Particle-Academy/holy-sheet)[ Packagist](https://packagist.org/packages/particle-academy/holy-sheet)[ Docs](https://github.com/Particle-Academy/holy-sheet)[ RSS](/packages/particle-academy-holy-sheet/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (6)Versions (9)Used By (0)

Holy Sheet
==========

[](#holy-sheet)

[![Fancy UI suite](art/fancy-ui.svg)](https://particle.academy)

**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
----------------------------

[](#framework-agnostic-by-design)

LayerWhat it requiresCore (`HolySheet\Agent`, `HolySheet\HolySheet`, validator, writer, schema)PHP 8.2+, `ext-zip`. Nothing else. Works in plain PHP scripts, Symfony, Laminas, Slim, CLI tools.Laravel adapter (`HolySheet\Laravel\*`)Optional. Auto-registered via `extra.laravel.providers` if Laravel is installed; ignored otherwise. Provides facade, service provider, and `php artisan holy-sheet:write` command.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
------------

[](#installation)

```
composer require particle-academy/holy-sheet
```

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

Quick start
-----------

[](#quick-start)

### Plain PHP (Symfony, Laminas, CLI, anywhere)

[](#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)

[](#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
---------------

[](#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
--------

[](#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))

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

[](#recipe-laravelai)

`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
-------------

[](#compatibility)

Versions**PHP**8.2, 8.3, 8.4**Laravel adapter**10.x, 11.x, 12.x, 13.x (optional)**Frameworks**any PHP 8.2+ project — Symfony, Laminas, Slim, plain PHP, CLI**Runtime deps**none beyond `ext-zip`Documentation
-------------

[](#documentation)

TopicDoc**Schema reference** — every field, every type, every option[docs/Schema.md](docs/Schema.md)**Recipes** — 14 end-to-end patterns including round-trip + helper builders[docs/Recipes.md](docs/Recipes.md)**Read path** — `describe()` contract + lossy-fields list[docs/ReadPath.md](docs/ReadPath.md)**Laravel adapter** — facade methods, service provider, artisan command[docs/LaravelAdapter.md](docs/LaravelAdapter.md)**Agent skill** — system prompt for LLM consumption[skills/holy-sheet.md](skills/holy-sheet.md)**JSON Schema** — for tool-use validators[skills/holy-sheet.schema.json](skills/holy-sheet.schema.json)Run the demo
------------

[](#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](examples/README.md) for the full walkthrough.

Three entry points, one schema
------------------------------

[](#three-entry-points-one-schema)

CallerEntry**Plain PHP**`HolySheet\Agent::write($schema, $path)` (static, framework-free)**Laravel facade**`HolySheet\Laravel\Facades\HolySheet::write($schema, $path)`**CLI / agent shell**`php artisan holy-sheet:write --in=schema.json --out=q4.xlsx` (Laravel command)Need an HTTP route? Build your own controller around the facade — Holy Sheet doesn't ship one. See [docs/LaravelAdapter.md](docs/LaravelAdapter.md#http-controller-pattern) for the recommended shape.

License
-------

[](#license)

MIT

---

⭐ Star Fancy UI
---------------

[](#-star-fancy-ui)

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

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance91

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

8

Last Release

47d ago

Major Versions

v0.2.0 → v1.0.02026-05-06

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/461446?v=4)[Wish Born](/maintainers/wishborn)[@wishborn](https://github.com/wishborn)

---

Top Contributors

[![wishborn](https://avatars.githubusercontent.com/u/461446?v=4)](https://github.com/wishborn "wishborn (13 commits)")

---

Tags

aiexcelxlsxcsvspreadsheetagenticdocument-creationparticle-academy

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/particle-academy-holy-sheet/health.svg)

```
[![Health](https://phpackages.com/badges/particle-academy-holy-sheet/health.svg)](https://phpackages.com/packages/particle-academy-holy-sheet)
```

###  Alternatives

[openspout/openspout

PHP Library to read and write spreadsheet files (CSV, XLSX and ODS), in a fast and scalable way

1.2k70.2M254](/packages/openspout-openspout)[nuovo/spreadsheet-reader

Spreadsheet reader library for Excel, OpenOffice and structured text files

668891.8k8](/packages/nuovo-spreadsheet-reader)[dcat/easy-excel

使用简单实用的语义化接口快速读写Excel文件

155390.7k30](/packages/dcat-easy-excel)[avadim/fast-excel-reader

Lightweight and very fast XLSX Excel Spreadsheet and CSV Reader in PHP

107737.8k11](/packages/avadim-fast-excel-reader)[seine/seine

Seine - Write spreadsheets of various formats to a stream

1270.6k](/packages/seine-seine)[lekoala/spread-compat

Easily manipulate PhpSpreadsheet, OpenSpout and League CSV

1223.6k1](/packages/lekoala-spread-compat)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)