Справочник интерфейсов
Модуль Contracts (TcpdfNext\Contracts) определяет общие интерфейсы, которым следуют все модули TCPDF-Next. Зависимость от контрактов, а не от конкретных классов, позволяет подставлять тестовые дублёры, создавать альтернативные реализации и поддерживать стабильный публичный API между мажорными версиями.
PdfDocumentInterface
Namespace: TcpdfNext\Contracts\PdfDocumentInterface
Основной API-контракт, реализуемый классом Document. Любой класс, удовлетворяющий этому интерфейсу, может использоваться как прямая замена встроенной модели документа.
Методы
pageSize(PageSize $size): static
Установить размер страницы по умолчанию для новых страниц.
orientation(Orientation $orientation): static
Установить ориентацию по умолчанию.
margin(Margin $margin): static
Установить поля страницы по умолчанию.
metadata(?string $title = null, ?string $author = null, ?string $subject = null, ?string $keywords = null, ?string $creator = null): static
Установить метаданные на уровне документа. Все параметры опциональны; передавайте только те, которые хотите установить.
addPage(?PageSize $pageSize = null, ?Orientation $orientation = null): static
Добавить новую страницу, опционально переопределив значения по умолчанию для этой страницы.
font(string $family, float $size = 12.0, string $style = ''): static
Выбрать шрифт по имени семейства, размеру и стилю.
text(string $content): static
Записать строку текста в текущей позиции курсора.
output(OutputDestination $destination = OutputDestination::String, ?string $filename = null, ?string $path = null): string|bool
Отрендерить PDF в выбранное назначение.
currentPage(): int
Вернуть номер текущей страницы (1-базированный).
pageCount(): int
Вернуть общее количество страниц.
Пример
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
Определяет загрузку, регистрацию, подмножественное встраивание и поиск метрик шрифтов. Встроенный FontManager реализует этот интерфейс, но вы можете предоставить пользовательскую реализацию для специализированных источников шрифтов.
Методы
registerFont(string $path, string $alias = ''): static
Зарегистрировать файл шрифта TrueType или OpenType. Если alias пуст, используется имя семейства шрифта из файла.
hasFont(string $family, string $style = ''): bool
Проверить, доступна ли комбинация семейства шрифта и стиля.
getFont(string $family, string $style = ''): FontInfo
Вернуть readonly-объект FontInfo с метриками для указанного шрифта.
stringWidth(string $text, string $family, float $size, string $style = ''): float
Вычислить ширину строки в пользовательских единицах.
subset(string $family, string $style, string $chars): string
Создать бинарные данные подмножества шрифта, содержащего только глифы, необходимые для указанных символов.
registeredFamilies(): array
Вернуть список всех зарегистрированных имён семейств шрифтов.
Пример
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
Определяет контракт для любого провайдера цифровой подписи. Реализуйте этот интерфейс для интеграции с программными сертификатами, облачными хранилищами ключей или аппаратными модулями безопасности (HSM).
Методы
sign(string $data): string
Подписать переданные данные и вернуть сырые байты подписи CMS/CAdES.
certificate(): string
Вернуть DER-кодированный сертификат подписанта.
chain(): array
Вернуть массив DER-кодированных промежуточных сертификатов (от подписанта до корня).
estimatedSize(): int
Вернуть оценочный максимальный размер подписи (в байтах). Используется для предварительного выделения плейсхолдера ByteRange.
algorithm(): string
Вернуть OID или имя алгоритма подписи (например, 'sha256WithRSAEncryption').
Пример
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
Расширяет SignerInterface для аппаратных модулей безопасности, которые никогда не раскрывают приватный ключ. Вместо подписания сырых данных HSM подписывает предварительно вычисленный дайджест.
Методы
Все методы из SignerInterface, плюс:
signDigest(string $digest, string $algorithm): string
Подписать предварительно вычисленный дайджест сообщения. Параметр algorithm идентифицирует использованный хеш (например, 'sha256').
Пример
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'; }
}Использование интерфейсов для тестирования
Все четыре интерфейса спроектированы для лёгкого мокирования с помощью PHPUnit или 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);
}
}См. также
- Обзор API -- Все пакеты одним взглядом
- Справочник Enums -- Enum-ы, используемые этими интерфейсами (Orientation, Alignment, OutputDestination)
- API документа -- Конкретный класс, реализующий PdfDocumentInterface
- Руководство по безопасности -- Полное руководство по шифрованию и цифровым подписям