Pro edição

Legal — Referência Profunda

Visão geral

Gera carimbos de numeração Bates sequencial como fragmentos de fluxo de conteúdo PDF por página.
Três tipos públicos: BatesNumberConfig (configuração imutável), BatesNumberer (motor), BatesPosition (enum de posição de seis casos).
Cada fragmento é autocontido. O estado gráfico é salvo e restaurado, de modo que anexá-lo nunca perturba o conteúdo existente da página.
A saída é determinística: um fragmento é uma função pura da configuração, do texto do carimbo e do tamanho da página.
O módulo não lança exceções. Entradas fora do intervalo degradam conforme as regras de fallback documentadas.

Disponibilidade e licenciamento

Este recurso é distribuído no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes do recurso. Compare edições e obtenha uma licença.

Não existe sinalizador de licença por recurso. Este é um recurso da edição Pro.

composer require nextpdf/pro:^3

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
`BatesNumberConfig::__construct`	`string $prefix = ''`, `string $suffix = ''`, `int $startNumber = 1`, `int $padding = 5`, `BatesPosition $position = BatesPosition::BottomRight`, `float $fontSize = 9.0`, `string $fontFamily = 'Courier'`, `float $opacity = 1.0`, `bool $useLayer = true`, `string $layerName = 'Bates Numbers'`, `float $inset = 15.0`	Configuração imutável de aparência e numeração	`BatesNumberConfig`	—	Todas as onze propriedades são públicas e readonly.
`BatesNumberConfig::formatNumber`	`int $pageIndex` (base 0)	`prefix` + preenchido com zeros (`startNumber + pageIndex`) + `suffix`	`string`	—	Um número mais largo que `padding` não é truncado.
`BatesNumberConfig::getRange`	`int $pageCount`	Primeiro e último carimbos formatados da execução	`array{first: string, last: string}`	—	Assume `pageCount >= 1`; uma contagem de 0 formata o índice de página -1.
`BatesNumberer::__construct`	`BatesNumberConfig $config`	Vincula a configuração	`BatesNumberer`	—	A classe é final e readonly.
`BatesNumberer::generate`	`int $pageCount`, `array $pageSizes`, `string $prefix = ''`, `int $startFrom = 1`	Caminho rápido estático com aparência padrão	`list<string>`	—	Sufixo, posição, fonte, opacidade e camada permanecem em seus padrões.
`BatesNumberer::generateStreams`	`int $pageCount`, `list<array{width: float, height: float}> $pageSizes`	Um fragmento autocontido por página	`list<string>`	Nunca lança; uma entrada de tamanho ausente recorre a A4 retrato	A contagem de fragmentos é igual a `pageCount`; entradas de tamanho extras são ignoradas.
`BatesNumberer::buildPageStream`	`string $text`, `float $pageWidth`, `float $pageHeight`	Constrói o fragmento de carimbo de uma página	`string`	—	Envolvido por `q`/`Q`; texto do carimbo escapado para a sintaxe de string literal.
`BatesNumberer::getConfig`	—	Retorna a configuração vinculada	`BatesNumberConfig`	—	—
`BatesPosition`	casos de enum `BottomLeft`, `BottomCenter`, `BottomRight`, `TopLeft`, `TopCenter`, `TopRight`	Vocabulário de posição baseado em string	—	—	Os valores de apoio são kebab-case (por exemplo `bottom-right`).
`BatesPosition::coordinates`	`float $pageWidth`, `float $pageHeight`, `float $textWidth`, `float $inset = 15.0`	X/Y para a linha de base do carimbo no espaço nativo do PDF	`array{x: float, y: float}`	—	A origem é o canto inferior esquerdo; as linhas superiores posicionam a linha de base a `inset` da borda superior.

Assinaturas dos pontos de entrada

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

Contrato de comportamento

Numeração

BatesNumberConfig::formatNumber calcula startNumber + pageIndex, preenche o número à esquerda com zeros até padding dígitos e o envolve com prefix e suffix. getRange retorna o primeiro e o último carimbos formatados para uma contagem de páginas. Use-o para encadear a numeração de continuação entre produções.

Anatomia do fragmento

Cada fragmento é, em ordem: um salvamento do estado gráfico (q), um operador de cor de preenchimento, um início opcional de conteúdo marcado, um bloco de texto que posiciona e exibe o carimbo, um fim opcional de conteúdo marcado e uma restauração (Q). As coordenadas e o tamanho da fonte são serializados com seis casas decimais, de modo que entradas idênticas produzem bytes idênticos. O texto do carimbo escapa \, ( e ) antes de entrar na string literal.

Vínculo de fonte

O bloco de texto seleciona o nome de recurso de fonte fixo /BatesFont. O dicionário de recursos da página incorporadora deve mapear esse nome para uma fonte correspondente ao fontFamily configurado, e a família deve ser resolvida no registro de fontes. A geração do fragmento em si nunca consulta o registro.

Posicionamento

BatesPosition::coordinates calcula a linha de base do carimbo no espaço nativo do PDF; a origem é o canto inferior esquerdo. O posicionamento ao centro e à direita subtrai uma largura de texto estimada: o comprimento em bytes vezes 0.6 vezes o tamanho da fonte, uma aproximação monoespaçada. Fontes proporcionais e texto multibyte deslocam essa estimativa. O posicionamento à esquerda não depende dela.

Camadas

Com useLayer habilitado (o padrão), o fragmento delimita o texto entre os operadores de conteúdo marcado BDC e EMC. O nome do conteúdo marcado tem a forma /Lyr_<name>, derivado de layerName com os caracteres não pertencentes a palavras substituídos por sublinhados. A delimitação é apenas em nível de fragmento: registrar o grupo de conteúdo opcional correspondente no documento — o passo que torna a camada alternável em um visualizador — cabe ao escritor incorporador.

Opacidade

Uma opacity abaixo de 1.0 é emitida como um preenchimento em tons de cinza mais claro. Um carimbo totalmente opaco é renderizado em preto.

Escopo

O motor aplica a numeração Bates exatamente como configurada. Ele não afirma que um documento numerado seja admissível em juízo ou juridicamente válido. O esquema de numeração, a retenção e o tratamento probatório permanecem sob responsabilidade do cliente; consulte suas equipes jurídica e de conformidade quanto à suficiência processual.

Casos extremos e modos de falha

generateStreams nunca lança em uma incompatibilidade de pageSizes. Uma entrada ausente recorre a A4 retrato, 595.276 por 841.890 pontos; entradas extras são ignoradas.
A contagem de fragmentos sempre é igual a pageCount.
Um número mais largo que padding não é truncado; o texto do carimbo simplesmente cresce.
getRange assume pageCount >= 1. Uma contagem de 0 formata o índice de página -1, isto é, startNumber - 1.
A opacidade é um clareamento em tons de cinza, não transparência ExtGState; o conteúdo sobreposto sob o carimbo não é mesclado.
Bytes do carimbo além de \, ( e ) passam sem codificação. A correção da codificação para texto não-ASCII depende da fonte vinculada.
As marcas Bates são conteúdo de sobreposição. Elas não redigem, removem nem criptografam nada na página.
O módulo não realiza operações criptográficas; o modo FIPS não altera seu comportamento.

Conformidade

Comportamento	Referência	Status
Delimitação de camada via operadores de conteúdo marcado `BDC`/`EMC`	ISO 32000-2:2020 §8.11.3.2	Parcial — o fragmento emite a delimitação; o registro do grupo de conteúdo opcional é o passo do escritor incorporador

Estas linhas registram a especificação com base na qual o módulo é construído, não uma certificação; o NextPDF não possui certificação de conformidade. A tabela também não é uma declaração de validade jurídica ou de suficiência probatória.

Notas de desenvolvimento

Fragmentos são valores de string puros. Teste-os por comparação direta de bytes; nenhum contexto de documento é necessário.
buildPageStream é público e testável em unidade de forma isolada: passe texto pré-formatado e dimensões de página explícitas.
Para numeração de continuação entre produções, inicialize startNumber a partir da execução anterior e registre a saída de getRange no seu log de produção.
Os nomes de camada são sanitizados para caracteres de palavra. Prefira nomes de camada ASCII para que o nome do conteúdo marcado permaneça legível em ferramentas de inspeção.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora de escopo.