Contributing to tc-lib-pdf

June 26, 2026 · View on GitHub

Thank you for your interest in contributing to tc-lib-pdf — the modern evolution of TCPDF. Contributions of all kinds are welcome: bug reports, bug fixes, documentation improvements, new features, and refactors.

Please take a moment to read this guide before opening an issue or pull request.

Pull requests are restricted to project collaborators. If you are not a collaborator, please open an issue instead of a pull request, describing the bug or feature in detail. A maintainer will review it and take it from there.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating you agree to abide by its terms. Please report unacceptable behaviour to info@tecnick.com.

Security Vulnerabilities

Do not open a public GitHub issue for security vulnerabilities.
Please follow the Security Policy and report them privately.

Getting Started

Requirements

  • PHP ≥ 8.2
  • Composer v2
  • make, git
  • Optional: rpmbuild (RPM packaging), dpkg-buildpackage (DEB packaging)

Local setup

git clone https://github.com/tecnickcom/tc-lib-pdf.git
cd tc-lib-pdf
make buildall

To verify everything is working after a change:

make qa

This runs linting, static analysis, and the full unit-test suite with coverage.

Reporting a Bug

Before opening an issue:

  1. Check the Security Policy — if the bug is a security vulnerability, do not file a public issue.
  2. Search existing issues to avoid duplicates.

If no existing issue matches, open a new one and include:

  • A clear title and description of the problem.
  • The library version (composer show tecnickcom/tc-lib-pdf) and PHP version.
  • A minimal, self-contained reproduction — a short PHP script or a failing PHPUnit test case is ideal.
  • Expected vs. actual behaviour — what you expected to happen and what actually happened.
  • Any relevant stack trace or error output.

The more precise and reproducible the report, the faster it can be triaged and fixed.

Submitting a Bug Fix

Only project collaborators can open pull requests. If you are not a collaborator, please open an issue describing the bug in detail (see Reporting a Bug). A maintainer will take it from there.

Collaborators preparing a fix:

  1. Create a branch from main: 
    git checkout -b fix/short-description-of-bug
  2. Make your changes, following the Coding Standards below.
  3. Add or update unit tests to cover the changes.
  4. Run the full quality-assurance suite locally and ensure it passes: 
    make qa
  5. Commit your changes (see Commit Message Guidelines).
  6. Open a pull request against main and fill in the PR template, describing the problem and your solution and referencing the related issue number (e.g. Fixes #123).

Proposing a New Feature

Before writing any code:

  1. Open a Feature Request on GitHub Issues describing the use case and proposed API.
  2. Wait for feedback from the maintainer. This avoids investing time in a direction that may not be accepted.

Once the feature is agreed upon, a collaborator will implement it following the same branch → code → test → pull request workflow as for bug fixes, using a branch named feature/short-description.

Development Workflow

The Makefile exposes all common development tasks:

CommandDescription
make qaRun linting, static analysis, tests, and reports
make testRun PHPUnit with code coverage
make lintCheck coding standards
make formatAuto-format the code
make buildallInstall dependencies, fix style, run QA, and build packages
make cleanRemove vendor/ and target/ directories
make serverStart the built-in PHP development server for the examples

Run make help to see the full list of available targets.

Coding Standards

  • The codebase follows PSR-12 for formatting.
  • Run make format to auto-format the code.
  • Run make lint to catch remaining issues.
  • All source files live under src/, all tests under test/.
  • Use strict types and explicit visibility on all class members.
  • Avoid introducing new external dependencies without prior discussion.

Testing

Tests are written with PHPUnit and live in test/.

# Run the full test suite with coverage
make test

# Run a specific test file
XDEBUG_MODE=coverage ./vendor/bin/phpunit test/HTMLTest.php

Requirements for contributions:

  • Every bug fix must be accompanied by a regression test that fails before the fix and passes after.
  • Every new feature must be accompanied by tests that cover both the happy path and edge cases.

Coverage reports are generated in target/coverage/.

Pull Request Guidelines

Opening pull requests is restricted to project collaborators. If you are an external contributor, please open an issue describing the problem or feature in detail instead.

  • Sign the Contributor License Agreement (CLA). On your first pull request the CLA Assistant bot will comment with a link to sign; the PR cannot be merged until the CLA is signed.
  • Target the main branch.
  • Keep PRs focused — one fix or feature per PR.
  • Ensure make qa passes locally before opening the PR.
  • Do not bump the version number in your PR; that is handled by the maintainer at release time.
  • Be responsive to review feedback; stale PRs may be closed after an extended period of inactivity.

Commit Message Guidelines

Use concise, imperative-mood commit messages:

fix: correct path traversal in font loader
feat: add support for CSS grid layout
test: add regression test for #123
docs: update CONTRIBUTING workflow
refactor: extract text measurement into helper

Prefix tags: fix, feat, test, docs, refactor, chore, ci.
Reference issues where relevant: fix: correct X (closes #42).

Questions?

If you have a question that is not covered here, feel free to open a GitHub Discussion or contact the maintainer at info@tecnick.com.