` at Thermal_Bounds::SIZE_MULTIPLIER_MIN),
* so it only applies to a hand-built AST asking for a fractional size.
*/
private const MIN_SIZE_EM = 0.5;
/**
* Printer dot budgets for image sizing: wide (80mm, ≥40 columns) printers
* are 576 dots across, narrow (58mm) 384. The client preview carries the same
* two numbers as DOT_BUDGET_WIDE / DOT_BUDGET_NARROW in
* packages/thermal-utils/src/generate-barcode-svg.ts, and inline in
* dotsToCh() in packages/thermal-utils/src/thermal-renderer.ts. All three
* must agree or PDF/preview parity silently drifts.
*/
private const DOT_BUDGET_WIDE = 576;
/**
* Narrow-roll printer dot budget (see DOT_BUDGET_WIDE sync note).
*/
private const DOT_BUDGET_NARROW = 384;
/**
* Column count at/above which the wide dot budget applies.
*/
private const NARROW_PAPER_THRESHOLD_CHARS = 40;
/**
* Wrapper side padding in px. Mirrors the `padding: 16px 12px` on the receipt
* wrapper that renderThermalPreview() emits in
* packages/thermal-utils/src/thermal-renderer.ts; in the PDF path
* Pdf_Layout_Preprocessor lifts this padding into the @page margins.
*/
private const PADDING_X_PX = 12.0;
/**
* Wrapper top/bottom padding in px (see PADDING_X_PX).
*/
private const PADDING_Y_PX = 16.0;
/**
* Render an HTML receipt string from a thermal AST.
*
* @param array $ast The thermal AST root (a receipt node).
* @param array $opts Optional: 'paper_width_px' — the PDF paper width in CSS
* px; the base font is scaled so the template's character
* grid fills the printable width like a real roll printer.
*
* @return string The receipt HTML.
*/
public function emit( array $ast, array $opts = array() ): string {
$width_chars = $this->clamp_integer( isset( $ast['paper_width'] ) ? $ast['paper_width'] : null, 48, Thermal_Bounds::PAPER_WIDTH_PDF_MIN, Thermal_Bounds::PAPER_WIDTH_MAX );
// 13px matches the JS preview renderer's base font; with a known paper
// width the font scales so the grid fills the printable width instead.
$font_px = 13.0;
if ( isset( $opts['paper_width_px'] ) && is_numeric( $opts['paper_width_px'] ) ) {
$inner_px = (float) $opts['paper_width_px'] - 2 * self::PADDING_X_PX;
if ( $inner_px > 50 ) {
// Clamp to a legible range so a malformed paper/column combination
// cannot produce microscopic or oversized receipt text.
$font_px = max( 6.0, min( 14.0, $inner_px / ( $width_chars * self::CHAR_WIDTH_EM ) ) );
}
}
$children = isset( $ast['children'] ) && \is_array( $ast['children'] ) ? $ast['children'] : array();
$inner = $this->render_nodes( $children, $width_chars );
return '' . $inner . '
';
}
/**
* Render a list of AST nodes.
*
* @param array $nodes The AST nodes.
* @param int $width_chars The receipt character width.
*
* @return string The concatenated HTML.
*/
private function render_nodes( array $nodes, int $width_chars ): string {
$html = '';
foreach ( $nodes as $node ) {
if ( \is_array( $node ) ) {
$html .= $this->render_node( $node, $width_chars );
}
}
return $html;
}
/**
* Render a single AST node.
*
* @param array $node The AST node.
* @param int $width_chars The receipt character width.
*
* @return string The HTML fragment.
*/
private function render_node( array $node, int $width_chars ): string {
$type = isset( $node['type'] ) ? $node['type'] : '';
$children = isset( $node['children'] ) && \is_array( $node['children'] ) ? $node['children'] : array();
switch ( $type ) {
case 'raw-text':
return $this->escape_html( isset( $node['value'] ) ? (string) $node['value'] : '' );
case 'text':
return '' . $this->render_nodes( $children, $width_chars ) . '
';
case 'bold':
return '' . $this->render_nodes( $children, $width_chars ) . '';
case 'underline':
return '' . $this->render_nodes( $children, $width_chars ) . '';
case 'invert':
return '' . $this->render_nodes( $children, $width_chars ) . '';
case 'size':
$em = $this->clamp_float( isset( $node['width'] ) ? $node['width'] : null, 1, self::MIN_SIZE_EM, Thermal_Bounds::SIZE_MULTIPLIER_MAX );
return '' . $this->render_nodes( $children, $width_chars ) . '';
case 'align':
$mode = $this->safe_align( isset( $node['mode'] ) ? $node['mode'] : null );
return '' . $this->render_nodes( $children, $width_chars ) . '
';
case 'row':
return $this->render_row( $node, $width_chars );
case 'col':
// Standalone column outside a row: plain aligned block.
return ''
. $this->render_nodes( $children, $width_chars ) . '
';
case 'line':
return $this->render_line( $node );
case 'barcode':
$barcode_type = isset( $node['barcode_type'] ) ? (string) $node['barcode_type'] : 'code128';
$value = isset( $node['value'] ) ? (string) $node['value'] : '';
if ( Barcode_Symbology::is_qr( $barcode_type ) ) {
return $this->render_qrcode( $value, $this->height_to_qr_size( isset( $node['height'] ) ? (int) $node['height'] : 40 ) );
}
return $this->render_barcode( $barcode_type, $value, isset( $node['height'] ) ? (int) $node['height'] : 40 );
case 'qrcode':
$value = isset( $node['value'] ) ? (string) $node['value'] : '';
$size = isset( $node['size'] ) ? (int) $node['size'] : 4;
return $this->render_qrcode( $value, $size );
case 'feed':
$lines = $this->clamp_integer( isset( $node['lines'] ) ? $node['lines'] : null, Thermal_Bounds::FEED_LINES_MIN, Thermal_Bounds::FEED_LINES_MIN, Thermal_Bounds::FEED_LINES_MAX );
return '';
case 'cut':
// The scissors glyph is missing from the monospace core fonts, so
// it gets the bundled DejaVu face (present in every Dompdf install).
return ''
. '✂
';
case 'receipt':
return $this->render_nodes( $children, $width_chars );
case 'image':
return $this->render_image( $node, $width_chars );
case 'drawer':
default:
return '';
}
}
/**
* Render a row as a single-row table of columns.
*
* Dompdf has no flexbox engine and no `ch` unit, so the JS renderer's flex
* rows are expressed as a fixed-layout table: fixed columns get em widths
* (chars × 0.6em) and `*` columns share the remaining width.
*
* Known divergence, not yet reconciled: there is no star-width algebra here.
* `*` columns are emitted as `` without a width and Dompdf distributes
* whatever the fixed columns leave, whereas the preview and the ESC/POS
* emitter floor-divide the remaining characters between star columns and give
* the remainder to the last one. The two agree on ordinary receipts and can
* differ by a character or two on rows with several star columns. Fixing it
* means porting resolve_row_widths() here and verifying the result against a
* real Dompdf render; do that before assuming the layouts match.
*
* @param array $node The row AST node.
* @param int $width_chars The receipt character width.
*
* @return string The HTML fragment.
*/
private function render_row( array $node, int $width_chars ): string {
$cols = isset( $node['children'] ) && \is_array( $node['children'] ) ? $node['children'] : array();
$cells = '';
foreach ( $cols as $col ) {
if ( \is_array( $col ) ) {
$cells .= $this->render_row_cell( $col, $width_chars );
}
}
return '';
}
/**
* Render a single row column as a table cell.
*
* @param array $node The col AST node.
* @param int $width_chars The receipt character width.
*
* @return string The HTML fragment.
*/
private function render_row_cell( array $node, int $width_chars ): string {
$width = isset( $node['width'] ) ? $node['width'] : 12;
$width_style = '';
if ( '*' !== $width ) {
$chars = $this->clamp_integer( $width, 12, Thermal_Bounds::COL_WIDTH_MIN, Thermal_Bounds::COL_WIDTH_MAX );
$width_style = 'width: ' . $this->format_float( $chars * self::CHAR_WIDTH_EM ) . 'em; ';
}
$align = $this->safe_align( isset( $node['align'] ) ? $node['align'] : null );
$children = isset( $node['children'] ) && \is_array( $node['children'] ) ? $node['children'] : array();
return ' | '
. $this->render_nodes( $children, $width_chars ) . ' | ';
}
/**
* Render an image node as a centered ![]()
.
*
* Image widths are authored in printer dots; mirroring the JS renderer they
* scale by the paper's dot budget so the image keeps the same fraction of
* the receipt width (em-based because Dompdf has no `ch` unit). Local
* WordPress URLs (store logos, uploads) are embedded as data URIs by
* Pdf_Renderer before Dompdf sees the HTML; remote URLs render blank because
* remote access stays disabled.
*
* @param array $node The image AST node.
* @param int $width_chars The receipt character width.
*
* @return string The HTML fragment.
*/
private function render_image( array $node, int $width_chars ): string {
$src = trim( isset( $node['src'] ) ? (string) $node['src'] : '' );
if ( '' === $src ) {
return '';
}
$width_dots = $this->clamp_integer( isset( $node['width'] ) ? $node['width'] : null, 200, Thermal_Bounds::IMAGE_WIDTH_DOTS_MIN, Thermal_Bounds::IMAGE_WIDTH_DOTS_MAX );
$dot_budget = $width_chars >= self::NARROW_PAPER_THRESHOLD_CHARS ? self::DOT_BUDGET_WIDE : self::DOT_BUDGET_NARROW;
$width_em = $width_dots * $width_chars / $dot_budget * self::CHAR_WIDTH_EM;
return ''
. '
 . ')
'
. '
';
}
if ( 'dashed' === $style ) {
return '
';
}
if ( 'dotted' === $style ) {
return '
';
}
return '
';
}
/**
* Render a 1D barcode as a centered PNG image, falling back to text on failure.
*
* @param string $barcode_type The barcode symbology string.
* @param string $value The barcode value.
* @param int $height The barcode height in pixels.
*
* @return string The HTML fragment.
*/
private function render_barcode( string $barcode_type, string $value, int $height = 40 ): string {
$text = trim( $value );
if ( '' === $text ) {
return '';
}
$img = Barcode_Image::barcode_img( $barcode_type, $text, $height );
return '' !== $img
? '' . $img . '
'
: $this->render_barcode_fallback( $text );
}
/**
* Render a QR code as a centered PNG image, falling back to text on failure.
*
* @param string $value The QR code value.
* @param int $size The QR code module scale (pixels per module).
*
* @return string The HTML fragment.
*/
private function render_qrcode( string $value, int $size ): string {
$text = trim( $value );
if ( '' === $text ) {
return '';
}
$img = Barcode_Image::qrcode_img( $text, $size );
return '' !== $img
? '' . $img . '
'
: $this->render_barcode_fallback( $text );
}
/**
* Render the escaped value as monospace fallback text.
*
* @param string $text The value to render.
*
* @return string The HTML fragment.
*/
private function render_barcode_fallback( string $text ): string {
return '' . $this->escape_html( $text ) . '
';
}
/**
* Convert a barcode height into a QR code size.
*
* A QR written as `` carries a pixel height
* where a QR wants a module scale, so the height is folded into the scale the
* `` element would have used. Mirrored by heightToQrSize()
* in packages/thermal-utils/src/thermal-renderer.ts; the two must agree or a
* QR previews at a different size than it prints.
*
* @param int $height The barcode height.
*
* @return int The QR code size clamped between 2 and 8, or 4 by default.
*/
private function height_to_qr_size( int $height ): int {
if ( $height <= 0 ) {
return 4;
}
$size = (int) round( $height / 10 );
return max( 2, min( 8, $size ) );
}
/**
* Clamp a value into an integer range, falling back when it is not numeric.
*
* Out-of-range values are clamped to the nearest bound, never replaced by
* the fallback: a template asking for a 5000-dot logo on a 576-dot roll
* should render as wide as the roll allows, not silently snap back to the
* 200-dot default with no signal. The fallback covers only missing and
* non-numeric values. Fractions truncate toward zero.
*
* Counterpart to safeInteger() in
* packages/thermal-utils/src/thermal-renderer.ts, which clamps the same way.
* The preview has no safeFloat: it applies each bound inline at the node it
* renders, so the bounds passed here must match the ones written there.
*
* @param mixed $value The candidate value.
* @param int $fallback The fallback for missing/non-numeric values.
* @param int $min The minimum allowed value.
* @param int $max The maximum allowed value.
*
* @return int The clamped integer.
*/
private function clamp_integer( $value, int $fallback, int $min, int $max ): int {
if ( ! is_numeric( $value ) ) {
return $fallback;
}
return max( $min, min( $max, (int) $value ) );
}
/**
* Clamp a value into a float range, falling back when it is not numeric.
*
* PHP-only: the preview renderer has no safeFloat helper, it inlines the
* equivalent clamp where it writes the CSS. See clamp_integer() above for
* why out-of-range clamps instead of falling back.
*
* @param mixed $value The candidate value.
* @param float $fallback The fallback for missing/non-numeric values.
* @param float $min The minimum allowed value.
* @param float $max The maximum allowed value.
*
* @return float The clamped float.
*/
private function clamp_float( $value, float $fallback, float $min, float $max ): float {
if ( ! is_numeric( $value ) ) {
return $fallback;
}
return max( $min, min( $max, (float) $value ) );
}
/**
* Format a float for CSS output, trimming a trailing ".0".
*
* @param float $value The value to format.
*
* @return string The formatted value.
*/
private function format_float( float $value ): string {
$formatted = rtrim( rtrim( sprintf( '%.2f', $value ), '0' ), '.' );
return '' === $formatted ? '0' : $formatted;
}
/**
* Resolve an alignment value to a valid CSS text-align keyword.
*
* @param mixed $value The candidate value.
*
* @return string One of left, center, or right.
*/
private function safe_align( $value ): string {
if ( 'center' === $value || 'right' === $value || 'left' === $value ) {
return $value;
}
return 'left';
}
/**
* HTML-escape a string for safe embedding.
*
* @param string $value The input text.
*
* @return string The escaped text.
*/
private function escape_html( string $value ): string {
return htmlspecialchars( $value, ENT_QUOTES, 'UTF-8' );
}
}