Erros de renderização e I/O

Escopo

Estas entradas cobrem as exceções de renderização e de entrada/saída (I/O) geradas enquanto o pipeline de HTML faz o layout do conteúdo, o resolvedor de mídia paginada atribui a geometria de página, o text shaper processa scripts complexos, o estágio de tipografia quebra linhas, o writer serializa um documento, o reader faz parsing de um PDF existente e o estágio de metadados lê um pacote Extensible Metadata Platform (XMP).

Duas hierarquias base aparecem abaixo, e a diferença governa quais dados de diagnóstico você pode ler após um catch:

• NextPdfException implementa ContextAwareExceptionInterface::getContext(): array. A implementação base retorna um array vazio; uma subclasse carrega chaves estruturadas somente quando sobrescreve getContext(). Subclasses que não a sobrescrevem ainda expõem seus dados por meio de propriedades public readonly.
• Várias classes aqui estendem a RuntimeException do PHP diretamente. Elas não são sensíveis ao contexto e não têm método getContext(); leia seu getMessage() e quaisquer propriedades públicas.

Cada entrada nomeia a classe exata, a condição de gatilho, as chaves de contexto ou propriedades públicas que carrega e o caminho de recuperação.

Layout de HTML e mídia paginada

UnsplittableContentException

• Quando é gerada. O engine de layout de HTML gera isto quando conteúdo marcado como break-inside: avoid (uma célula de tabela cuja restrição de quebra é Avoid) tem uma altura medida que excede a altura utilizável de uma única página. O engine não consegue satisfazer ao mesmo tempo a restrição avoid-break e o limite da página, então ele falha em vez de transbordar silenciosamente.
• Dados carregados. Estende NextPdfException, mas não sobrescreve getContext(), então getContext() retorna um array vazio. Os dados de diagnóstico estão em propriedades public readonly: gridRow (int), gridCol (int), contentHeight (float, pontos) e pageHeight (float, pontos). A mensagem informa as coordenadas da célula e ambas as alturas.
• Recuperação. Remova a restrição break-inside: avoid da célula problemática, reduza o conteúdo da célula para que caiba em uma página, ou aumente o tamanho da página ou reduza suas margens para que a altura utilizável acomode o conteúdo.

BudgetExceededException

• Quando é gerada. Os primitivos de layout do modo retained geram isto quando um dos quatro tiers de orçamento de recursos definidos no registro de decisão de arquitetura ADR-020 é violado e o chamador optou por uma falha rígida em vez do fallback suave. O caminho padrão não gera exceção: ContainerLayout::acceptChild() retorna false, o chamador recorre ao layout de bloco e um aviso é emitido. A exceção é reservada para validação em tempo de configuração e para testes que verificam a tupla de violação exata. Os tiers são per-child (um stream de filho capturado excede seu limite), per-container (o orçamento de contagem de nós do Tier 1), per-document (o orçamento de passagem de layout ou de profundidade de aninhamento) e global (o teto de resident-set-size de pico de 256 MB de todo o SDK).
• Dados carregados. Sobrescreve getContext(), que retorna um formato estável de oito chaves consumido por ferramentas de monitoramento de desempenho de aplicações (APM): budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize e processedItemCount. As primeiras quatro chaves são o subconjunto original da v1.0.0 e são sempre preenchidas; as últimas quatro têm padrão null ou 0 quando o construtor é chamado sem elas. getCausalWarningCode() mapeia a tupla (tier, container-type) para o WarningCode que o caminho de fallback suave teria emitido.
• Recuperação. Para uma violação de configuração, reduza o valor solicitado de volta ao envelope documentado (por exemplo, o orçamento de nós retained aceita 5.000 a 100.000 via Config::withRetainedNodeBudget()). Para uma violação de conteúdo, reduza o aninhamento de contêineres ou a contagem de nós, ou confie no fallback suave padrão para o layout de bloco em vez de optar pela superfície de falha rígida.

UnsupportedNamedPageException

• Quando é gerada. O estágio de mídia paginada gera isto, com falha fechada, quando um documento declara uma regra @page <ident> { … } nomeada (vinculada ao conteúdo por meio da propriedade page: <ident>). Páginas nomeadas do CSS Paged Media Level 3 §3.4 e Level 4 §3.2 — incluindo as pseudoclasses :first, :left, :right e :blank e as substituições nomeadas de size: e rotate: — são parseadas, mas nenhum caminho de layout de produção as consome. O engine se recusa em vez de emitir a paginação padrão silenciosamente incorreta que descartar a regra produziria.
• Dados carregados. Sobrescreve getContext(), que retorna page_names (lista dos idents distintos que dispararam a falha, na ordem da origem), has_size_override (bool), has_rotate_override (bool) e has_pseudo_classes (bool). Os mesmos valores são expostos nas propriedades públicas pageNames, hasSizeOverride, hasRotateOverride e hasPseudoClasses.
• Recuperação. Remova as regras @page <ident> nomeadas e quaisquer vinculações page: <ident>, e expresse a geometria pretendida por meio da regra @page { … } sem nome suportada e suas formas de pseudoclasse. Como alternativa, fixe em uma versão futura que entregue suporte completo a layout de página nomeada.

Tipografia e text shaping

IcuRequirementException

• Quando é gerada. A segmentação de texto gera isto quando precisa do iterador de quebra de linha do International Components for Unicode (ICU), mas a política require-ICU está ativa (NEXTPDF_REQUIRE_ICU=1) enquanto a extensão ext-intl e IntlBreakIterator estão indisponíveis.
• Dados carregados. Estende RuntimeException diretamente, então não é sensível ao contexto e não tem getContext(). É um refinamento estrito da exceção genérica que o mesmo caminho de código gerava anteriormente, então handlers catch (\RuntimeException) existentes continuam funcionando.
• Recuperação. Instale e ative ext-intl para que o iterador de quebra do ICU esteja disponível, ou remova NEXTPDF_REQUIRE_ICU para recorrer ao segmentador não-ICU onde a política require-ICU não é obrigatória.

ScriptShaperException

• Quando é gerada. Esta é a exceção base para a service provider interface (SPI) de shaping de script. Ela não é gerada diretamente hoje; subtipos concretos são gerados em vez disso. Capture este tipo para tratar qualquer falha de shaping em um só lugar.
• Dados carregados. Estende RuntimeException diretamente; não é sensível ao contexto, sem getContext().
• Recuperação. Ramifique pelo subtipo concreto. Consulte NotYetImplementedException abaixo para o único subtipo distribuído na versão atual.

NotYetImplementedException

• Quando é gerada. Cada text shaper placeholder gera isto a partir do corpo de seu shape() para scripts cujo shaping concreto está adiado (Mongol e Tibetano). A junção da SPI de shaping está pronta em arquitetura, mas o shaping real está pendente de uma fixture validada por falante nativo. Gerar uma exceção em vez de um no-op silencioso expõe a conexão acidental em produção em tempo de execução, em vez de emitir texto sem shaping em um PDF que afirma acessibilidade tagueada.
• Dados carregados. Estende ScriptShaperException (e, portanto, RuntimeException), então não é sensível ao contexto e não tem getContext(). Os dados de diagnóstico estão em suas propriedades public readonly: bcp47LanguageTag (a tag BCP-47 do run, como mn-Mong ou bo-Tibt) e missingCapability (a capacidade concreta que a implementação não tem). A mensagem inclui ambas.
• Recuperação. Não roteie runs nos scripts não implementados pelo shaper em produção. Detecte a tag de idioma a montante e recorra a um caminho de renderização diferente ou fixe em uma versão futura que entregue shaping para o script afetado.

Perfis de saída do writer e criptografia

Pdf14FeatureRejectedException

• Quando é gerada. O writer gera isto quando um documento contém um recurso proibido sob o perfil de saída PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), que proíbe construções introduzidas em versões posteriores do PDF.
• Dados carregados. Estende NextPdfException, mas não sobrescreve getContext(), então getContext() retorna um array vazio. Os dados de diagnóstico estão em suas propriedades public readonly: feature (o nome do recurso rejeitado), reason (por que ele é proibido) e isoClause (a referência de cláusula ISO). A mensagem combina os três.
• Recuperação. Remova ou substitua o recurso rejeitado por um equivalente compatível com PDF 1.4, ou tenha como alvo um perfil de saída superior que permita o recurso.

Pdf20FeatureRejectedException

• Quando é gerada. O writer gera isto quando um documento contém um recurso proibido sob o perfil de saída estrito de PDF 2.0. A ISO 32000-2:2020 descontinua construções que o PDF 1.7 ainda permitia — mais notavelmente as fontes Standard 14 Type 1 (§9.6.2), que devem ser incorporadas em um documento PDF 2.0 conforme.
• Dados carregados. Mesmo formato de Pdf14FeatureRejectedException: estende NextPdfException, não sobrescreve getContext() (retorna um array vazio) e expõe feature, reason e isoClause como propriedades public readonly.
• Recuperação. Remedie o recurso rejeitado — por exemplo, incorpore as base 14 fonts — ou use a saída de escape documentada onde houver uma (para fontes base 14 não incorporadas, Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Quando é gerada. PdfWriter::build() gera isto no ponto de entrada quando o encryptionMode do documento é pubkey (uma lista de destinatários de chave pública) antes de a dispatch de criptografia de corpo de stream por chave pública do lado do writer ser conectada. Recusar de antemão evita emitir silenciosamente um PDF não criptografado que o chamador acreditava estar criptografado.
• Dados carregados. Estende RuntimeException diretamente, então não é sensível ao contexto e não tem getContext(). É um refinamento estrito da exceção genérica que o mesmo site gerava anteriormente, então handlers catch (\RuntimeException) existentes continuam funcionando.
• Recuperação. Use um modo de criptografia suportado (criptografia baseada em senha) em vez da lista de destinatários de chave pública, ou fixe em uma versão que entregue suporte a criptografia de chave pública. Não trate a saída como criptografada quando isto for gerado.

Entrada do reader e de metadados

UnsupportedPdfStructureException

• Quando é gerada. O reader de grafo de objetos gera isto, com falha fechada, quando um PDF de entrada cai fora de seu envelope suportado. O reader suporta tabelas de cross-reference clássicas (ISO 32000-2:2020 §7.5.4), cross-reference streams (§7.5.8), objetos comprimidos em object stream (§7.5.7), cadeias /Prev multirrevisão (§7.5.6) e arquivos de referência híbrida via /XRefStm (§7.5.8.4). Qualquer coisa fora desse envelope expõe esta exceção em vez de um parsing parcial ou adivinhado. Construtores nomeados mapeiam para os casos de motivo: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile() e crossReferenceOffsetOutOfBounds().
• Dados carregados. Estende RuntimeException diretamente, então não é sensível ao contexto e não tem getContext(). Ela expõe uma propriedade public readonly reason do tipo UnsupportedPdfStructureReason (um enum) para que os chamadores ramifiquem pela categoria precisa sem fazer parsing da mensagem; uma string detail opcional e um throwable previous podem adicionar contexto delimitado e não sensível. A mensagem padrão é o resumo não vazante do motivo.
• Recuperação. Ramifique por reason. Para EncryptedDocument, execute uma etapa de descriptografia antes de ler, já que a descriptografia está fora do escopo do reader. Para DamagedCrossReference, TruncatedFile ou CrossReferenceOffsetOutOfBounds, trate o arquivo como malformado ou incompleto e readquira ou repare a origem. Para CyclicReferenceChain, NonConformantObjectStream ou IrresolvableObjectCollision, a entrada viola o modelo estrutural e não pode ser lida como está.

PacketTooLargeException

• Quando é gerada. O reader de metadados XMP em streaming gera isto quando um pacote XMP incorporado excede o teto de bytes configurado. É um guard defensivo contra entradas do estilo entity-expansion e quadratic-blowup (um teto de pico de 128 MB contra XMP incorporado em escala de gigabytes).
• Dados carregados. Estende NextPdfException, mas não sobrescreve getContext(), então getContext() retorna um array vazio. Os dados de diagnóstico estão em suas propriedades public readonly: byteCount (a contagem de bytes observada) e cap (o limite configurado em bytes). A mensagem relata ambos.
• Recuperação. Rejeite ou ignore os metadados grandes demais como maliciosos ou malformados. Se um documento legítimo genuinamente precisar de um pacote maior, aumente o limite configurado deliberadamente, ponderando o risco de exaustão de memória que o guard existe para evitar.

Veja também

• Índice de referência de erros
• Solução de problemas de fontes e tagueamento — para os sintomas de NotYetImplementedException, ScriptShaperException e IcuRequirementException.
• Solução de problemas de validação de PDF/A e PDF/UA — para os sintomas de Pdf14FeatureRejectedException e Pdf20FeatureRejectedException.
• Solução de problemas de criptografia e permissões — para PublicKeyEncryptionUnsupportedException e o motivo EncryptedDocument do reader.