Contributing

We welcome contributions of all kinds — bug reports, documentation improvements, feature proposals, and code. This page summarises the process. For the full contributor agreement and detailed guidelines, see CONTRIBUTING.md on GitHub.

Development Setup

Prerequisites

Requirement	Minimum Version
PHP	8.5+
Composer	2.x
PHPUnit	12.x
PHPStan	2.x

Getting Started

# Clone the repository
git clone https://github.com/yeeefang/tcpdf-next.git
cd tcpdf-next

# Install dependencies
composer install

# Verify everything works
composer test

Running Tests

TCPDF-Next uses PHPUnit 12 with separate suites for unit and integration tests.

# Run the full test suite
composer test

# Run only unit tests (fast, no I/O)
composer test:unit

# Run only integration tests (file output, font loading, etc.)
composer test:integration

All tests must pass before a pull request can be merged. The CI pipeline runs the full suite on every push.

Static Analysis

The codebase is analysed with PHPStan at level 8 (the strictest level):

composer analyse

Zero errors are tolerated. If your change introduces a PHPStan error, the CI build will fail.

Code Style Requirements

• declare(strict_types=1) at the top of every PHP file.
• PHPStan level 8 compliance — no baseline exceptions for new code.
• readonly classes preferred wherever mutable state is not required.
• Backed enums for all finite sets of values (no magic strings or integer constants).
• Named parameters in public API methods for clarity.
• No mixed types — every parameter, return type, and property must be explicitly typed.
• Final by default — classes are final unless designed for extension.

Pull Request Process

1. Fork the repository and create a feature branch from main.

2. Write tests first — TCPDF-Next follows a TDD-oriented workflow. New features and bug fixes must include corresponding tests.

3. Keep commits focused — one logical change per commit. Write clear commit messages.

4. Run the full check suite before pushing:

   composer analyse && composer test

5. Open a pull request against main. Fill in the PR template with:

   • A description of the change and its motivation.
   • Links to related issues (use Closes #123 syntax).
   • Any breaking changes or migration notes.

6. Respond to review feedback — maintainers may request changes. Please address or discuss each comment.

Reporting Bugs

Open a GitHub Issue with:

• PHP version and OS.
• TCPDF-Next version (composer show yeeefang/tcpdf-next).
• Minimal reproduction code.
• Expected vs. actual behaviour.

Security Vulnerabilities

Do not report security issues via public GitHub Issues. Use GitHub Security Advisories instead. See the FAQ for details.

Thank You

Every contribution makes TCPDF-Next better. Whether you fix a typo in the docs or implement a major feature, your time and effort are genuinely appreciated.