Erros do core e gerais

Escopo

Estas entradas cobrem as exceções do core e de uso geral que o NextPDF gera. A maioria estende a base NextPdfException, que por sua vez estende \RuntimeException e implementa ContextAwareExceptionInterface. Essa interface expõe um método, getContext(): array, que retorna um mapa plano em snake_case de primitivos seguros para serializar em um log ou em um payload de APM.

Capture a família NextPdfException com um único catch (NextPdfException $e). Adicione também um catch (\RuntimeException $e) para cobrir os poucos erros de baixo nível deste conjunto que estendem \RuntimeException diretamente (listados abaixo). A base NextPdfException::getContext() retorna um array vazio; as subclasses o sobrescrevem para adicionar campos de domínio. Quando uma classe não sobrescreve getContext(), ela herda o array vazio e o detalhe de diagnóstico vive na mensagem e nos getters tipados.

Quatro tipos deste conjunto não estendem NextPdfException: BlackPointCompensationUnsupportedException e UnsupportedSourceDocumentException estendem \RuntimeException diretamente (capture-os como \RuntimeException), e ComplianceViolation e RuleViolation são objetos de valor, não exceções — eles são documentados aqui porque modelam dados de erro e de violação que o engine retorna.

Exceção base

NextPdfException

• O que é. Base abstract para toda exceção gerada pelo core do NextPDF e por seus pacotes de extensão. Estende \RuntimeException e implementa ContextAwareExceptionInterface. Capturar esse único tipo intercepta qualquer erro da biblioteca.
• Contexto. O getContext() base retorna um array vazio. As subclasses o sobrescrevem para retornar campos específicos do domínio.
• Recuperação. Não é gerada diretamente. Use-a como o tipo abrangente; ramifique pela subclasse concreta para tratamento específico.

Configuração e feature gating

InvalidConfigException

• Quando é gerada. Quando um valor de Config ou uma combinação de valores é inválido — uma configuração obrigatória ausente, uma opção mutuamente exclusiva ou um valor fora do intervalo aceito. Isso sinaliza um erro do desenvolvedor: o código chamador forneceu uma configuração que deve ser corrigida antes de tentar novamente. A mensagem informa a chave, o tipo ou intervalo esperado e o tipo de debug real do valor fornecido.
• Contexto. getContext() retorna config_key, given_value e expected_type. Getters tipados: getConfigKey(), getGivenValue(), getExpectedType().
• Recuperação. Ação do desenvolvedor: corrija a chave de configuração nomeada para um valor do tipo ou intervalo esperado antes de chamar o NextPDF novamente.

NotImplementedException

• Quando é gerada. Quando um ponto de entrada de API pública é alcançado, mas sua implementação está intencionalmente ausente na versão atual. Usada para shims obsoletos que existem para dar aos chamadores pré-bisect uma falha alta e acionável, em vez de um no-op silencioso. A mensagem combina um rótulo feature pesquisável por grep e uma referência followUp (ID de defeito, âncora de rastreamento ou nome de sprint).
• Contexto. Não sobrescreve getContext(), então retorna um array vazio. Os valores $feature e $followUp são propriedades públicas readonly e estão embutidos na mensagem.
• Recuperação. Ação do chamador da biblioteca: remova a chamada ou fixe em uma versão futura que entregue o follow-up nomeado.

IncompatibleFeatureFlagsException

• Quando é gerada. No momento de build do Config (Config::validate()) quando uma combinação de CssFeatureFlags é internamente inconsistente — uma flag pressupõe outra que está desativada. A única combinação proibida atualmente é layoutSubgrid = true com layoutGrid = false: um eixo com subgrid deriva suas linhas de grade de um contêiner de grade pai (CSS Grid Layout Module Level 2 §1), então subgrid sem grid descreve uma grade que não pode existir. A verificação é executada sobre as flags resolvidas, então CssRenderingMode::Safe (que força cada recurso da Fase 4+ a ficar desligado) mascara a combinação em vez de dispará-la. Estende StrictModeViolation.
• Contexto. getContext() mescla os campos de modo estrito do pai (cssDeviation, excId, chunkSha256, location) com os booleanos layoutGrid e layoutSubgrid. O location é Config::validate() e cssDeviation codifica o par de flags.
• Recuperação. Ação do chamador da biblioteca: ative layoutGrid junto com layoutSubgrid, ou desative layoutSubgrid.

IncompatibleRenderingModeException

• Quando é gerada. No momento de build do Config quando um pareamento de CssRenderingMode e CssLayoutMode cai fora das células compatíveis da matriz de modos. O único pareamento proibido atualmente é CssRenderingMode::Safe + CssLayoutMode::Retained — Safe força cada recurso da Fase 4+ a ficar desligado, deixando os contextos de formatação do modo retained (Grid, Subgrid, @container) sem consumidores, então a combinação é rejeitada em vez de ter degradação silenciosa permitida. Estende StrictModeViolation.
• Contexto. getContext() mescla os campos de modo estrito do pai com mode1 (o valor do modo de renderização) e mode2 (o valor do modo de layout). O cssDeviation codifica o par de modos; location é Config::validate().
• Recuperação. Ação do chamador da biblioteca: escolha Safe + Streaming para rollback, ou um modo de renderização não Safe (Normal / Strict / Audit) com Retained para Grid / Subgrid / Container Queries.

StrictModeViolation

• Quando é gerada. Base abstract para qualquer exceção de desvio de especificação gerada sob CssRenderingMode::Strict. No modo estrito, qualquer desvio de CSS detectado que não esteja vinculado a uma entrada de exceção EXC-NNN registrada gera uma instância desta classe (ou de uma subclasse) no ponto de detecção. Não é gerada diretamente; consulte IncompatibleFeatureFlagsException e IncompatibleRenderingModeException.
• Contexto. getContext() retorna os quatro campos do ADR-023: cssDeviation (rótulo curto para a construção que desvia), excId (identificador de registro quando registrado, caso contrário null), chunkSha256 (hash do chunk de citação de especificação quando conhecido, caso contrário null) e location (origem legível pelo chamador, caso contrário null).
• Recuperação. Ação do chamador da biblioteca: registre o desvio como uma nova entrada EXC-NNN aprovada, ou corrija o renderizador para remover o desvio.

Entrada de HTML e CSS

HtmlParsingException

• Quando é gerada. Quando o parsing da entrada HTML ou a construção do DOM falha: declarações de charset inválidas, violações de limite de tamanho de entrada, profundidade de aninhamento excessiva, estouros de contagem de elementos e erros de estrutura de tabela, como uma contagem máxima de linhas. A exaustão de recursos específica de CSS é relatada, em vez disso, por CssParserLimitExceededException e CssResolutionBudgetExceededException.
• Contexto. getContext() retorna html_snippet (um trecho curto e truncado do HTML problemático), position (offset de byte, ou -1 se desconhecido) e rule (a restrição de parser violada). Getters tipados: getHtmlSnippet(), getPosition(), getRule().
• Recuperação. Ação do desenvolvedor: simplifique a entrada HTML ou ajuste os limites do parser.

CssParserLimitExceededException

• Quando é gerada. Quando a entrada CSS excede um limite de segurança configurado do parser. Duas categorias são cobertas pelos construtores nomeados: forByteLimit() (folha de estilo grande demais para processamento seguro por regex) e forNestingDepth() (recursão de aninhamento de CSS profunda demais). Ambas as mensagens informam o valor real e o limite.
• Contexto. getContext() retorna limit_type (byte ou nesting_depth), actual e limit.
• Recuperação. Ação do desenvolvedor: divida a folha de estilo em folhas menores, ou reduza a profundidade de aninhamento, ou aumente o limite configurado.

CssResolutionBudgetExceededException

• Quando é gerada. Quando a resolução de :has() em CSS excede seu orçamento de travessia. O resolvedor de :has() de duas passagens impõe um orçamento estrito de visita de nós para evitar que seletores patológicos causem travessias quadráticas do documento; assim que a contagem total de visitas excede o limite, a folha de estilo é rejeitada como complexa demais. A mensagem informa a contagem de visitas e o orçamento.
• Contexto. getContext() retorna visits e budget. Getters tipados: getVisits(), getBudget().
• Recuperação. Ação do desenvolvedor: reduza a complexidade do seletor, ou aumente o orçamento configurado.

Fontes e imagens

FontNotFoundException

• Quando é gerada. Quando um arquivo de fonte não pode ser localizado ou lido no nível do sistema de arquivos: a família ou o caminho solicitado não existe, não é legível, ou o diretório de fontes configurado está inacessível. Os dados da fonte podem ser válidos — isso sinaliza apenas que não é possível alcançá-los. A mensagem lista os caminhos pesquisados.
• Contexto. getContext() retorna font_name, search_paths (uma lista) e fallback_attempted (um bool). Getters tipados: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Recuperação. Ação do desenvolvedor: verifique o caminho da fonte. Ação de infraestrutura: corrija as permissões de arquivo do arquivo ou diretório da fonte.

FontParsingException

• Quando é gerada. Quando um arquivo de fonte é encontrado, mas seu conteúdo não é utilizável: está corrompido, em um formato não suportado ou faltam tabelas obrigatórias. Cobre falhas de validação estrutural durante o parsing de TrueType, Type 1, CFF e OpenType — cabeçalhos truncados, diretórios de tabela inválidos, tabelas obrigatórias ausentes (head, hhea, OS/2), erros de descompactação e violações de tamanho. A mensagem informa o arquivo e o erro de parsing.
• Contexto. getContext() retorna font_file e parse_error. Getters tipados: getFontFile(), getParseError().
• Recuperação. Ação do desenvolvedor: substitua o arquivo de fonte por um válido.

ImageProcessingException

• Quando é gerada. Quando uma imagem não pode ser decodificada, está em um formato não suportado ou falha no processamento de GD/Imagick: magic bytes não reconhecíveis, dados JPEG corrompidos, tipos MIME não suportados, violações de limite de tamanho de arquivo e falhas de alocação de recurso GD. A imagem estava acessível, mas seus dados de pixel não puderam ser extraídos para incorporação.
• Contexto. getContext() retorna image_path (vazio para dados inline), format (detectado ou esperado, por exemplo jpeg, png, unknown) e operation (por exemplo decode, resize, embed). Getters tipados: getImagePath(), getFormat(), getOperation().
• Recuperação. Ação do desenvolvedor: forneça um arquivo de imagem válido e suportado.

Saída, layout e serialização

CompressionException

• Quando é gerada. Quando a compressão ou descompressão FlateDecode (zlib) falha — falhas de gzcompress/gzuncompress em content streams, dados de fonte, conteúdo de página, dados de anexo e cross-reference streams. Normalmente um stream de entrada corrompido, memória insuficiente ou uma extensão zlib ausente.
• Contexto. getContext() retorna algorithm (nome do filtro, por exemplo FlateDecode, LZWDecode) e stream_length (comprimento em bytes, ou -1 se desconhecido). Getters tipados: getAlgorithm(), getStreamLength().
• Recuperação. Ação de infraestrutura: verifique se ext-zlib está carregado e se a memória é suficiente.

WriterException

• Quando é gerada. Quando a serialização, a linearização ou a saída de I/O de PDF falha: erros de gravação de stream do PdfWriter, corrupção da tabela de cross-reference, falhas de geração de header/trailer, falhas de resolução de referência de objeto, erros de gravação de arquivo e estouros do buffer de saída. Um documento válido em memória não pôde ser serializado em um stream de bytes válido. A mensagem informa o estágio.
• Contexto. getContext() retorna output_path (vazio para saída em string) e writer_state (o estágio, por exemplo header, body, xref, trailer). Getters tipados: getOutputPath(), getWriterState().
• Recuperação. Ação de infraestrutura: verifique o espaço em disco, as permissões de arquivo e o stream de saída.

PageLayoutException

• Quando é gerada. Quando as restrições de layout de página não podem ser satisfeitas: violações de layout de coluna (largura insuficiente, contagem de colunas inválida), estouro de conteúdo além dos limites da página e conflitos de margem. O layout solicitado é geometricamente impossível para as dimensões e o conteúdo da página dados. A mensagem informa o número da página quando conhecido e a restrição violada.
• Contexto. getContext() retorna page_number (com base em um, ou 0 se desconhecido) e constraint. Getters tipados: getPageNumber(), getConstraint().
• Recuperação. Ação do desenvolvedor: ajuste o tamanho da página, as margens, as configurações de coluna ou o conteúdo.

TemplateException

• Quando é gerada. Quando uma operação de importação ou reutilização de template PDF falha no TemplateManager: transições de estado de template inválidas (iniciar ou encerrar templates fora de sequência), referência a um template inexistente e falhas de compressão de stream durante a serialização do template. A mensagem informa a operação e o id do template quando atribuído.
• Contexto. getContext() retorna template_id (vazio se ainda não atribuído) e operation (por exemplo begin, end, use, serialize). Getters tipados: getTemplateId(), getOperation().
• Recuperação. Ação do desenvolvedor: corrija a sequência de uso do template ou o PDF de origem.

Invariantes de content stream

ContentStreamBalanceException

• Quando é gerada. Quando um ContentStreamBuilder detecta um par de operadores desbalanceado no fechamento do stream (ou no meio do stream quando os invariantes são verificados de forma antecipada). Ela captura os contadores de profundidade que falharam no invariante de balanceamento para que o log possa identificar qual emissor vazou um q, BT ou BMC sem seu Q, ET ou EMC correspondente. Conforme ISO 32000-2:2020 §8.4.2 (pilha de estado gráfico), §9.4.1 (objetos de texto) e §14.6 (marked content).
• Contexto. getContext() retorna graphics_depth, text_block_depth, marked_content_depth e offending_operator. Getters tipados: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Recuperação. Ação do desenvolvedor: localize o emissor que abriu uma construção sem fechá-la.

GraphicsStateBalanceException

• Quando é gerada. Quando um content stream de PDF é fechado com operadores q/Q desbalanceados. A ISO 32000-2:2020 §8.4.2 exige que cada salvamento de estado gráfico (q) seja correspondido por exatamente um restauro (Q) antes do término do stream; o desbalanceamento vaza transformação, caminho de recorte, cores e intenção de renderização para páginas subsequentes ou Form XObjects. Gerada apenas quando a verificação estrita de estado gráfico está ativada (NEXTPDF_GFXSTATE_STRICT=1); no modo relaxado, um aviso é emitido via trigger_error().
• Contexto. getContext() retorna save_depth (positivo para salvamentos em excesso, negativo para restauros em excesso). Getter tipado: getSaveDepth().
• Recuperação. Ação do desenvolvedor: localize o par save()/restore() não correspondido.

MissingShadingResourceException

• Quando é gerada. Quando ConicGradientRenderer::render() é invocado sem um contexto de registro de recurso Shading. A mudança disruptiva da v10.0.0 removeu o caminho substituto de mapa de marcadores implícitos anterior: os chamadores devem construir o renderizador com um ShadingResourceRegistryInterface para que o objeto indireto /ShadingType 4 seja registrado na subdictionary de recurso Shading da página (ISO 32000-2 §8.7.4.2 / §8.7.4.3). A mensagem informa o contexto do chamador e aponta para a nota de migração v9.x→v10.0.
• Contexto. getContext() retorna context (um rótulo curto de contexto do chamador, por exemplo ConicGradientRenderer::render).
• Recuperação. Ação do chamador da biblioteca: conecte uma instância de registro de recurso Shading ao construtor do renderizador antes de chamar render().

Linearização (Fast Web View)

LinearizationInvariantException

• Quando é gerada. Quando o Linearizer de três passagens da v2 detecta que suas asserções MEASURE → PLACE → FILL foram violadas: uma contagem de bytes da Pass 3 que não corresponde ao comprimento de arquivo previsto na Pass 1 (deriva de offset), um placeholder de dicionário de linearização pequeno demais para a largura serializada, ou um offset de hint stream /H [offset length] que não corresponde à saída final. Expor isso, em vez de emitir um PDF quebrado, é uma garantia de segurança declarada.
• Contexto. getContext() retorna invariant (o nome do invariante violado), expected, actual e delta (a diferença com sinal). Getters tipados: getInvariant(), getExpectedValue(), getActualValue().
• Recuperação. Ação do mantenedor: abra um relatório de bug — esses invariantes devem ser mantidos para todas as entradas bem formadas. Capture a exceção anterior encadeada.

LinearizationUnimplementedException

• Quando é gerada. Quando a feature flag do linearizer está definida para um backend que está intencionalmente desativado. Atualmente gerada apenas para linearizerVersion === 'v1-noop', a configuração de downgrade de emergência que rejeita todas as tentativas de linearização em tempo de execução sem uma mudança de código ou redeploy — útil para acionar o kill-switch do Fast Web View em produção.
• Contexto. getContext() retorna reason (uma explicação curta e legível por humanos). Getter tipado: getReason().
• Recuperação. Ação do operador / engenharia de release: ajuste a configuração ou atualize para uma versão de backend corrigida.

Invariantes de conformidade e perfil

ConformanceViolationException

• Quando é gerada. Quando um recurso solicitado não pode ser emitido sem quebrar o contrato de conformidade ISO declarado do documento, e o engine falha de forma fechada em vez de gravar um objeto não conforme. O gatilho canônico é uma anotação Screen multimídia ou uma ação Rendition (ISO 32000-2:2020 §12.5.6.18 / §13.2) sob um perfil de arquivamento PDF/A, que toda parte do PDF/A proíbe (série ISO 19005) — o arquivo falharia na validação do veraPDF, então o engine se recusa de antemão.
• Contexto. getContext() retorna conformance_mode (o modo declarado, por exemplo pdfa4) e feature (o recurso rejeitado, por exemplo Screen annotation). Ambos são propriedades públicas readonly. O motivo é a mensagem da exceção.
• Recuperação. Ação do desenvolvedor: descarte a chamada multimídia para saída de arquivamento, ou tenha como alvo um perfil de conformidade não de arquivamento (padrão ConformanceMode::Plain).

PdfRViolationException

• Quando é gerada. Quando um invariante de conformidade PDF/R-1 (ISO 23504-1:2020) é violado, seja na construção do objeto de valor (os perfis PdfRStrip, PdfRPage, PdfRDocument) ou no momento do validador (PdfRValidator). Ela captura a cláusula normativa problemática e uma descrição de violação de uma linha, para que os consumidores de auditoria possam rotear constatações para a subcláusula §6 correta sem fazer parsing de texto livre.
• Contexto. getContext() retorna standard (sempre ISO 23504-1:2020), clause (o caminho da cláusula, por exemplo 6.6.1) e violation. Getters tipados: getClause(), getViolation().
• Recuperação. Ação do desenvolvedor: corrija a entrada rejeitada ou reconstrua o documento para estar em conformidade com a cláusula citada.

Geração de código de barras

BarcodeException

• Quando é gerada. Quando a geração de código de barras falha devido a dados inválidos ou erros de codificação em todas as simbologias suportadas (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) e falhas de renderização de GD durante a criação de imagem. O valor do código de barras tem limite de excerto de 128 bytes na mensagem e no contexto — payloads grandes demais ou binários são armazenados truncados com um marcador ... (<N> bytes, truncated) para que não possam ser copiados inteiros em um log.
• Contexto. getContext() retorna barcode_type (simbologia, por exemplo QRCODE, EAN13, CODE128) e value (o valor truncado). Getters tipados: getBarcodeType(), getValue().
• Recuperação. Ação do desenvolvedor: corrija os dados do código de barras ou a seleção da simbologia.

BarcodeEncoderNotFoundException

• Quando é gerada. A partir de BarcodeEncoderRegistry quando o tipo de encoder solicitado é desconhecido ou seu portão de capacidade está fechado. Ela também implementa o PSR-11 Psr\Container\NotFoundExceptionInterface, então o registro é um contêiner em conformidade com o padrão. A mensagem informa a simbologia e o motivo.
• Contexto. Não sobrescreve getContext(), então retorna um array vazio. O type e o reason estão disponíveis pelos getters getType() e getReason() e na mensagem.
• Recuperação. Ação do desenvolvedor: registre o encoder, ou instale o pacote que o fornece (por exemplo nextpdf/pro para Micro QR / DotCode / HanXin / JabCode).

Criptografia, encriptação e assinaturas

EncryptionException

• Quando é gerada. Quando a encriptação ou desencriptação de PDF falha: falhas de encriptação/desencriptação AES-256-CBC, erros de OpenSSL, tamanhos de IV inválidos, falhas de cálculo de hash e erros de cálculo de valor UE/OE. Normalmente uma extensão OpenSSL ausente ou mal configurada, material de chave inválido ou dados encriptados corrompidos. A mensagem informa a operação e o algoritmo.
• Contexto. getContext() retorna algorithm (por exemplo AES-256-CBC) e operation (por exemplo encrypt, decrypt, key_derivation). Getters tipados: getAlgorithm(), getOperation().
• Recuperação. Ação de infraestrutura: garanta que o OpenSSL esteja disponível e corretamente configurado. Consulte Criptografia e permissões.

UnsupportedAlgorithmException

• Quando é gerada. Quando um algoritmo criptográfico não pode ser executado no runtime atual: uma extensão PHP obrigatória está indisponível, a biblioteca subjacente não tem o primitivo, a extensão hash empacotada não consegue sintetizar uma variante SHAKE/XOF, ou o algoritmo não está registrado no SignatureAlgorithmRegistry. O engine não deve degradar silenciosamente para um primitivo mais fraco, então ele expõe isso. A fábrica estática nonFipsHostUnderFipsProfile() a gera (com o identificador de algoritmo regulatory-profile:fips) quando RegulatoryProfile::FIPS é selecionado, mas um provedor OpenSSL validado por FIPS não pode ser confirmado (tanto FIPS_ABSENT quanto INDETERMINATE falham de forma fechada).
• Contexto. getContext() retorna algorithm (nome ou OID, por exemplo shake256, Ed25519, AES-256-GCM) e reason (acionável pelo operador). Getters tipados: getAlgorithm(), getReason().
• Recuperação. Ação do operador: instale a extensão ausente ou atualize o runtime; para o portão FIPS, instale uma build de OpenSSL validada por FIPS ou defina NEXTPDF_FIPS_MODE explicitamente. Ação do desenvolvedor: registre um descritor de algoritmo personalizado via SignatureAlgorithmRegistry::register().

SignatureException

• Quando é gerada. Quando uma operação de assinatura digital falha: tratamento de certificado e de chave privada (parsing de PKCS#12, decodificação de PEM/DER, validação X.509), construção de PKCS#7/CMS, formato de assinatura ECDSA, violações de tamanho de contêiner, codificação DER e orquestração PAdES. Erros específicos de TSA são relatados pela mais específica TsaException. Prefira as fábricas nomeadas tipadas ao construtor posicional; cada uma vincula a causa raiz ao final da mensagem. Exemplos: ltvCapabilityMissing() (B-LT/B-LTA precisa de nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), a família Ed25519 (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing() e o par de status OCSP nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Essas fábricas falham de forma fechada em vez de emitir uma assinatura silenciosamente rebaixada.
• Contexto. getContext() retorna cert_info (subject DN ou thumbprint, ou vazio), signature_level (o nível PAdES tentado, por exemplo B-B, B-T, B-LT, B-LTA) e detail (o diagnóstico acionável, vazio para o construtor posicional legado). Getters tipados: getCertInfo(), getSignatureLevel(), getDetail().
• Recuperação. Ação do desenvolvedor: corrija a configuração de certificado/chave. Para fábricas de recurso ausente, instale o pacote nomeado. Consulte Falhas de assinatura e carimbo de tempo para entradas de sintoma e resolução por fábrica.

BlackPointCompensationUnsupportedException

• Quando é gerada. A partir de NullBlackPointCompensationTransform::transform() quando um chamador pede ao adaptador nulo que aplique uma transformação de compensação de ponto preto ISO 18619 não Default. O adaptador nulo é o fallback seguro para ambientes sem um backend de gerenciamento de cores; produzir uma amostra transformada sem um módulo real de gerenciamento de cores relataria silenciosamente a conversão de forma incorreta. Ao contrário da maioria das entradas aqui, esta estende \RuntimeException diretamente, não NextPdfException, então os caminhos catch (\RuntimeException) existentes continuam funcionando.
• Contexto. Sem getContext(); é uma \RuntimeException simples. O detalhe está na mensagem.
• Recuperação. Ação do desenvolvedor: registre uma BlackPointCompensationTransform real (LittleCMS, Argyll, PHP puro), ou restrinja /UseBlackPtComp a BlackPointCompensation::Default.

Montagem de documento e acessibilidade

UnsupportedSourceDocumentException

• Quando é gerada. Quando um documento de origem não pode ser copiado com segurança para uma saída de mesclagem/divisão e a operação falha de forma fechada em vez de emitir um resultado corrompido ou com segurança comprometida. Use as fábricas nomeadas: encrypted() (ISO 32000-2 §7.6 — o conteúdo não pode ser copiado sem a chave), signed() (§12.8 — copiar páginas invalidaria o byte range da assinatura), unsupportedStreamFilter() (um filtro que o reader do grafo de objetos não consegue fazer round-trip), multipleInteractiveForms() (uma limitação documentada: mais de uma origem carrega um /AcroForm não vazio, §12.7) e splitWithInteractiveForm() (uma limitação documentada: subdividir páginas de uma origem com formulário deixaria widgets órfãos). Estende \RuntimeException diretamente, não NextPdfException.
• Contexto. Sem getContext(); é uma \RuntimeException simples. A causa e o número do objeto afetado são informados na mensagem.
• Recuperação. Ação do desenvolvedor: descriptografe a origem primeiro ou forneça a chave; para origens assinadas, assine após a mesclagem; para mesclagens com múltiplos formulários, achate ou remova os campos de formulário de todas as origens, exceto uma; para divisões com formulário, achate o formulário antes de dividir.

InvalidBcp47TagException

• Quando é gerada. A partir de Bcp47Validator::validate() quando uma tag de idioma candidata está malformada sob o ABNF da RFC 5646 §2.1, ou falha na consulta ao registro curado. Específica do domínio BCP-47 / ISO 14289-2:2024 §8.4.4, distinta de InvalidConfigException, para que os chamadores a jusante da junção de acessibilidade possam capturar um tipo restrito. O par de predicados Bcp47Validator::isWellFormed() / isValid() permanece a superfície de valor de retorno retrocompatível para chamadores que preferem ramificação a exceções.
• Contexto. getContext() retorna tag (o candidato exatamente como fornecido) e reason (um código de rejeição estável e legível por máquina, por exemplo empty-string, well-formed-shape, unregistered-primary, duplicate-variant). Getters tipados: getTag(), getReason().
• Recuperação. Ação do desenvolvedor: corrija a tag de idioma para uma tag BCP-47 bem formada e registrada. Consulte Fontes e tagueamento.

FormFieldAccessibilityException

• Quando é gerada. Quando um campo de formulário interativo dependeria de um nome acessível sintético (não fornecido pelo autor) ao produzir um documento PDF/UA com a imposição estrita de nome acessível de campo ativada. A saída PDF/UA padrão emite um nome de fallback sintético no /Contents do widget para que um campo nunca fique sem nome; o modo estrito, em vez disso, exige que o autor forneça um nome significativo (um tooltip, ou uma legenda para um botão de envio sem ação) para que usuários de leitor de tela recebam uma descrição real (ISO 14289-2:2024 §8.10.2).
• Contexto. Não sobrescreve getContext(), então retorna um array vazio. O $fieldId é uma propriedade pública readonly; o motivo é a mensagem.
• Recuperação. Ação do desenvolvedor: forneça um tooltip / nome acessível para o campo nomeado antes de produzir um documento PDF/UA estrito, ou desative o modo estrito. Consulte Validação de PDF/A e PDF/UA.

VendorExtensionRegistryConflictException

• Quando é gerada. A partir de VendorExtensionRegistry::register() quando um chamador re-registra um prefixo de fornecedor de extensão de desenvolvedor de PDF conhecido (ISO 32000-2:2020 §7.12.1) com uma descrição que diverge dos metadados já registrados. Os descritores são append-only e têm detecção de conflito; a exceção tipada substituiu uma \RuntimeException genérica para que os chamadores possam capturar esta classe específica.
• Contexto. getContext() retorna prefix, existing_description e attempted_description. Getters tipados: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Recuperação. Ação do desenvolvedor: registre o prefixo com a descrição existente, ou use um prefixo distinto; não sobrescreva metadados registrados.

Exportação de auditoria

AuditExportException

• Quando é gerada. Quando a montagem do bundle de exportação de auditoria, a geração da matriz de rastreabilidade ou a projeção de schema falha em tempo de execução. Cobre I/O contra claims.json / manifest.json, encode/decode JSON do bundle canônico e incompatibilidade de versão de schema no caminho retrocompatível de AuditExporter::projectToV1(). A mensagem informa o estágio, o artefato quando conhecido e o detalhe.
• Contexto. getContext() retorna stage (por exemplo read_claims, encode_bundle, project_v1), detail e artefact (caminho ou schema_version que disparou a falha). Getters tipados: getStage(), getDetail(), getArtefact().
• Recuperação. Ação de conformidade / DevOps: verifique os caminhos do artefato de entrada, regere claims.json a partir de uma execução limpa, ou reconstrua o manifesto antes de tentar a exportação novamente.

Objetos de valor de violação

Estes não são exceções. São objetos de valor imutáveis que o engine retorna para descrever uma violação individual; eles não carregam getContext().

ComplianceViolation

• O que é. Um objeto de valor final readonly que representa uma falha de regra relatada por um validador externo (veraPDF ou equivalente), incluindo a referência de cláusula ISO e a localização dentro da estrutura do PDF.
• Campos. Propriedades públicas readonly: ruleId (identificador de regra do validador, por exemplo 6.1.2-1), clause (referência de cláusula ISO, por exemplo ISO 19005-1:2005, 6.1.2), severity (por exemplo error, warning), location (caminho do objeto dentro da estrutura do PDF) e message (descrição legível por humanos).
• Uso. Inspecione a coleção retornada por um validador de conformidade; roteie ou exiba cada entrada por severity e clause. Consulte Validação de PDF/A e PDF/UA.

RuleViolation

• O que é. Um objeto de valor final readonly que representa uma violação de regra de negócio Schematron / EN 16931, retornado por SchematronRunnerInterface::runRules() e agregado dentro de ValidationResult::$ruleViolations. A estabilidade é experimental.
• Campos. Propriedades públicas readonly: ruleId (identificador EN 16931 como BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n}, ou um pacote específico de tier), severity (um enum RuleSeverity), message (texto da regra, en-GB), xpath (XPath para o XML incorporado, null para regras de documento inteiro) e semanticPath (caminho BG/BT em notação de ponto como BG-22.BT-106, null para violações estruturais).
• Uso. Inspecione a coleção no resultado de validação; roteie ou exiba cada entrada por severity, ruleId e localizador.

Veja também

• Índice de referência de erros
• Índice da base de conhecimento
• Falhas de assinatura e carimbo de tempo
• Criptografia e permissões
• Fontes e tagueamento
• Validação de PDF/A e PDF/UA