Pro edición

Legal — Referencia detallada

De un vistazo

Genera sellos de números Bates secuenciales como fragmentos de flujo de contenido PDF por página.
Tres tipos públicos: BatesNumberConfig (configuración inmutable), BatesNumberer (motor), BatesPosition (enumeración de posición de seis casos).
Cada fragmento es autónomo. El estado gráfico se guarda y se restaura, de modo que añadir contenido nunca altera el contenido existente de la página.
La salida es determinista: un fragmento es una función pura de la configuración, el texto del sello y el tamaño de página.
El módulo no lanza excepciones. Las entradas fuera de rango degradan según las reglas de reserva documentadas.

Disponibilidad y licencias

Esta funcionalidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la funcionalidad. Comparar ediciones y obtener una licencia.

No existe ningún indicador de licencia por funcionalidad. Se trata de una capacidad de la edición Pro.

composer require nextpdf/pro:^3

Superficie pública de la API

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`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`	Configuración inmutable de apariencia y numeración	`BatesNumberConfig`	—	Las once propiedades son públicas y readonly.
`BatesNumberConfig::formatNumber`	`int $pageIndex` (base 0)	`prefix` + (`startNumber + pageIndex`) con ceros a la izquierda + `suffix`	`string`	—	Un número más ancho que `padding` no se trunca.
`BatesNumberConfig::getRange`	`int $pageCount`	Primer y último sello formateado de la ejecución	`array{first: string, last: string}`	—	Supone `pageCount >= 1`; un recuento de 0 formatea el índice de página -1.
`BatesNumberer::__construct`	`BatesNumberConfig $config`	Vincula la configuración	`BatesNumberer`	—	La clase es final y readonly.
`BatesNumberer::generate`	`int $pageCount`, `array $pageSizes`, `string $prefix = ''`, `int $startFrom = 1`	Ruta rápida estática con apariencia por defecto	`list<string>`	—	El sufijo, la posición, la fuente, la opacidad y la capa permanecen en sus valores por defecto.
`BatesNumberer::generateStreams`	`int $pageCount`, `list<array{width: float, height: float}> $pageSizes`	Un fragmento autónomo por página	`list<string>`	Nunca lanza; una entrada de tamaño ausente recurre a A4 vertical	El número de fragmentos es igual a `pageCount`; las entradas de tamaño adicionales se ignoran.
`BatesNumberer::buildPageStream`	`string $text`, `float $pageWidth`, `float $pageHeight`	Construye el fragmento del sello de una página	`string`	—	Envuelto en `q`/`Q`; el texto del sello se escapa para la sintaxis de cadena literal.
`BatesNumberer::getConfig`	—	Devuelve la configuración vinculada	`BatesNumberConfig`	—	—
`BatesPosition`	casos de enumeración `BottomLeft`, `BottomCenter`, `BottomRight`, `TopLeft`, `TopCenter`, `TopRight`	Vocabulario de posición respaldado por cadenas	—	—	Los valores de respaldo son kebab-case (por ejemplo `bottom-right`).
`BatesPosition::coordinates`	`float $pageWidth`, `float $pageHeight`, `float $textWidth`, `float $inset = 15.0`	X/Y para la línea base del sello en espacio nativo del PDF	`array{x: float, y: float}`	—	El origen es la esquina inferior izquierda; las filas superiores colocan la línea base a `inset` del borde superior.

Firmas de los puntos 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 comportamiento

Numeración

BatesNumberConfig::formatNumber calcula startNumber + pageIndex, rellena el número con ceros a la izquierda hasta padding dígitos y lo envuelve con prefix y suffix. getRange devuelve el primer y el último sello formateado para un recuento de páginas. Se emplea para encadenar la numeración de continuación entre producciones.

Anatomía del fragmento

Cada fragmento es, en orden: una salvaguarda del estado gráfico (q), un operador de color de relleno, un inicio opcional de contenido marcado, un bloque de texto que posiciona y muestra el sello, un fin opcional de contenido marcado y una restauración (Q). Las coordenadas y el tamaño de fuente se serializan con seis decimales, de modo que entradas idénticas producen bytes idénticos. El texto del sello escapa \, ( y ) antes de entrar en la cadena literal.

Vinculación de fuente

El bloque de texto selecciona el nombre de recurso de fuente fijo /BatesFont. El diccionario de recursos de la página incrustadora debe asignar ese nombre a una fuente que coincida con el fontFamily configurado, y la familia debe resolverse en el registro de fuentes. La generación del fragmento en sí nunca consulta el registro.

Colocación

BatesPosition::coordinates calcula la línea base del sello en espacio nativo del PDF; el origen es la esquina inferior izquierda. La colocación centrada y a la derecha resta un ancho de texto estimado: longitud en bytes por 0.6 por el tamaño de fuente, una aproximación monoespaciada. Las fuentes proporcionales y el texto multibyte desplazan esa estimación. La colocación a la izquierda no depende de ella.

Capas

Con useLayer habilitado (el valor por defecto), el fragmento encierra el texto entre los operadores de contenido marcado BDC y EMC. El nombre de contenido marcado tiene la forma /Lyr_<name>, derivado de layerName con los caracteres no alfanuméricos reemplazados por guiones bajos. El encierro es únicamente a nivel de fragmento: registrar el grupo de contenido opcional correspondiente en el documento —el paso que hace que la capa sea conmutable en un visor— corresponde al escritor incrustador.

Opacidad

Una opacity inferior a 1.0 se emite como un relleno en escala de grises más claro. Un sello totalmente opaco se renderiza en negro.

Alcance

El motor aplica la numeración Bates exactamente como se configura. No afirma que un documento numerado sea admisible ante un tribunal ni legalmente válido. El esquema de numeración, la retención y el tratamiento probatorio siguen siendo responsabilidad del cliente; consulte a sus equipos legal y de cumplimiento sobre la suficiencia procesal.

Casos límite y modos de fallo

generateStreams nunca lanza ante un desajuste de pageSizes. Una entrada ausente recurre a A4 vertical, 595.276 por 841.890 puntos; las entradas adicionales se ignoran.
El número de fragmentos siempre es igual a pageCount.
Un número más ancho que padding no se trunca; el texto del sello simplemente crece.
getRange supone pageCount >= 1. Un recuento de 0 formatea el índice de página -1, es decir startNumber - 1.
La opacidad es un aclarado en escala de grises, no transparencia de ExtGState; el contenido solapado bajo el sello no se mezcla.
Los bytes del sello distintos de \, ( y ) pasan sin codificar. La corrección de la codificación para texto no ASCII depende de la fuente vinculada.
Las marcas Bates son contenido superpuesto. No redactan, eliminan ni cifran nada de la página.
El módulo no realiza operaciones criptográficas; el modo FIPS no cambia su comportamiento.

Conformidad

Comportamiento	Referencia	Estado
Encierro de capa mediante los operadores de contenido marcado `BDC`/`EMC`	ISO 32000-2:2020 §8.11.3.2	Parcial — el fragmento emite el encierro; el registro del grupo de contenido opcional es el paso del escritor incrustador

Estas filas registran la especificación con la que se construye el módulo, no una certificación; NextPDF no posee ninguna certificación de conformidad. La tabla tampoco es una declaración de validez legal ni de suficiencia probatoria.

Notas de desarrollo

Los fragmentos son valores de cadena puros. Se prueban por comparación directa de bytes; no se requiere ningún contexto de documento.
buildPageStream es público y comprobable unitariamente de forma aislada: pase texto preformateado y dimensiones de página explícitas.
Para la numeración de continuación entre producciones, siembre startNumber a partir de la ejecución anterior y registre la salida de getRange en su registro de producción.
Los nombres de capa se sanean a caracteres alfanuméricos. Prefiera nombres de capa ASCII para que el nombre de contenido marcado siga siendo legible en las herramientas de inspección.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública soportada de la API. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbooks y los prefijos de tickets quedan fuera de alcance.