<?php

declare(strict_types=1);

namespace Mezzio\Template;

/**
 * Interface defining required template capabilities.
 */
interface TemplateRendererInterface
{
    /**
     * @const string Value indicating all templates; used with `addDefaultParam()`.
     */
    public const TEMPLATE_ALL = '*';

    /**
     * Render a template, optionally with parameters.
     *
     * Implementations MUST support the `namespace::template` naming convention,
     * and allow omitting the filename extension.
     *
     * @param non-empty-string $name
     * @param array<non-empty-string, mixed>|object $params
     */
    public function render(string $name, array|object $params = []): string;

    /**
     * Add a default parameter to use with a template.
     *
     * Use this method to provide a default parameter to use when a template is
     * rendered. The parameter may be overridden by providing it when calling
     * `render()`, or by calling this method again with a null value.
     *
     * The parameter will be specific to the template name provided. To make
     * the parameter available to any template, pass the TEMPLATE_ALL constant
     * for the template name.
     *
     * If the default parameter existed previously, subsequent invocations with
     * the same template name and parameter name will overwrite.
     *
     * @param non-empty-string $templateName Name of template to which the param applies;
     *     use TEMPLATE_ALL to apply to all templates.
     * @param non-empty-string $param Param name.
     */
    public function addDefaultParam(string $templateName, string $param, mixed $value): void;
}