forked from apoloz/alfa-bank-sdk
65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
# 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:
|
|
```bash
|
|
git clone https://github.com/your-username/alfa-bank-sdk.git
|
|
cd alfa-bank-sdk
|
|
```
|
|
3. **Install dependencies**:
|
|
```bash
|
|
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](https://docs.saloon.dev) 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.
|
|
|
|
```bash
|
|
# 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! |