alfa-bank-sdk/CONTRIBUTING.md

Contributing to Alfa Bank SDK

Thank you for your interest in contributing to the unofficial Alfa Bank SDK! We welcome pull requests, bug reports, and feature requests.

Getting Started

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/your-username/alfa-bank-sdk.git
   cd alfa-bank-sdk
   

3. Install dependencies:

   composer install
   

Development Standards (Strict)

To maintain the "Enterprise Grade" quality of this SDK, all contributions must adhere to the following architectural rules:

1. Requests & Responses

• DTOs Only: Never pass raw arrays to a Request constructor. Always create a dedicated DTO in src/Data/....
• Strict Typing: All Request classes must implement the createDtoFromResponse(Response $response) method. Returning raw JSON is forbidden.
• Saloon v3: Follow Saloon PHP best practices.

2. Pagination

• If an endpoint returns a list (e.g. transactions, accounts), the Request class MUST:
  1. Implement Saloon\PaginationPlugin\Contracts\Paginatable.
  2. Use the Apoloz\AlfaBank\Traits\HasAlfaPagination trait.
  3. Return a Spatie\LaravelData\DataCollection in createDtoFromResponse.

3. Security

• No Secrets: Never commit real keys (.pem, .key, .pfx) or credentials.
• Crypto: Use the CmsSigner and JwsSigner utilities for cryptographic operations. Do not roll your own crypto logic.

Running Quality Checks

We use Pest for testing and PHPStan for static analysis.

# Run Unit & Feature Tests
vendor/bin/pest

# Run Static Analysis (Level 5)
vendor/bin/phpstan analyse

PRs with failing tests or PHPStan errors will not be merged.

Submitting a Pull Request

1. Create a new branch: git checkout -b feature/my-new-feature.
2. Write tests for your new feature (we aim for high coverage).
3. Commit changes with clear, descriptive messages.
4. Push to your fork and open a Pull Request against main.

Reporting Bugs

Please open an issue on GitHub with:

• A clear description of the bug.
• Minimal reproducible code example.
• SDK version and PHP version.

Thank you for helping improve this SDK!