diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72939af..abc2180 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,6 +76,11 @@ This will allow the Utopia-php community to have sufficient discussion about the This is also important for the Utopia-php lead developers to be able to give technical input and different emphasis regarding the feature design and architecture. Some bigger features might need to go through our [RFC process](https://github.com/appwrite/rfc). + +## Adding a New Adapter + +You can follow our [Adding new Payment Adapter tutorial](docs/tutorials/add-payment-adapter.md) to add new payment provider support in this library. + ## Other Ways to Help Pull requests are great, but there are many other areas where you can help Utopia-php. diff --git a/docs/tutorials/add-payment-adapter.md b/docs/tutorials/add-payment-adapter.md new file mode 100644 index 0000000..1a1808c --- /dev/null +++ b/docs/tutorials/add-payment-adapter.md @@ -0,0 +1,203 @@ +# Adding a new payment adapter 💾 + +This document is part of the Utopia contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](../../CODE_OF_CONDUCT.md) and the [Contributing Guide](../../CONTRIBUTING.md). + +## Getting started + +Payment adapters help developers process payments using payment providers. By adding a new payment provider, you will be able to use it to process payments. + +Utopia is and will always be tech-agnostic, meaning we are creating tools based on technologies you already use and love instead of creating a new toolset for you. With that in mind, we accept all contributions with adapters for any payment provider. + +## 1. Prerequisites + +It's really easy to contribute to an open source project, but when using GitHub, there are a few steps we need to follow. This section will take you step-by-step through the process of preparing your own local version of utopia-php/pay, where you can make any changes without affecting Utopia right away. + +> If you are experienced with GitHub or have made a pull request before, you can skip to [Implement new adapter](#2-implement-new-adapter). + +### 1.1 Fork the utopia-php/pay repository + +Before making any changes, you will need to fork Utopia's repository to keep branches on the official repo clean. To do that, visit the [utopia-php/pay Github repository](https://github.com/utopia-php/pay) and click on the fork button. + +This will redirect you from `github.com/utopia-php/pay` to `github.com/YOUR_USERNAME/pay`, meaning all changes you do will only be done inside your repository. Once you are there, click the highlighted `Code` button, copy the URL, and clone the repository to your computer using `git clone` command: + +```shell +$ git clone [COPIED_URL] +``` + +> To clone a repository, you will need a basic understanding of CLI and git-cli binaries installed. If you are a beginner, we recommend you to use `Github Desktop`. It is a really clean and simple visual Git client. + +Finally, you will need to create a `feat-ZZZ-adapter` branch based on the `main` branch and switch to it. Replace `ZZZ` with the adapter name. + +## 2. Implement new adapter + +### 2.1 Add adapter class + +Before implementing the adapter, please make sure to **not use any PHP library!** You will need to build app API calls using HTTP requests. + +Create a new file `XXX.php` where `XXX` is the name of the adapter in [`PascalCase`](https://stackoverflow.com/a/41769355/7659504) in this location +```bash +src/Pay/Adapter/XXX.php +``` + +Inside this file, create a new class that extends the abstract `Adapter` class. Note that the class name should start with a capital letter, as PHP FIG standards suggest. + +Once a new class is created, you can implement your new adapter's flow. We have prepared a starting point for the adapter class below, but you should also consider looking at other adapter implementations and try to follow the same standards. + +```php + If you copy this template, make sure to replace all `[THIS]` placeholders and to implement everything marked as `TODO:`. + +When implementing a new adapter, please make sure to follow these rules: + +- `getName()` needs to use the same name as the file name with the first letter lowercased. For example, in `Stripe.php`, we use `stripe`. + +Please mention in your documentation what resources or API docs you used to implement the provider's API. + +## 2. Test your adapter + +After you add your new adapter, you should write proper tests. To do that, create `tests/Pay/Adapter/[PROVIDER_NAME]Tests.php` and write tests for the provider. You can look at the tests written for the existing adapters for examples. + +To run the test, you can simply run + +```bash +composer test +``` + +## 4. Raise a pull request + +First of all, commit the changes with the message `Add XXX Adapter` (where `XXX` is adapter name) and push it. This will publish a new branch to your forked version of utopia-php/pay. If you visit `github.com/YOUR_USERNAME/pay`, you will see a new alert saying you are ready to submit a pull request. Follow the steps GitHub provides, and at the end, you will have your pull request submitted. + +## 🤕 Stuck ? + +If you need any help with the contribution, feel free to head over to the [Appwrite discord channel](https://appwrite.io/discord), and we'll be happy to help you out.