README

PHP package for reading and writing presentation files (.pptx) from a JSON-friendly schema. Framework-agnostic core with an optional Laravel adapter. Designed to round-trip with the @particle-academy/fancy-slides JS package's Deck schema — what the JS editor emits, DarkSlide writes to a real Office Open XML file that opens in PowerPoint, Keynote, Google Slides, and LibreOffice Impress.

Why

Sister project to holy-sheet (XLSX writer). The two share an "agent emits JSON, PHP writes a real document" pattern:

Quickstart

use DarkSlide\Agent;

$deck = [
    'id' => 'demo',
    'title' => 'My deck',
    'theme' => ['name' => 'default'],
    'slides' => [
        [
            'id' => 's1',
            'layout' => 'title',
            'elements' => [
                [
                    'id' => 'e1',
                    'type' => 'text',
                    'x' => 0.1, 'y' => 0.4, 'w' => 0.8, 'h' => 0.2,
                    'content' => 'Welcome to dark-slide',
                    'format' => 'plain',
                    'style' => ['fontSize' => 56, 'weight' => 'bold', 'align' => 'center'],
                ],
            ],
        ],
    ],
];

// Validate before writing — catches malformed agent output
$errors = Agent::validate($deck);
if (!empty($errors)) {
    foreach ($errors as $e) {
        echo "{$e['path']}: expected {$e['expected']}, got {$e['got']}\n";
    }
    exit(1);
}

// Write to disk
$result = Agent::write($deck, '/tmp/my-deck.pptx');
// $result === ['path' => '/tmp/my-deck.pptx', 'bytes' => 18432, 'slides' => 1]

// Or get the bytes in memory (no temp file)
$bytes = Agent::toBytes($deck);

Laravel

use DarkSlide\Laravel\Facades\DarkSlide;

DarkSlide::write($deck, storage_path('app/decks/demo.pptx'));

return response(DarkSlide::toBytes($deck), 200, [
    'Content-Type' => 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    'Content-Disposition' => 'attachment; filename="demo.pptx"',
]);

Schema

Mirrors @particle-academy/fancy-slides's Deck shape exactly. Coordinates are 0..1 fractions; DarkSlide converts to PPTX EMU (914,400 per inch) on write.

See docs/schema.md for the full reference.

Element coverage (v0.5)

What's new in v0.5

• Element entrance animations. Add animation: { effect, trigger?, direction?, duration?, delay?, order? } to any element (effect: fade / fly-in / zoom / wipe). Slides with animations emit a real <p:timing> tree: builds are sorted by (order, index) and grouped into click steps (on-click opens a step; with-prev / after-prev attach to it), mirroring fancy-slides' build sequencer. Each build targets its shape by the exact <p:cNvPr id> it was emitted with; animated shapes start hidden and reveal when their build fires. Elements without animation are unaffected.

What's new in v0.4

• Slide transitions. Add transition: { kind, duration?, direction? } to a slide (fade / slide / zoom), or a deck-wide theme.defaultTransition.
• Image fit + crop. fit is honoured (fill / cover centre-crop / contain & scale-down letterbox) and an explicit crop: {x,y,w,h} maps to <a:srcRect>. Opt-in remote fetch via Agent::write($deck, $path, ['allowHttpImages' => true]) (off by default).
• Native charts. chart elements emit real ppt/charts/chartN.xml parts (no embedded workbook — literal caches) translated from an Apache ECharts-style option. Unsupported options fall back to a pre-rendered image or a titled placeholder.
• Theme + layouts. theme.colors / theme.fonts map into the pptx clrScheme + fontScheme, and all 8 layouts ship as real slideLayoutN.xml parts so PowerPoint recognises each slide's layout role.

What's new in v0.3

• Markdown headings. # / ## / ### paragraph prefixes in format: "markdown" text elements emit larger bold runs in the pptx.
• Syntax-highlighted code blocks. The code element now ships one <a:r> per token, colored by kind (keyword / string / comment / number / builtin / punctuation). Pure-PHP tokenizer, zero third-party deps. Languages: javascript, typescript, jsx, tsx, php, json, bash, css, python, html.
• Reader fidelity for v0.2 features. Tables, gradients, embedded images, and inline bold/italic/code spans now round-trip back to the Deck schema.

Agent tool-use surface

Agent::validateAndRepair($schema) returns ['ok' => bool, 'schema' => array, 'errors' => list] — wire it into your LLM tool to give the agent structured feedback on its emitted decks. Mirrors holy-sheet's pattern.

License

MIT