Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
170 lines (120 loc) · 3.83 KB

CONTRIBUTING.md

File metadata and controls

170 lines (120 loc) · 3.83 KB

Contributing to php-collective/dto

Thank you for considering contributing to the DTO library! This document provides guidelines and instructions for contributing.

Development Setup

  1. Clone the repository:

    git clone https://github.com/php-collective/dto.git
cd dto

  2. Install dependencies:

    composer install

  3. Verify your setup:

    composer check

Requirements

  • PHP 8.2 or higher
  • Composer

Code Style

This project follows PSR-12 with the PHPCollective ruleset. Before submitting code:

# Check for style violations
composer cs-check

# Auto-fix style issues
composer cs-fix

Running Tests

# Run all tests
composer test

# Run specific test file
vendor/bin/phpunit tests/Generator/BuilderTest.php

# Run specific test method
vendor/bin/phpunit --filter testBuildWithEnums

Static Analysis

The project uses PHPStan at level 8:

composer stan

Before Submitting a PR

Run all checks:

composer check

This runs both code style checks and tests. Additionally run:

composer stan

Pull Request Process

  1. Create a feature branch from master
  2. Make your changes
  3. Ensure all checks pass (composer check and composer stan)
  4. Write or update tests for your changes
  5. Update documentation if needed (especially README.md and docs/)
  6. Submit a pull request to master

Adding New Features

When adding new features:

  1. Add tests - Create test cases in tests/ mirroring the source structure
  2. Update documentation - Add or update docs in docs/ directory
  3. Consider backwards compatibility - Avoid breaking changes when possible

Test Fixtures

Test fixtures for generated DTOs are in tests/Generator/Fixtures/. When adding tests that require new DTO classes or enums, add them there.

Project Structure

src/
├── Config/        # Configuration builder classes
├── Dto/           # Base DTO classes (runtime)
├── Engine/        # Config parsers and validators
├── Generator/     # Code generation logic
├── Importer/      # JSON Schema/data importers
└── Utility/       # Helper utilities

tests/
├── Config/        # Config builder tests
├── Dto/           # DTO runtime tests
├── Engine/        # Parser/validator tests
├── Generator/     # Generation tests
│   └── Fixtures/  # Test DTO classes
├── Importer/      # Importer tests
└── Utility/       # Utility tests

docs/              # VitePress documentation site
├── .vitepress/    # VitePress config and theme
├── guide/         # Tutorial and guide pages
├── reference/     # API/CLI reference pages
└── public/        # Static assets (logo, images)

Documentation

The documentation site is built with VitePress and deployed to GitHub Pages.

Local Development

cd docs
npm install    # First time only
npm run docs:dev

This starts a dev server at http://localhost:5173/dto/ with hot reload.

Building

cd docs
npm run docs:build

Structure

  • docs/guide/ - Tutorials, configuration, patterns (kebab-case filenames)
  • docs/reference/ - CLI, TypeScript, Importer reference
  • docs/.vitepress/config.ts - Navigation and sidebar config
  • docs/index.md - Homepage

Adding/Editing Pages

  1. Add or edit markdown files in docs/guide/ or docs/reference/
  2. Add frontmatter with title: ---\ntitle: Page Title\n---
  3. Update sidebar in docs/.vitepress/config.ts if adding new pages
  4. Preview locally with npm run docs:dev

Reporting Issues

When reporting issues, please include:

  • PHP version
  • Library version
  • Minimal code example to reproduce
  • Expected vs actual behavior
  • Error messages (if any)

Questions?

Open an issue on GitHub for questions or discussions.