Contributing to php-seo

October 28, 2025 · View on GitHub

Thank you for considering contributing to php-seo! We welcome contributions from the community and are excited to work with you.

Code of Conduct
Getting Started
Development Setup
Making Changes
Testing
Code Style
Pull Request Process
Reporting Issues
Feature Requests

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Fork the repository on GitHub
Clone your fork locally
Set up the development environment
Create a new branch for your feature or fix
Make your changes
Test your changes
Submit a pull request

Development Setup

Prerequisites

PHP 8.2 or higher
Composer
Git

Installation

# Clone your fork
git clone https://github.com/YOUR_USERNAME/php-seo.git
cd php-seo

# Install dependencies
composer install

# Copy environment configuration (if needed)
cp .env.example .env

Development Tools

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Generate HTML coverage report
composer test-coverage-html

# Check code style
composer style

# Fix code style automatically
composer style-fix

# Run static analysis
composer analyze

# Run all quality checks
composer quality

Making Changes

Branch Naming

Use descriptive branch names:

feature/ai-provider-anthropic - for new features
fix/meta-tag-escaping - for bug fixes
docs/api-reference - for documentation updates
refactor/analyzer-architecture - for code refactoring

Commit Messages

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(ai): add Anthropic Claude provider support

Add support for Anthropic's Claude models via their API.
Includes rate limiting, error handling, and fallback support.

Closes #123

Testing

Test Requirements

This project maintains a 100% test pass rate with 405 passing tests and 1037 assertions. All contributions must:

✅ Write tests for all new functionality
✅ Ensure all existing tests continue to pass
✅ Maintain or improve test coverage
✅ Use descriptive test names
✅ Test both success and failure scenarios
✅ Include edge cases and error conditions

Writing Tests

All tests must pass before a PR can be merged. The project uses Pest testing framework.

Test Structure

<?php

test('it generates SEO title from page content', function () {
    $seoManager = new SeoManager();
    $content = '<h1>Welcome to Our Site</h1><p>Great content here.</p>';
    
    $seoManager->analyze($content);
    $title = $seoManager->generateTitle();
    
    expect($title)->toBeString()
        ->and($title)->not->toBeEmpty()
        ->and(strlen($title))->toBeLessThanOrEqual(60);
});

Running Tests

# Run all tests (must be 405 passing before PR submission)
composer test

# Run specific test file
./vendor/bin/pest tests/Unit/SeoManagerTest.php

# Run tests with coverage
composer test-coverage

# Run tests for a specific provider
./vendor/bin/pest --filter="OllamaProvider"

# Run tests with verbose output
./vendor/bin/pest --verbose

# Run quality checks (includes tests, style, and analysis)
composer quality

Test Coverage Status

Current test coverage:

405 tests passing (100% pass rate ✅)
1037 assertions validating functionality
Unit tests for all core components
Integration tests for Laravel & Symfony
AI provider tests for all supported platforms

Code Style

We follow PSR-12 coding standards with some additional rules:

PHP Standards

Use strict types: declare(strict_types=1);
Use type hints for all parameters and return types
Use proper PHPDoc comments
Follow PSR-4 autoloading standards

Code Organization

Keep classes focused and single-purpose
Use dependency injection
Prefer composition over inheritance
Write self-documenting code

Example

<?php

declare(strict_types=1);

namespace Rumenx\PhpSeo\Generators;

use Rumenx\PhpSeo\Config\SeoConfig;
use Rumenx\PhpSeo\Contracts\GeneratorInterface;

/**
 * Generator for creating SEO-optimized content.
 */
class ExampleGenerator implements GeneratorInterface
{
    public function __construct(
        private readonly SeoConfig $config
    ) {
    }

    /**
     * Generate content from page data.
     *
     * @param array<string, mixed> $pageData
     * @return string
     */
    public function generate(array $pageData): string
    {
        // Implementation here
    }
}

Pull Request Process

Before Submitting

Update documentation - Update README, CHANGELOG, or other docs if needed
Add tests - Ensure your changes are tested
Check quality - Run composer quality to verify everything passes
Update CHANGELOG - Add your changes to the unreleased section

Pull Request Template

## Description
Brief description of the changes.

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that causes existing functionality to change)
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] Added new tests for this change
- [ ] Updated existing tests

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] CHANGELOG updated