php-framework/CONTRIBUTING.md

Contributing to Core PHP Framework

Thank you for considering contributing to the Core PHP Framework! This document outlines the process and guidelines for contributing.

Code of Conduct

This project adheres to a code of conduct that all contributors are expected to follow. Be respectful, professional, and inclusive in all interactions.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When creating a bug report, include:

• Clear title and description
• Steps to reproduce the behavior
• Expected vs actual behavior
• PHP and Laravel versions
• Code samples if applicable
• Error messages and stack traces

Security Vulnerabilities

DO NOT open public issues for security vulnerabilities. Instead, email security concerns to: dev@host.uk.com

We take security seriously and will respond promptly to valid security reports.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

• Use a clear and descriptive title
• Provide a detailed description of the proposed feature
• Explain why this enhancement would be useful to most users
• List similar features in other frameworks if applicable

Pull Requests

1. Fork the repository and create your branch from main
2. Follow the coding standards (see below)
3. Add tests for any new functionality
4. Update documentation as needed
5. Ensure all tests pass before submitting
6. Write clear commit messages (see below)

Development Setup

Prerequisites

• PHP 8.2 or higher
• Composer
• Laravel 11 or 12

Setup Steps

# Clone your fork
git clone https://github.com/your-username/core-php.git
cd core-php

# Install dependencies
composer install

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

# Run migrations
php artisan migrate

# Run tests
composer test

Coding Standards

PSR Standards

• Follow PSR-12 coding style
• Use PSR-4 autoloading

Laravel Conventions

• Use Laravel's naming conventions for classes, methods, and variables
• Follow Laravel's directory structure patterns
• Use Eloquent for database interactions where appropriate

Code Style

We use Laravel Pint for code formatting:

./vendor/bin/pint

Run this before committing to ensure consistent code style.

PHP Standards

• Use strict typing: declare(strict_types=1);
• Add type hints for all method parameters and return types
• Use short array syntax: [] instead of array()
• Document complex logic with clear comments
• Avoid abbreviations in variable/method names

Testing

• Write feature tests for new functionality
• Write unit tests for complex business logic
• Aim for > 70% code coverage
• Use meaningful test names that describe what is being tested

public function test_user_can_create_workspace_with_valid_data(): void
{
    // Test implementation
}

Commit Message Guidelines

Format

type(scope): subject

body (optional)

footer (optional)

Types

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

Examples

feat(modules): add lazy loading for API modules

Implement lazy loading system that only loads API modules
when API routes are being registered, improving performance
for web-only requests.

Closes #123

fix(auth): resolve session timeout issue

Fix session expiration not being properly handled in multi-tenant
environment.

Fixes #456

Rules

• Use present tense: "add feature" not "added feature"
• Use imperative mood: "move cursor to..." not "moves cursor to..."
• Keep subject line under 72 characters
• Reference issue numbers when applicable
• Separate subject from body with a blank line

Package Development

Creating a New Package

New packages should follow this structure:

packages/
└── package-name/
    ├── src/
    ├── tests/
    ├── composer.json
    ├── README.md
    └── LICENSE

Package Guidelines

• Each package should have a clear, single purpose
• Include comprehensive tests
• Add a detailed README with usage examples
• Follow semantic versioning
• Document all public APIs

Testing Guidelines

Running Tests

# Run all tests
composer test

# Run specific test suite
./vendor/bin/phpunit --testsuite=Feature

# Run specific test file
./vendor/bin/phpunit tests/Feature/ModuleSystemTest.php

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage

Test Organization

• Feature tests: Test complete features end-to-end
• Unit tests: Test individual classes/methods in isolation
• Integration tests: Test interactions between components

Test Best Practices

• Use factories for creating test data
• Use database transactions to keep tests isolated
• Mock external services to avoid network calls
• Test edge cases and error conditions
• Keep tests fast and deterministic

Documentation

Code Documentation

• Add PHPDoc blocks for all public methods
• Document complex algorithms with inline comments
• Include usage examples in docblocks for key classes
• Keep documentation up-to-date with code changes

Example PHPDoc

/**
 * Create a new workspace with the given attributes.
 *
 * This method handles workspace creation including:
 * - Validation of input data
 * - Creation of default settings
 * - Assignment of owner permissions
 *
 * @param  array  $attributes  Workspace attributes (name, slug, settings)
 * @return \Core\Mod\Tenant\Models\Workspace
 * @throws \Illuminate\Validation\ValidationException
 */
public function create(array $attributes): Workspace
{
    // Implementation
}

Review Process

What We Look For

• Code quality: Clean, readable, maintainable code
• Tests: Adequate test coverage for new code
• Documentation: Clear documentation for new features
• Performance: No significant performance regressions
• Security: No security vulnerabilities introduced

Timeline

• Initial review typically within 1-3 business days
• Follow-up reviews within 1 business day
• Complex PRs may require additional review time

License

By contributing to the Core PHP Framework, you agree that your contributions will be licensed under the EUPL-1.2 license.

Questions?

If you have questions about contributing, feel free to:

• Open a GitHub Discussion
• Create an issue labeled "question"
• Email dev@host.uk.com

Thank you for contributing! 🎉