Contributing - Mangopay PHP SDK

We welcome contributions to the Mangopay PHP SDK! This guide will help you get started with contributing to the project.

Ways to Contribute

Report Bugs

Found an issue? Report it on GitHub Issues.

Suggest Features

Have an idea? Open a feature request.

Submit Code

Fix bugs or add features via pull requests.

Improve Documentation

Help make our docs better.

Getting Started

Prerequisites

Before contributing, ensure you have:

PHP 5.6 or higher (PHP 8.1+ recommended for development)
Composer for dependency management
Git for version control
A Mangopay sandbox account for testing
PHPUnit for running tests

Setting Up Development Environment

1. Fork and Clone the Repository

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/mangopay4-php-sdk.git
cd mangopay4-php-sdk

# Add upstream remote
git remote add upstream https://github.com/Mangopay/mangopay4-php-sdk.git

2. Install Dependencies

composer install

3. Configure Test Environment

Create a configuration file for tests:

// tests/config.php (create this file)
<?php

return [
    'clientId' => 'your-sandbox-client-id',
    'clientPassword' => 'your-sandbox-api-key',
    'baseUrl' => 'https://api.sandbox.mangopay.com',
    'temporaryFolder' => '/tmp/mangopay-tests/'
];

Never commit your real credentials! Add tests/config.php to .gitignore.

Development Workflow

Creating a Branch

Create a new branch for your work:

# Update your local repository
git fetch upstream
git checkout master
git merge upstream/master

# Create a feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/issue-description

Making Changes

Code Style Guidelines

The project follows PSR-4 and PSR-12 standards: File Structure:

MangoPay/
├── Libraries/          # Core library files
├── Tools/             # Helper tools
└── [Entity].php       # Entity classes (User, Wallet, etc.)

Naming Conventions:

<?php

namespace MangoPay;

// Class names: PascalCase
class UserNatural extends User
{
    // Properties: PascalCase (Mangopay convention)
    public $FirstName;
    public $LastName;
    public $Email;
    
    // Methods: PascalCase (Mangopay convention)
    public function GetFullName()
    {
        return $this->FirstName . ' ' . $this->LastName;
    }
}

Formatting:

Use 4 spaces for indentation (no tabs)
Opening braces on the same line for methods
One blank line between methods
No trailing whitespace

Documentation: Add PHPDoc comments for all classes and methods:

/**
 * Creates a new natural user
 * @param UserNatural $user The user to create
 * @return UserNatural The created user with ID
 * @throws Libraries\ResponseException
 */
public function CreateNatural($user)
{
    return $this->CreateObject('users_createnaturals', $user, '\MangoPay\UserNatural');
}

Writing Tests

All new features and bug fixes should include tests.

Test Structure

<?php

namespace MangoPay\Tests\Cases;

use MangoPay\UserNatural;

class MyFeatureTest extends Base
{
    public function test_MyFeature_WorksCorrectly()
    {
        // Arrange
        $user = new UserNatural();
        $user->FirstName = "John";
        $user->LastName = "Doe";
        $user->Email = "[email protected]";
        $user->Birthday = mktime(0, 0, 0, 12, 21, 1985);
        $user->Nationality = "GB";
        $user->CountryOfResidence = "GB";
        
        // Act
        $createdUser = $this->_api->Users->Create($user);
        
        // Assert
        $this->assertNotNull($createdUser->Id);
        $this->assertEquals("John", $createdUser->FirstName);
        $this->assertEquals("Doe", $createdUser->LastName);
    }
    
    public function test_MyFeature_HandlesErrors()
    {
        // Test error scenarios
        $this->expectException(\MangoPay\Libraries\ResponseException::class);
        
        $invalidUser = new UserNatural();
        // Missing required fields
        $this->_api->Users->Create($invalidUser);
    }
}

Running Tests

# Run all tests
vendor/bin/phpunit tests/

# Run specific test file
vendor/bin/phpunit tests/Cases/UsersTest.php

# Run specific test method
vendor/bin/phpunit --filter test_Users_CreateNatural tests/Cases/UsersTest.php

Using Docker for Tests

The project includes Docker configurations for testing across PHP versions:

# Build and run tests in PHP 7.4
docker-compose -f docker-compose.php74.yml up --build

# PHP 8.0
docker-compose -f docker-compose.php80.yml up --build

# PHP 8.1
docker-compose -f docker-compose.php81.yml up --build

Committing Changes

Commit Message Format

Use clear, descriptive commit messages:

# Good commit messages
git commit -m "Add support for ChargeBearer parameter on payouts"
git commit -m "Fix null reference in PendingUserAction"
git commit -m "Update tests for PHP 8.2 compatibility"

# Poor commit messages (avoid these)
git commit -m "fix bug"
git commit -m "update"
git commit -m "changes"

Commit Message Structure

<type>: <subject>

<body>

<footer>

Types:

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

Example:

feat: Add support for Bizum PayIn

Implements the new Bizum payment method as per API release note.

- Add BizumPayIn class
- Add CreateBizumPayIn method to ApiPayins
- Include tests for Bizum PayIn flow

Closes #123

Pull Request Process

Before Submitting

Ensure all tests pass:
```
vendor/bin/phpunit tests/
```

Check code style:

# If you have PHP_CodeSniffer installed
phpcs --standard=PSR12 MangoPay/

Update documentation if needed
Update CHANGELOG.md (for significant changes)

Submitting a Pull Request

Push your changes:

git push origin feature/your-feature-name

Create a Pull Request on GitHub
Fill out the PR template with:
- Description of changes
- Related issue number (if applicable)
- Type of change (bug fix, feature, etc.)
- Checklist completion
Wait for review - maintainers will review your PR

Pull Request Template

## Description
Brief description of what this PR does.

## Related Issue
Fixes #(issue number)

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
Describe the tests you ran and how to reproduce them.

## Checklist
- [ ] My code follows the project's code style
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

Reporting Issues

Bug Reports

When reporting a bug, please include:

SDK Version: Which version are you using?
PHP Version: Output of php -v
Environment: Sandbox or Production
Description: Clear description of the issue
Steps to Reproduce: Detailed steps to reproduce the bug
Expected Behavior: What you expected to happen
Actual Behavior: What actually happened
Code Sample: Minimal code that reproduces the issue (remove credentials!)
Error Messages: Full error message and stack trace

Template:

## Bug Description
A clear description of the bug.

## Environment
- SDK Version: 3.50.1
- PHP Version: 8.1.0
- Environment: Sandbox

## Steps to Reproduce
1. Create a user with...
2. Call method...
3. See error

## Expected Behavior
The method should return...

## Actual Behavior
Instead, it throws...

## Code Sample
```php
$api = new MangoPayApi();
// Your code here (remove credentials!)

Error Message

Full error message and stack trace


### Feature Requests

For feature requests, please include:

1. **Use Case:** Why do you need this feature?
2. **Current Workaround:** How are you handling this now?
3. **Proposed Solution:** How you envision the feature working
4. **API Support:** Does the Mangopay API already support this?

## Code Review Process

### What We Look For

- **Correctness:** Does the code work as intended?
- **Tests:** Are there adequate tests?
- **Documentation:** Is the code well-documented?
- **Style:** Does it follow project conventions?
- **Backwards Compatibility:** Does it break existing code?
- **Performance:** Are there any performance concerns?

### Response Time

Maintainers typically respond to PRs within:
- **Initial review:** 1-2 weeks
- **Follow-up reviews:** 3-5 business days

## Release Process

### Version Numbering

The SDK follows [Semantic Versioning](https://semver.org/):

- **Major version (X.0.0):** Breaking changes
- **Minor version (0.X.0):** New features (backwards compatible)
- **Patch version (0.0.X):** Bug fixes (backwards compatible)

### Release Checklist

For maintainers preparing a release:

1. Update version in `composer.json`
2. Update `CHANGELOG.md`
3. Run full test suite
4. Create release tag
5. Publish to Packagist
6. Update GitHub release notes

## Community Guidelines

### Code of Conduct

- Be respectful and inclusive
- Focus on constructive feedback
- Assume good intentions
- No harassment or discrimination

### Getting Help

- **Questions:** Use GitHub Discussions
- **Bugs:** Open a GitHub Issue
- **Security Issues:** Email [email protected] (do not open public issues)

## Recognition

Contributors are recognized in:

- GitHub Contributors page
- CHANGELOG.md (for significant contributions)
- Release notes

## Additional Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/Mangopay/mangopay4-php-sdk">
    View source code and issues
  </Card>
  <Card title="API Documentation" icon="book" href="https://docs.mangopay.com">
    Mangopay API reference
  </Card>
  <Card title="Packagist" icon="box" href="https://packagist.org/packages/mangopay4/php-sdk">
    PHP package repository
  </Card>
  <Card title="Changelog" icon="clock" href="/resources/changelog">
    Version history
  </Card>
</CardGroup>

## License

By contributing to the Mangopay PHP SDK, you agree that your contributions will be licensed under the MIT License.

<Note>
Thank you for contributing to the Mangopay PHP SDK! Your contributions help improve the experience for developers worldwide.
</Note>

Additional Resources

​Ways to Contribute

Report Bugs

Suggest Features

Submit Code

Improve Documentation

​Getting Started

​Prerequisites

​Setting Up Development Environment

​1. Fork and Clone the Repository

​2. Install Dependencies

​3. Configure Test Environment

​Development Workflow

​Creating a Branch

​Making Changes

​Code Style Guidelines

​Writing Tests

​Test Structure

​Running Tests

​Using Docker for Tests

​Committing Changes

​Commit Message Format

​Commit Message Structure

​Pull Request Process

​Before Submitting

​Submitting a Pull Request

​Pull Request Template

​Reporting Issues

​Bug Reports

​Error Message

Build docs developers (and LLMs) love

Ways to Contribute

Getting Started

Prerequisites

Setting Up Development Environment

1. Fork and Clone the Repository

2. Install Dependencies

3. Configure Test Environment

Development Workflow

Creating a Branch

Making Changes

Code Style Guidelines

Writing Tests

Test Structure

Running Tests

Using Docker for Tests

Committing Changes

Commit Message Format

Commit Message Structure

Pull Request Process

Before Submitting

Submitting a Pull Request

Pull Request Template

Reporting Issues

Bug Reports

Error Message