Common

Visão geral

O NextPDF Enterprise entrega um pequeno conjunto de primitivas compartilhadas reutilizadas entre os módulos Enterprise. A primeira é uma bounding box normalizada para posicionamento espacial independente de resolução. Essas são value objects sem comportamento de compliance, conformidade ou criptografia.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare as edições e obtenha uma licença.

O pacote Enterprise é instalado ao lado do pacote Core; essas primitivas compartilhadas são consumidas internamente pelos outros módulos Enterprise e são resolvidas com o pacote. Elas não têm equivalente no nível Core nem no nível Pro.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

BoundingBox é uma value object imutável cujas quatro coordenadas — x, y, largura, altura — são normalizadas para o intervalo [0.0, 1.0] em relação às dimensões da página. Como as coordenadas são normalizadas, a box é independente de resolução e pode ser reutilizada entre os módulos Enterprise que raciocinam sobre a geometria da página. O construtor valida que cada coordenada está dentro do intervalo e que x + width e y + height não excedem 1.0 (dentro de uma pequena tolerância de ponto flutuante), lançando um erro de argumento caso contrário.

Ela expõe area(), contains(self $other) e overlaps(self $other). Boxes de área zero (pontos ou linhas degenerados) não podem se sobrepor por definição.

O que este módulo afirma

Este módulo fornece primitivas de geometria validadas. Ele não faz nenhuma declaração de compliance ou conformidade e não realiza nenhuma I/O.

Limite de nível

Common é uma superfície de suporte exclusiva do Enterprise que outros módulos Enterprise consomem. Ela não duplica nem substitui a geometria do Core; ela fornece as pequenas primitivas validadas que os módulos Enterprise compartilham.

Por que funciona assim

A decisão fundamental é normalizar cada coordenada para o intervalo [0.0, 1.0] e validá-la no construtor. Coordenadas normalizadas tornam a box independente de resolução, de modo que uma região descrita uma vez permanece correta em qualquer tamanho de página ou escala de renderização. A construção fail-closed significa que uma box inválida ou com transbordamento não pode existir: o construtor a rejeita em vez de limitar ou adivinhar. Os módulos Enterprise consumidores, portanto, nunca reverificam a geometria que recebem, porque uma box construída já é conhecidamente válida. A imutabilidade mantém uma box compartilhada segura para ser passada entre módulos sem cópias defensivas. Contexto de design: Uma API que se recusa a adivinhar.

Superfície da API

Classe	Responsabilidade
BoundingBox	Box normalizada imutável; area(), contains(), overlaps().

Exemplo de código — Início rápido

use NextPDF\Enterprise\Common\BoundingBox;

$box = new BoundingBox(0.1, 0.1, 0.5, 0.2);
$inside = $box->contains(new BoundingBox(0.2, 0.15, 0.1, 0.02));

Exemplo de código — Produção

$region = new BoundingBox($x, $y, $w, $h); // throws on out-of-range input

if ($region->overlaps($redactionZone)) {
    $logger->info('common.overlap', ['area' => $region->area()]);
}

Casos extremos e armadilhas

• Construir com qualquer coordenada fora de [0.0, 1.0], ou com x + width / y + height acima de 1.0, lança um erro de argumento — valide as entradas a montante.
• Boxes de área zero nunca se sobrepõem; leve isso em conta ao calcular interseções.
• As coordenadas são normalizadas, não pixels; converta na fronteira de renderização.

Desempenho

Todas as operações são aritmética de tempo constante sobre quatro floats.

Notas de segurança

BoundingBox não realiza nenhuma I/O e não mantém nenhum conteúdo do documento. O construtor rejeita geometria fora do intervalo, impedindo que valores degenerados se propaguem para os módulos consumidores.

Residência de dados e mitigações de PII

Este módulo não mantém nenhum dado pessoal e não realiza nenhuma persistência ou I/O de rede. Considerações de residência não se aplicam.

Telemetria segura e limpeza de logs

As coordenadas e áreas de box são geometria não sensível e são seguras para registrar em log.

Conformidade

Este módulo não implementa nenhum padrão normativo e não faz nenhuma declaração de conformidade. Ele é uma primitiva de geometria.

Comportamento em modo FIPS

Este módulo não realiza nenhuma operação criptográfica; o modo FIPS não se aplica.

Modelo de ameaças

A única entrada são quatro floats. A validação de intervalo e de limites do construtor é a mitigação: uma geometria inválida não pode ser construída.

Contrato de comportamento

• BoundingBox é uma value object imutável cujas quatro coordenadas são normalizadas para o intervalo [0.0, 1.0] em relação às dimensões da página, tornando-a independente de resolução.
• O construtor valida que cada coordenada está dentro do intervalo e que x + width e y + height não excedem 1.0 (dentro de uma pequena tolerância de ponto flutuante), lançando um erro de argumento caso contrário.
• Ela expõe area(), contains() e overlaps(); boxes de área zero nunca se sobrepõem por definição.
• O módulo não realiza nenhuma I/O, não mantém nenhum conteúdo do documento e não faz nenhuma declaração de compliance ou conformidade.

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íquete estão fora do escopo.

Fallback do Core

Fallback do Core — nenhum; esta é uma primitiva de suporte compartilhada exclusiva do Enterprise. Ela não duplica nem substitui a geometria do Core e não tem equivalente no nível Core.

Fallback do Pro

Fallback do Pro — nenhum; este recurso não tem equivalente no nível Pro. A primitiva compartilhada BoundingBox é entregue apenas no pacote nextpdf/enterprise.

Nota sobre o limite do Enterprise

A primitiva de geometria validada é descrita no nível de comportamento. Ela é uma superfície de suporte exclusiva do Enterprise que outros módulos Enterprise consomem; não há submecanismos internos além do contrato documentado.

Limite de implantação

Limite de implantação — nenhum aplicável; este módulo não realiza nenhuma persistência, nenhuma I/O de rede e não mantém nenhum conteúdo de documento ou dado pessoal. Não há recurso de responsabilidade do operador para esta superfície.

Limite de conformidade legal

Nenhuma restrição de controle de exportação se aplica a esta superfície. O módulo não implementa nenhum padrão normativo e não faz nenhuma declaração de conformidade, certificação ou regulatória. Esta documentação não é um parecer jurídico.

Consulte também

• Validation — consome primitivas compartilhadas.
• Evidence — consome primitivas compartilhadas.
• Common — Referência profunda — referência profunda para as primitivas compartilhadas.