[fabeat]

A theme that did not come from a directory, and a deck that comes back as bytes.

This branch carries the chrome: → templates-file: rename of #37 as well, so the diff shows both until that pull request merges. Once it does, this one shows only its own commits.

The finder

This half read every file itself, so the only way in was a path. A program that keeps its themes in a database had nowhere to put them. This adds one seam — Files\FileFinder — and every file a deck names comes through it.

interface FileFinder
{
    public function read(string $name, ?string $role = null): ?string;
    public function path(string $name, ?string $role = null): ?string;
    public function themes(): array;
    public function files(string $theme): array;
}

The finder owns where files come from; the library owns what a theme is. The library composes the names and asks; the finder answers. It never needs to know what a theme is, or what the files of one are called.

• read() — the contents. What the library wants for YAML, for Markdown and for a picture.
• path() — a path, for the two things a zip-based reader must open: a theme's template.pptx and a document's template_file:.
• themes() — the themes that resolve, so a failure can name what would have worked.
• files() — the files of a theme, so a null can be told apart from a refusal.

A finder answers; it does not refuse. A file that is not there is null and nothing else. Each half of this suite has its own exceptions, so a finder that refused would throw one half's exception and the other half would not catch it — and the two interfaces would stop being the same, which is the whole reason there is one shape rather than two. What may be read therefore stays with the library, which holds every path a finder answers to its own roots before it reads it.

The interface is identical to the Word half's, and the two DiskFinders are behaviourally identical — the same names, the same roles, the same answers, checked by loading both classes into one process and asking both the same questions. A finder written once serves both.

What a caller can do now

$renderer = new PresentationRenderer(directory: '.', files: $finder);
$renderer->withTheme('corporate');    // outranks the deck's own `theme:`
$bytes = $renderer->toString($deck);  // the deck as bytes

withTheme() resolves a name once. The deck's own theme: is still type-checked — this half refuses a wrong-typed frontmatter value by name, and a caller's theme does not stop that — but the caller's theme answers for the deck.

toString() is the counterpart of toDocx(). The renderer wrote to a path and returned the path; every embedder wrote a temporary file and read it back. It stages now, the way the Word half already did: PHP's ZipArchive cannot write to memory (open('php://temp') returns 9, and open('php://temp', CREATE|OVERWRITE) fails at close() with "Failure to create temporary file"), and PHPPresentation's writer takes a path.

What did not change

The error messages, the shipped themes, the six steps a theme is looked for in, the scope checks, and this half's refusing an unknown directive or frontmatter key by name. The scope check stays in the library, where the messages are — the finder resolves a path, the library holds it to its roots and reads it.

A theme directory that exists but holds no manifest still shadows a later one, and is still reported as a theme without a manifest.

The new refusal

A theme may carry a template.pptx. A source that lists the master and cannot serve it is refused by name, with the new UnservedTemplate:

The theme "house" carries a "template.pptx" that the source of this render cannot serve. A deck drawn without it is drawn in the wrong design with nothing saying so, so it is refused rather than drawn without it.

It is not an InvalidInput: neither the deck's author nor the theme's author can fix it — the program that brought the source can.

The listing (files()) is what tells "this theme has no master" from "this source cannot serve one".

Nothing left on disk

A master or a picture that a source serves as bytes is staged into a file of the library's own, and removed when the render is over — on the failure path as well as the happy one. render() and toString() both release what they staged, in a finally.

The deliberate breaks

ThemeLoader::load() and loadManifest() take a ?FileFinder where they took a ?PathScope; their first parameter is now a theme's name rather than its directory — the signature does not change, the interpretation does. ThemeResolver's loader parameter became nullable. PresentationRenderer::__construct() gained a trailing named files:.

LoadedTheme::template() returns a Master rather than a path, because a path alone cannot say who owns the file — and a staged master is written again when it is asked for, so a renderer can draw twice.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud