Pro edición

Document

De un vistazo

El módulo Document divide un PDF en segmentos por rango de páginas y ensambla PDF Portfolios (Collections) con columnas de esquema ordenables. Ambas operaciones están acotadas frente a entradas hostiles.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho de uso no carga las clases de la capacidad. Document forma parte de la edición Pro, sin ningún indicador de licencia independiente por función. Compare ediciones y obtenga una licencia.

Instalación

composer require nextpdf/pro:^3

El código reside bajo el espacio de nombres NextPDF\Pro\Document.

Descripción conceptual

Se proporcionan dos capacidades:

PdfSplitter extrae rangos de páginas en segmentos PDF autónomos. Detecta las páginas escaneando en busca de objetos de página en la entrada en bruto y envuelve las páginas seleccionadas en un catálogo y un árbol de páginas mínimos. Admite la división por rangos, la división de tamaño fijo (splitEvery) y la extracción de un único rango (extractPages).
PdfPortfolio construye un diccionario de PDF Collection que agrega adjuntos de archivo con un esquema definido. Admite los modos de vista de mosaico, detalle y oculto, y emite un diccionario apto para su inclusión en el catálogo del documento.

Por qué funciona así

Dividir un PDF no es un corte de bytes. Un objeto de página se refiere a recursos, fuentes y flujos de contenido compartidos mediante referencia indirecta. Además hereda /MediaBox y /Resources de sus ancestros en el árbol de páginas. Por eso el divisor reconstruye cada segmento como un grafo de objetos autocontenido: recorre el cierre transitivo de referencias de las páginas seleccionadas, materializa los atributos heredados, renumera en un espacio de identificadores nuevo y escribe una tabla de referencias cruzadas con desplazamientos precisos a nivel de byte. El recorrido del cierre está acotado, porque de lo contrario un grafo de expansión hostil podría arrastrar una cantidad ilimitada de trabajo a un solo segmento. El resultado se abre como un PDF autónomo válido, no como un fragmento con referencias colgantes.

Trasfondo de diseño: Anatomía de un archivo PDF.

Contrato de comportamiento

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) aplica un límite de tamaño de entrada y un límite de número de rangos, y rechaza la entrada que no comienza con la cabecera PDF.
splitEvery($pdfData, $pagesPerSegment) rechaza un tamaño de segmento inferior a 1; el segmento final puede contener menos páginas.
PdfPortfolio rechaza en el momento de la construcción cualquier modo de vista distinto de mosaico, detalle u oculto.
addSchema() y addEntry() devuelven el portfolio para el encadenamiento fluido; generateCollectionDictionary() devuelve la cadena del diccionario Collection.
Los nombres de campo del esquema se sanean para su uso como objetos de nombre PDF; los valores de cadena se escapan para las cadenas literales PDF.

Ejemplo de código — Inicio rápido

Lo siguiente refleja la API pública documentada. El repositorio no incluye un ejemplo ejecutable para este módulo.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Ejemplo de código — Producción

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

Casos límite y trampas

El divisor reconstruye cada segmento como un grafo de objetos nuevo con una tabla de referencias cruzadas real y precisa a nivel de byte; los segmentos son PDF autónomos válidos. Renumera en un espacio de identificadores nuevo en lugar de preservar la disposición de bytes de origen, así que entregue los bytes del segmento al módulo Writer para los flujos de actualización incremental o de firma.
Un rango que no coincide con ninguna página produce un segmento mínimo de una página en lugar de un error.
La ordenación del portfolio toma por defecto el primer campo de esquema, en orden ascendente.

Rendimiento

La división y el ensamblado del portfolio son lineales respecto al tamaño de la entrada y al número de entradas. El tope de entrada predeterminado es de 100 MB y el tope de rangos predeterminado es de 1000; ambos los puede ajustar a la baja el llamante. Mida con documentos representativos.

Notas de seguridad

Trate la entrada como no confiable. Las protecciones de tamaño y de número acotan el uso de recursos. El módulo sanea los nombres de campo y escapa los valores de cadena antes de que lleguen al diccionario de salida. No registra ningún contenido del documento.

Conformidad

El diccionario Portfolio sigue el modelo de PDF Collections y el divisor sigue el modelo de objetos de página definido por ISO 32000-2; el código fuente anota las cláusulas pertinentes. El corpus RAG no estaba disponible en el momento de la redacción, por lo que esta página no afirma ningún identificador de cláusula externo y limita las declaraciones de conformidad al comportamiento verificado por las pruebas del módulo.

Nota sobre el límite de Enterprise

Enterprise no cambia el comportamiento de Document. Enterprise añade funciones de archivo y cumplimiento de nivel superior documentadas por separado; no son necesarias para la división ni para el ensamblado de Portfolio.

Alternativa / repliegue a Core

Sin Pro, use las primitivas de documento básicas de NextPDF Core; la división por rangos de páginas y el ensamblado de Portfolio son adiciones de Pro. Consulte /modules/document/.

Límite de publicación

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