Referência de Interfaces
O módulo Contracts (TcpdfNext\Contracts) define as interfaces compartilhadas contra as quais todos os módulos TCPDF-Next programam. Ao depender de contratos em vez de classes concretas, você pode substituir test doubles, criar implementações alternativas e manter uma API pública estável entre versões principais.
PdfDocumentInterface
Namespace: TcpdfNext\Contracts\PdfDocumentInterface
O contrato principal da API implementado pelo Document. Qualquer classe que cumpra esta interface pode ser usada como substituição direta para o modelo de documento embutido.
Métodos
pageSize(PageSize $size): static
Definir o tamanho de página padrão para novas páginas.
orientation(Orientation $orientation): static
Definir a orientação de página padrão.
margin(Margin $margin): static
Definir as margens de página padrão.
metadata(?string $title = null, ?string $author = null, ?string $subject = null, ?string $keywords = null, ?string $creator = null): static
Definir metadados em nível de documento. Todos os parâmetros são opcionais; passe apenas os que deseja definir.
addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static
Adicionar uma nova página, opcionalmente substituindo os padrões para esta página.
font(string $family, float $size = 12.0, string $style = ''): static
Selecionar uma fonte por nome de família, tamanho e estilo.
text(string $content): static
Escrever uma linha de texto na posição atual do cursor.
output(OutputDestination $destination = OutputDestination::String, ?string $filename = null, ?string $path = null): string|bool
Renderizar o PDF para o destino escolhido.
currentPage(): int
Retornar o número da página atual (baseado em 1).
pageCount(): int
Retornar o número total de páginas.
Exemplo
php
use TcpdfNext\Contracts\PdfDocumentInterface;
use TcpdfNext\Contracts\OutputDestination;
function generateReport(PdfDocumentInterface $pdf): string
{
return $pdf
->addPage()
->font('Helvetica', size: 14)
->text('Quarterly Report')
->output(OutputDestination::String);
}FontManagerInterface
Namespace: TcpdfNext\Contracts\FontManagerInterface
Define carregamento de fontes, registro, subconjuntos e busca de métricas. O FontManager embutido implementa esta interface, mas você pode fornecer uma implementação customizada para fontes de fontes especializadas.
Métodos
registerFont(string $path, string $alias = ''): static
Registrar um arquivo de fonte TrueType ou OpenType. Se alias estiver vazio, o nome da família da fonte do arquivo é usado.
hasFont(string $family, string $style = ''): bool
Verificar se uma combinação de família e estilo de fonte está disponível.
getFont(string $family, string $style = ''): FontInfo
Retornar um objeto FontInfo readonly com métricas para a fonte especificada.
stringWidth(string $text, string $family, float $size, string $style = ''): float
Calcular a largura de uma string em unidades do usuário.
subset(string $family, string $style, string $chars): string
Criar um binário de fonte subconjunto contendo apenas os glifos necessários para os caracteres fornecidos.
registeredFamilies(): array
Retornar uma lista de todos os nomes de famílias de fontes registradas.
Exemplo
php
use TcpdfNext\Contracts\FontManagerInterface;
function addCustomFonts(FontManagerInterface $fonts): void
{
$fonts->registerFont('/fonts/NotoSans-Regular.ttf', 'NotoSans');
$fonts->registerFont('/fonts/NotoSans-Bold.ttf', 'NotoSans');
if ($fonts->hasFont('NotoSans', 'B')) {
$info = $fonts->getFont('NotoSans', 'B');
echo "Ascender: {$info->ascender}";
}
}SignerInterface
Namespace: TcpdfNext\Contracts\SignerInterface
Define o contrato para qualquer provedor de assinatura digital. Implemente esta interface para integrar com certificados de software, cofres de chaves baseados em nuvem ou módulos de segurança de hardware (HSMs).
Métodos
sign(string $data): string
Assinar os dados fornecidos e retornar os bytes brutos da assinatura CMS/CAdES.
certificate(): string
Retornar o certificado de assinatura codificado em DER.
chain(): array
Retornar um array de certificados intermediários codificados em DER (do assinante à raiz).
estimatedSize(): int
Retornar o tamanho máximo estimado (em bytes) da assinatura. Usado para pré-alocar o placeholder ByteRange.
algorithm(): string
Retornar o OID ou nome do algoritmo de assinatura (ex: 'sha256WithRSAEncryption').
Exemplo
php
use TcpdfNext\Contracts\SignerInterface;
class FileSigner implements SignerInterface
{
public function __construct(
private readonly string $certPath,
private readonly string $keyPath,
private readonly string $password,
) {}
public function sign(string $data): string
{
$cert = file_get_contents($this->certPath);
$key = openssl_pkey_get_private(
file_get_contents($this->keyPath),
$this->password,
);
openssl_pkcs7_sign(/* ... */);
// Return raw signature bytes
}
public function certificate(): string { /* ... */ }
public function chain(): array { return []; }
public function estimatedSize(): int { return 8192; }
public function algorithm(): string { return 'sha256WithRSAEncryption'; }
}HsmSignerInterface
Namespace: TcpdfNext\Contracts\HsmSignerInterface
Estende SignerInterface para módulos de segurança de hardware que nunca expõem a chave privada. Em vez de assinar dados brutos, o HSM assina um digest pré-computado.
Métodos
Todos os métodos de SignerInterface, mais:
signDigest(string $digest, string $algorithm): string
Assinar um digest de mensagem pré-computado. O parâmetro algorithm identifica o hash usado (ex: 'sha256').
Exemplo
php
use TcpdfNext\Contracts\HsmSignerInterface;
class AwsCloudHsmSigner implements HsmSignerInterface
{
public function __construct(
private readonly string $keyId,
private readonly AwsKmsClient $kms,
private readonly string $certPem,
) {}
public function sign(string $data): string
{
$digest = hash('sha256', $data, binary: true);
return $this->signDigest($digest, 'sha256');
}
public function signDigest(string $digest, string $algorithm): string
{
$result = $this->kms->sign([
'KeyId' => $this->keyId,
'Message' => $digest,
'MessageType' => 'DIGEST',
'SigningAlgorithm' => 'RSASSA_PKCS1_V1_5_SHA_256',
]);
return $result['Signature'];
}
public function certificate(): string { return $this->certPem; }
public function chain(): array { return []; }
public function estimatedSize(): int { return 16384; }
public function algorithm(): string { return 'sha256WithRSAEncryption'; }
}Usando Interfaces para Testes
Todas as quatro interfaces são projetadas para serem facilmente mocáveis com PHPUnit ou Mockery.
php
use PHPUnit\Framework\TestCase;
use TcpdfNext\Contracts\FontManagerInterface;
class TextRendererTest extends TestCase
{
public function testCalculatesWidth(): void
{
$fonts = $this->createMock(FontManagerInterface::class);
$fonts->method('hasFont')->willReturn(true);
$fonts->method('stringWidth')
->with('Hello', 'Helvetica', 12.0, '')
->willReturn(26.64);
$renderer = new TextRenderer($fonts);
$this->assertEqualsWithDelta(26.64, $renderer->width('Hello'), 0.01);
}
}Veja Também
- Visão Geral da API -- Todos os pacotes em resumo
- Referência de Enums -- Enums usados por estas interfaces (Orientation, Alignment, OutputDestination)
- API do Document -- A classe concreta que implementa PdfDocumentInterface
- Guia de Segurança -- Guia completo de criptografia e assinaturas digitais