Quantum

Appearance

View Contracts ​

This page covers the behaviors you can rely on when integrating with the View package.

Layout contract ​

setLayout(?string $layoutFile, array $assets = []): void ​

Use this before render().

Contract:

  • stores the layout file name for later full renders
  • appends any provided assets to the current layout asset list
  • accepts null, which clears the current layout selection while leaving the accumulated asset list available for later full renders

render() reads whatever layout is currently stored. It does not accept a layout argument of its own.

Parameter contract ​

setParam() and setParams() ​

These methods add data into the shared param bag.

Contract:

  • later values overwrite earlier values for the same key
  • render() and renderPartial() both merge their $params argument into the same shared bag
  • params remain available after rendering until flushParams() is called or a key is overwritten
  • getParams() and getParam() return raw values, so RawParam wrappers stay an internal escape-hatch detail

setRawParam() ​

Stores one param as a RawParam wrapper.

Use it only for trusted HTML or content you intentionally do not want escaped.

getParam() and getParams() ​

These methods always return the unwrapped value.

If a param was stored as RawParam, callers receive the original value rather than the wrapper object.

Render contract ​

render(string $viewFile, array $params = []): ?string ​

Contract:

  • requires a layout to be set first
  • renders the page template first, then the layout
  • returns the final layout HTML
  • stores the rendered page body so getContent() can return it afterward
  • registers any assets collected through setLayout() before the layout render begins

Failure behavior:

  • throws ViewException when no layout is set
  • can also surface renderer, asset, config, DI, session, database, or app-level exceptions from its dependencies

renderPartial(string $viewFile, array $params = []): string ​

Contract:

  • does not require a layout
  • returns the requested fragment HTML
  • keeps the existing full-render page body available through getContent()
  • merges the provided params into the shared param bag before rendering

Use it for partials, snippets, or error fragments that should not go through the full page pipeline.

Content contract ​

getContent(): ?string ​

Returns the last body view generated by render(), including after later partial renders.

Failure behavior:

  • throws ViewException if no full render has happened yet

If your code only used renderPartial(), getContent() is still considered unavailable.

Cache contract ​

render() renders body and layout, then writes the final HTML using the current request URI as the cache key when view cache is enabled.

Important boundary:

  • caching happens after both the body and layout are rendered
  • this path does not short-circuit rendering before layout generation
  • only full render() participates
  • no request URI means no cache write/read path