Contributing Guide for WAHA PHP Client

Thank you for your interest in contributing to this project! 🎉

📋 Table of Contents

How to Contribute
Reporting Bugs
Suggesting New Features
Pull Requests
Development Setup
Coding Standards
Testing
Commit Guidelines

🚀 How to Contribute

There are several ways you can contribute:

Report Bugs – Help us identify and fix issues.
Suggest Features – Recommend improvements or new functionality.
Submit Pull Requests – Contribute code directly.
Improve Documentation – Enhance or expand documentation.
Testing – Help test and review code.

🐛 Reporting Bugs

Before reporting a bug, please make sure:

✅ Check existing issues to avoid duplicates.
✅ Use the available issue template.
✅ Include detailed information:
- PHP version
- Package version (composer show orlinkzz/waha-php)
- Steps to reproduce the issue
- Expected behavior vs actual behavior
- Error messages or stack traces (if available)

Bug Report Template

**Bug Description**
A clear and concise description of the bug.

**Steps to Reproduce**
1. Set up environment '...'
2. Run code '...'
3. Observe the error

**Expected Behavior**
Describe what should happen.

**Actual Behavior**
Describe what actually happens.

**Environment**
- PHP Version: [e.g. 8.1.0]
- Package Version: [e.g. 1.0.0]
- OS: [e.g. Ubuntu 20.04]

**Additional Context**
Any other relevant information.

💡 Suggesting New Features

To suggest a new feature:

Open a GitHub Issue.
Use the enhancement label.
Clearly explain:
- The problem you are trying to solve.
- The proposed solution.
- Alternative solutions you have considered.
- Use cases and examples.

🔀 Pull Requests

Before Creating a Pull Request

Fork the repository and clone it locally.

Create a new branch from main:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Commit your changes with a clear message.

Push your branch:

git push origin feature/your-feature-name

Open a Pull Request targeting the main branch.

Branch Naming Convention

feature/feature-name – New features
fix/bug-description – Bug fixes
docs/documentation-update – Documentation changes
refactor/refactor-name – Refactoring work
test/test-name – Testing-related changes

Pull Request Checklist

Before submitting a PR, ensure:

Code follows the project's coding standards.
All tests pass (composer test).
No syntax errors exist.
Documentation has been updated if necessary.
Commit messages are clear and descriptive.
Your branch is up-to-date with main.
Changes have been tested locally.

Pull Request Template

## Description
Describe the changes you made.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
- [ ] Refactoring
- [ ] Testing

## Related Issues
Closes #(issue number)

## Testing
Describe how you tested your changes.

## Screenshots (if applicable)
Add screenshots for UI-related changes.

## Checklist
- [ ] My code follows the code style of this project
- [ ] My change requires documentation updates
- [ ] I have updated the documentation accordingly
- [ ] I have added tests covering my changes
- [ ] All new and existing tests pass

💻 Development Setup

Prerequisites

PHP 8.1 or higher
Composer
Git
Running WAHA instance (for testing)

Local Setup

Fork and clone the repository:

git clone https://github.com/your-username/waha-php.git
cd waha-php

Install dependencies:
```
composer install
```
Copy the environment file:
```
cp .env.example .env
```
Set up a WAHA instance:
- Install and run WAHA.
- Update your .env configuration accordingly.
Run tests:
```
composer test
```

Project Structure

waha-php/
├── src/
│   ├── Client/
│   ├── Database/
│   ├── Exceptions/
│   ├── Laravel/
│   ├── Message/
│   └── Queue/
├── tests/
├── database/
├── config/
└── docs/

📝 Coding Standards

PHP Standards

This project follows the PSR-12 coding standard:

Indentation: 4 spaces (no tabs)
Line Length: Maximum 120 characters
Braces: Opening braces on the same line as declarations
Visibility: Always declare visibility (public, protected, private)
Type Hints: Use parameter and return type declarations whenever possible

Code Style Example

<?php

namespace Orlinkzz\Waha;

use Orlinkzz\Waha\Client\WahaHttpClient;

class WahaClient
{
    private WahaHttpClient $http;

    public function __construct(
        private readonly WahaConfig $config
    ) {
        $this->http = new WahaHttpClient($config);
    }

    public function sendText(
        string $chatId,
        string $text,
        ?string $session = null
    ): array {
        // Implementation
    }
}

Naming Conventions

Classes: PascalCase (WahaClient, OutgoingMessage)
Methods: camelCase (sendText, getMessageLogs)
Variables: camelCase ($chatId, $sessionId)
Constants: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
Database Tables: snake_case (waha_sessions, waha_messages)

Documentation

Use PHPDoc for all public methods.
Include parameter and return types.
Add usage examples for complex functionality.

/**
 * Send a text message using the anti-ban flow.
 *
 * @param string $chatId WhatsApp chat ID (e.g. '628123456789@c.us')
 * @param string $text Message content
 * @param string|null $session Session name
 *
 * @return array Response from the WAHA API
 *
 * @throws WahaException If the API request fails
 *
 * @example
 * $client->sendText('628123456789@c.us', 'Hello!');
 */

🧪 Testing

Running Tests

# Run all tests
composer test

# Run tests with coverage
composer test-coverage

# Run a specific test file
vendor/bin/phpunit tests/DatabaseTest.php

Writing Tests

Every new feature should include tests.
Every bug fix should include a regression test.
Use descriptive test names.
Tests should be independent from each other.

Example Test

public function test_send_text_message_with_anti_banned_flow(): void
{
    $client = new WahaClient($this->config);

    $result = $client->sendText(
        '628123456789@c.us',
        'Test message'
    );

    $this->assertIsArray($result);
    $this->assertArrayHasKey('id', $result);
}

Test Coverage

Aim for at least 80% code coverage.
Focus on critical paths and edge cases.
Test error handling and exception scenarios.

📦 Commit Guidelines

Commit Message Format

Follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

feat – New feature
fix – Bug fix
docs – Documentation only
style – Formatting changes only
refactor – Code refactoring
test – Test additions or updates
chore – Maintenance and tooling updates

Examples

feat(client): add support for voice messages

fix(database): resolve connection timeout issue

docs(readme): add Laravel installation guide

refactor(client): simplify anti-ban flow

test(database): add session repository tests

Best Practices

Use imperative mood ("add" instead of "added").
Keep the subject line under 50 characters when possible.
Use the body section for detailed explanations.
Reference issues in the footer (Closes #123, Fixes #456).

👥 Code Review Process

For Contributors

Submit a pull request with a clear description.
Wait for maintainer review.
Address review feedback if requested.
Push updates to the same branch.
Wait for approval from at least one maintainer.

For Reviewers

Be respectful and constructive.
Focus on code quality rather than personal preference.
Explain the reasoning behind suggestions.
Approve when standards are met.

🤝 Community Guidelines

Code of Conduct

Be respectful – Respect all contributors.
Be constructive – Provide helpful feedback.
Be inclusive – Welcome contributors from all backgrounds.
Be patient – Everyone is learning.
Be collaborative – Work together toward better outcomes.

Communication

Use polite and professional language.
Avoid spam and excessive self-promotion.
Stay on topic in issues and pull requests.
Feel free to use emojis to keep communication friendly 😊

📞 Need Help?

If you need assistance:

Read the project documentation.
Check existing issues.
Open a discussion.
Contact the maintainer: @orlinkzz

🎉 Recognition

All contributors will be recognized through:

Contributors list
Release notes (for significant contributions)
Project acknowledgements

Thank you for contributing! 🙏

Every contribution, no matter how small, helps make this project better.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History