Skip to content

feat: declare the page read nullable through the whole seam - #13

Merged
tyrsson merged 6 commits into
1.0.xfrom
tyrsson-render-05-no-page
Nov 13, 2026
Merged

tyrsson merged 6 commits into
1.0.xfrom
tyrsson-render-05-no-page

Conversation

@tyrsson

@tyrsson tyrsson commented Nov 13, 2026

Copy link
Copy Markdown
Member

Scope

Phase 5 of specs/001-document-view-render/tasks.md: T031 to T033, User Story 3. A render performed outside a build completes, and no page is required anywhere.

Tasks

Task Change
T031 src/View/DocumentViewRenderer.php: the page read is explicitly nullable
T032 test/unit/DocumentViewRendererTest.php: absent, explicitly null and not-a-page entries
T033 test/integration/DocumentViewRenderingTest.php: a render with an empty PageContext

What changed

render() now delegates the page read to a private pageFor(Document $document): ?Page. That method reads commondoc.page with a null default and narrows the result with instanceof Page, so the accepted type is declared and proved by static analysis rather than asserted in a local annotation. A document whose entry is missing, explicitly null, or not a page all reach the body template as page: null.

The page variable is supplied on every render. No branch throws or short-circuits when it is null, so a preview render and a build render travel the same path.

Gates

  • mago format: applied, --check clean
  • mago lint: no issues
  • mago analyze: no issues, no new baseline entries
  • mago guard: no issues
  • PHPUnit: 101 tests, 182 assertions, all passing

tyrsson and others added 2 commits November 12, 2026 19:23
…straint

The document view seam imports Mezzio\Template\TemplateRendererInterface directly, so the package that provides it becomes a direct requirement instead of an accident of webware-theme's tree. The php constraint now covers 8.6 while config.platform.php stays pinned at 8.4.99.

Baseline gates recorded before any code change: mago format --check, lint, analyze and guard exit zero, 43 unit tests and 8 integration tests pass.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Joey Smith <jsmith@webinertia.net>
Page implements Laminas\View\Model\ModelInterface for the state a template
reads, never for a position in the render tree: it is final readonly and every
mutator throws, because LaminasViewRenderer writes to the model it renders and
walks children through beforeRender().

PageContext holds the current page for one conversion. PageContextListener
copies it into the document data under commondoc.page on
DocumentPreRenderEvent, so the renderer reads the page from the document it
belongs to and a document built outside a build simply has no entry.

Both factories are registered in ConfigProvider, and the aliases docblock now
says interface-string because its only key is an interface.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Joey Smith <jsmith@webinertia.net>
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

tyrsson and others added 4 commits November 12, 2026 19:45
Page implements ModelInterface and returns an ArrayIterator, so the
IteratorAggregate import was never referenced. Mago reports it as
no-redundant-use on both supported PHP versions, which fails the lint gate
and skips the suites behind it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add DocumentViewRenderer, registered for the document node at priority 10, so a
converted document is rendered as a view instead of as finished HTML. The body
comes from the injected child renderer and is handed to the template renderer
once, which keeps the layout wrap, the view helpers and the helper state reset
with the framework.

- src/View/DocumentViewRenderer.php, src/Container/DocumentViewRendererFactory.php
- templates/commondoc/layout.phtml as the shell, templates/commondoc/document.phtml
  rewritten as the body template reading documentBody and the optional page
- ConfigProvider: templates.map for commondoc::document and commondoc::layout,
  templates.layout, renderer factory entry, middleware pipeline entry removed
- EnvironmentFactory: renderer at priority 10 and the page context listener on
  the pre-render event
- LayoutWrappingMiddleware, its factory and both tests deleted (owner approved)
- config/autoload/commonmark.global.php: external_link.noFollow was 'none',
  which the CommonMark extension rejects; it is now '' (apply to none)

Tests cover T015 to T027: renderer and factory units, layout and body templates,
the provider wiring, the environment factory registrations and a real container
render asserting the site override, the packaged body with the layout wrap and
the template-not-found failure.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
User story 2 is a property of the seam, so these cases exist to fail if a future
refactor reintroduces HTML post-processing.

- DocumentViewRendererTest: the child renderer is asked once, for exactly the
  document's children; the body reaches the template byte for byte; an empty
  child result still produces a rendered document
- DocumentViewRenderingTest: a body template calling a stateful Laminas helper
  renders that helper's markup inside the body; a table, contributed by the
  installed table extension, reaches the output; the converter is the library's
  own MarkdownConverter and the library's document renderer still sits behind
  the view renderer at the lower priority

Covers T028, T029 and T030.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
A render outside a build has no page, so the null case is now a declared
outcome rather than an assumption.

- DocumentViewRenderer::pageFor returns Page|null, reads commondoc.page with a
  null default and narrows the result, so a document whose entry is absent, null
  or not a page all render the same way
- the page variable is supplied on every render, with no branch that throws or
  short-circuits when it is null
- unit cases for the absent, explicitly null and not-a-page entries
- an integration case that converts with an empty PageContext and asserts a full
  document, body plus layout, with an empty title region

Covers T031, T032 and T033.

Signed-off-by: Joey Smith <jsmith@webinertia.net>
@tyrsson
tyrsson force-pushed the tyrsson-render-05-no-page branch from 8315b6d to d8b9e76 Compare November 13, 2026 01:46
@tyrsson
tyrsson merged commit de4c330 into 1.0.x Nov 13, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant