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