Contributing

Contributions to php-pdftk are highly encouraged! Whether you are fixing bugs, improving documentation, or ensuring compatibility with newer PHP versions, your help is welcome.

Development Environment Setup

To run the tests and static analysis tools locally, you will need:

  1. PHP 8.1 or higher.
  2. Composer installed globally.
  3. The pdftk binary installed on your local system (the test suite executes real PDF manipulations).
# 1. Clone the repository
git clone https://github.com/mikehaertl/php-pdftk.git
cd php-pdftk

# 2. Install dependencies (including dev tools)
composer install

Testing

The library uses PHPUnit for its testing framework. Before submitting a pull request, ensure that all existing tests pass.

To run the unit test suite: 

composer run test:unit

If you have Xdebug configured for coverage, you can generate a test coverage report: 

composer run test:coverage

Static Analysis

We utilize Psalm to enforce strict type checking and catch potential runtime errors statically.

To run Psalm across the codebase: 

composer run psalm

If you introduce code that intentionally violates a strict Psalm rule for a valid architectural reason, please discuss it in your Pull Request.

Coding Standards

The project strictly adheres to coding standards enforced by php-cs-fixer. Clean, consistent code makes the project easier to maintain.

To verify your code against the style guide (dry-run): 

composer run cs:check

To automatically fix formatting issues in your files: 

composer run cs:fix

For a fast syntax check (linting) across all PHP files to catch basic parse errors: 

composer run lint

Submitting a Pull Request

  1. Fork the repository and create a feature branch (git checkout -b feature/my-new-feature).
  2. Write clear, descriptive commit messages.
  3. Include tests for any new features or bug fixes.
  4. Run composer run test:unit, composer run psalm, and composer run cs:fix to ensure your build will pass CI.
  5. Open a Pull Request against the master branch, explaining the problem you are solving and your approach.