Enterprise edição

Common — Referência Profunda

Visão geral

Esta página é a referência aprofundada do namespace NextPDF\Enterprise\Common. O namespace distribui um único símbolo público: o objeto de valor BoundingBox. É um retângulo imutável e normalizado para posicionamento espacial independente de resolução em uma página. As superfícies Enterprise Intelligence e Privacy o consomem para geometria de células de tabela, localização de entidades e zonas de redação. O módulo não realiza I/O, não retém conteúdo de documento e não toca em criptografia. Para orientação de fluxo de trabalho, leia primeiro a página de capacidade Common.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

A primitiva em si não realiza nenhuma restrição de licença; a restrição ocorre nas superfícies Enterprise que a consomem. Não há equivalente de nível Core ou de nível Pro desta classe. Ela é distribuída apenas no pacote nextpdf/enterprise e não duplica nem substitui os tipos de geometria do Core.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`BoundingBox::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Valida cada valor em relação a `[0.0, 1.0]` e, em seguida, valida as duas somas de arestas	`BoundingBox`	`InvalidArgumentException` quando um valor está fora do intervalo ou uma soma de arestas excede `1.0 + 1e-9`	Os quatro valores tornam-se propriedades `public readonly`
`BoundingBox::area`	nenhum	Multiplica `width` por `height`	`float`	Nada declarado	Retorna `0.0` para caixas degeneradas
`BoundingBox::contains`	`self $other`	Testa se `$other` está totalmente dentro desta caixa	`bool`	Nada declarado	As arestas direita e inferior toleram `+1e-9`; as arestas esquerda e superior comparam exatamente
`BoundingBox::overlaps`	`self $other`	Testa uma interseção estrita de retângulos	`bool`	Nada declarado	Um operando de área zero em qualquer lado retorna `false`

Assinatura do ponto de entrada

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

Contrato de comportamento

Modelo de coordenadas

Os quatro valores são frações das dimensões da página, normalizados para o intervalo [0.0, 1.0].
x localiza a aresta esquerda e y localiza a aresta superior da caixa. x + width e y + height delimitam as arestas direita e inferior.
A normalização torna cada operação independente de resolução. A mesma caixa endereça a mesma região da página em qualquer tamanho de renderização ou DPI.

Construção

O construtor é o único ponto de validação. Uma coordenada fora de [0.0, 1.0] levanta InvalidArgumentException; a mensagem nomeia o componente infrator e o valor recebido.
Uma soma de arestas acima de 1.0 + 1e-9 levanta InvalidArgumentException; a mensagem informa ambos os operandos e sua soma. A tolerância de 1e-9 absorve o arredondamento de ponto flutuante da aritmética de normalização a montante.
Uma instância construída é imutável. A classe é final readonly, portanto escritas em propriedades falham com um Error do PHP e a classe não pode ser estendida.

Predicados

area() retorna width * height. É uma computação pura sem efeitos colaterais.
contains() retorna true quando a outra caixa está totalmente dentro desta caixa. As comparações das arestas direita e inferior carregam uma tolerância de +1e-9; as comparações das arestas esquerda e superior são exatas. Toda caixa contém a si mesma, e uma caixa de área zero pode ser contida.
overlaps() retorna true em uma interseção estrita de retângulos. As quatro comparações de arestas são estritas, sem tolerância. Se qualquer operando tiver área zero, o resultado é false.
Portanto, a contenção não implica sobreposição: uma caixa degenerada dentro de outra caixa está contida, mas nunca se sobrepõe.
Nenhum método realiza I/O, persistência, acesso à rede ou registro em log, e nenhum retém conteúdo de documento ou dado pessoal. Não há recurso sob responsabilidade do operador para esta superfície.

Consumidores

Os módulos Enterprise compartilham esta primitiva em vez de definir geometria por módulo. Em Intelligence, a saída de TableExtractor a carrega nos valores TableCell e KeyValuePair. Em Privacy, PiiEntity, RedactionFinding e ZoneRedaction localizam conteúdo com ela, e RedactionEngine consome essas localizações. Os contratos dessas superfícies estão documentados em suas próprias páginas de referência.

Casos extremos e modos de falha

Componente fora do intervalo. Qualquer um dos quatro valores abaixo de 0.0 ou acima de 1.0 levanta InvalidArgumentException na construção. INF e -INF são rejeitados pela mesma guarda.
Estouro da soma de arestas. x + width ou y + height acima de 1.0 + 1e-9 levanta InvalidArgumentException. Uma soma dentro da tolerância de 1e-9 constrói com sucesso.
Entrada NAN. A guarda de intervalo usa comparações ordenadas, e toda comparação ordenada com NAN é falsa, portanto um componente NAN não é rejeitado. Tal instância reporta uma área NAN e retorna false de ambos os predicados. Sanitize as fontes de float a montante antes da construção.
Caixas de área zero. Uma caixa com largura zero ou altura zero nunca se sobrepõe a nada, incluindo a si mesma. Ainda pode ser contida por uma caixa não degenerada. Considere essa assimetria na lógica de interseção.
Caixas que se tocam nas arestas. Duas caixas que compartilham apenas uma aresta ou um canto não se sobrepõem; o teste de interseção é estrito.
Assimetria de tolerância de contenção. Uma caixa interna cuja aresta esquerda ou superior fica fora da caixa externa por qualquer quantidade falha na contenção; apenas as arestas direita e inferior recebem a tolerância de 1e-9.
Modo FIPS. Este módulo não realiza nenhuma operação criptográfica; o modo FIPS não altera seu comportamento.

Conformidade

Este módulo não implementa nenhum padrão normativo e não faz nenhuma declaração de conformidade. É uma primitiva de geometria validada. A semântica do espaço de coordenadas do PDF para os recursos que a consomem está documentada nas páginas desses recursos. A NextPDF não detém nenhuma certificação e não concede nenhuma; suporte não é conformidade, e conformidade não é certificação. Nenhuma restrição de controle de exportação se aplica a esta superfície, e esta referência não é um parecer jurídico.

Notas de desenvolvimento

A classe está disponível desde o nextpdf/enterprise 2.2.0; sua superfície pública permanece inalterada no 3.1.0.
Converta coordenadas absolutas do espaço da página em frações relativas à página antes da construção. A classe valida intervalo, não semântica; ela não consegue detectar uma região plausível, porém incorreta.
As instâncias são objetos de valor simples e baratos de construir. Não as agrupe em pool nem as armazene em cache.
Duas instâncias com coordenadas idênticas comparam como iguais sob igualdade frouxa (==); a identidade estrita (===) as distingue. Prefira a comparação de coordenadas em testes.
Para geometria além dos predicados booleanos, derive as arestas das propriedades públicas: aresta direita x + width, aresta inferior y + height.
Ao testar os limites de tolerância, sonde ambos os lados de 1e-9 na guarda da soma de arestas e nas comparações de contenção das arestas direita/inferior.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora de escopo.