From 463d6c026dbaa1f59fb545f991a8d07c2676546f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lucas=20Garc=C3=ADa?= <lucas@codeccoop.org>
Date: Fri, 10 May 2024 11:33:19 +0200
Subject: [PATCH] feat: add readme.md

---
 README.md  | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 readme.txt |  33 -----------
 2 files changed, 168 insertions(+), 33 deletions(-)
 create mode 100644 README.md
 delete mode 100755 readme.txt

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..99e8227
--- /dev/null
+++ b/README.md
@@ -0,0 +1,168 @@
+# Wpct ERP Forms
+
+Bridge WP form builder plugins' submissions to remote backend over http requests.
+
+Wpct ERP Forms has integrations form [GravityForms](https://www.gravityforms.com) and [Contact Form 7](https://contactform7.com/).
+
+> Http requests will be sent with data encoded as `application/json` if there is no uploads. Else if form
+submission contains files, the default behavior is to send data as `multipart/formdata` encodec
+content type.
+
+## Installation
+
+Download the [latest release](https://git.coopdevs.org/codeccoop/wp/plugins/wpct-erp-forms/-/releases/permalink/latest/downloads/plugins/wpct-erp-forms.zip) as a zipfile.
+Once downloaded, decompress and place its content on your WP instance `wp-content/plugins`'s directory.
+
+> Go to the [releases](https://git.coopdevs.org/codeccoop/wp/plugins/wpct-erp-forms/-/releases) to find previous versions.
+
+You can install it with `wp-cli` with the next command:
+
+```shell
+wp plugin install https://git.coopdevs.org/codeccoop/wp/plugins/wpct-erp-forms/-/releases/permalink/latest/downloads/plugins/wpct-erp-forms.zip
+```
+
+## Dependencies
+
+* [WordPress](https://wordpress.org) >= 6.3.1
+* [Wpct Http Bridge](https://git.coopdevs.org/codeccoop/wp/plugins/wpct-http-bridge) >= 1.0.4
+
+## Settings
+
+Go to `Settings > Wpct ERP Forms` to manage plugin settings. This page has two main sections:
+
+1. General
+	* **Notification receiver**: Email address receiver of submission fails notifications.
+2. Rest API:
+	* **Endpoints**: A list of relations between forms and endpoints. With this list you can bind form submissions
+	to custom endpoints. Submission on forms not listed on this list will be ignored by the plugin.
+
+## Hooks
+
+### Filters
+
+#### `wpct_erp_forms_payload`
+
+Filter the submission data to be sent to the backend.
+
+Arguments:
+
+1. `array $payload`: Associative array with form submission data.
+2. `array $uploads`:Associative array with form submission uploaded files.
+3. `array $form`: Associative array with form object information.
+
+```php
+add_filter('wpct_erp_forms_payload', function ($payload, $uploads, $form) {
+	return $payload;
+}, 10, 3);
+```
+
+#### `wpct_erp_forms_submission_files`
+
+Filters uploaded files to be sent to the backend.
+
+Arguments:
+
+1. `array $uploads`: Associative array with form submission uploaded files.
+2. `array $form`: Associative array with form object information.
+
+Example:
+
+```php
+add_filter('wpct_erp_forms_submission_files', function ($uploads, $form) {
+	return $uploads;
+}, 10, 3);
+```
+#### `wpct_erp_forms_endpoints`
+
+Filters the endpoints array to be used for each submission.
+
+Arguments:
+1. `array $endpoints`: Positional array with endpoints as string values. It will trigger one http request for each
+endpoint on the list. _* Endpoints are relative to the **base_url** option defined on the options page of
+**Wpct HTTP Brdige**_.
+2. `array $payload`: Associative array with form submission data.
+3. `array $uploads`:  Associative array with form submission uploaded files.
+4. `array $form`: Associative array with form object information.
+
+Example:
+
+```php
+add_filter('wpct_erp_forms_endpoints', function ($endpoints, $payload, $files, $form) {
+	return $endpoints;
+}, 10, 4);
+```
+
+### Actions
+
+#### `wpct_erp_forms_before_submission`
+
+Action to do just before submission has been sent to the backend.
+
+Arguments:
+
+1. `array $payload`: Associative array with form submission data.
+2. `array $uploads`:Associative array with form submission uploaded files.
+3. `array $form`: Associative array with form object information.
+
+Example:
+
+```php
+add_action('wpct_erp_forms_before_submission', function ($payload, $files, $form) {
+	// do something
+}, 10, 3);
+```
+
+#### `wpct_erp_forms_after_submission`
+
+Action to do after the submission has been succesfuly sent to the backend.
+
+Arguments:
+
+1. `array $payload`: Associative array with form submission data.
+2. `array $uploads`:Associative array with form submission uploaded files.
+3. `array $form`: Associative array with form object information.
+
+Example:
+
+```php
+add_action('wpct_erp_forms_after_submission', function ($payload, $files, $form) {
+	// do something
+}, 10, 3);
+```
+#### `wpct_erp_forms_on_failure`
+
+Action to do after a request connexion error with the backend.
+
+Arguments:
+
+1. `array $payload`: Associative array with form submission data.
+2. `array $uploads`:Associative array with form submission uploaded files.
+3. `array $form`: Associative array with form object information.
+
+Example:
+
+```php
+add_action('wpct_erp_forms_on_failure', function ($payload, $files, $form) {
+	// do something
+}, 10, 3);
+```
+
+## Wpct HTTP Bridge
+
+This plugins needs [Wpct HTTP Bridge](https://git.coopdevs.org/codeccoop/wp/plugins/wpct-http-bridge/) to work.
+
+With this plugins hooks you can customize the submission http requests. See it's [README.md](https://git.coopdevs.org/codeccoop/wp/plugins/wpct-http-bridge/-/blob/main/README.md?ref_type=heads)
+for more information.
+
+Example:
+
+```php
+// Add Authorization header to the request befor its sent
+add_filter('wpct_http_headers', function ($headers, $method, $url) {
+	if ($url === '/custom/endpoints' && $method === 'POST') {
+		$headers['Authorization'] = 'Bearer ' . getenv('BACKEND_TOKEN');
+	}
+
+	return $headers;
+}, 10, 3);
+```
diff --git a/readme.txt b/readme.txt
deleted file mode 100755
index 27ce5e9..0000000
--- a/readme.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-=== Wpct ERP Forms ===
-Contributors: codeccoop, coopdevs
-Tags: forms, erp, crm
-Requires at least: 6.3.1
-Tested up to: 6.3.1
-Requires PHP: 8.0
-Stable tag: 1.0.0
-License: GPLv2 or later
-License URI: https://www.gnu.org/licenses/gpl-2.0.html
-
-Form submissions to ERP backends
-
-== Description ==
-
-Bridge WP form builder plugins' submissions to a ERP backend. The plugin should work with [WPCT Odoo Connect](https://git.coopdevs.org/coopdevs/website/wp/wp-plugins/wpct-odoo-connect) to perform http requests.
-
-The plugin has two integrations, with GravityForms and with Contactform7. Choose your preferred form builder.
-
-== Hooks ==
-
-Filters:
-* wpct_erp_forms_before_submission (array $submission, array $form) -> array $submission: Filter form submission
-* wpct_erp_forms_payload (array $payload) -> array $payload: Filter submission payload
-* wpct_erp_forms_endpoints (array $endpoints) -> array $endpoints: Filter endpoints array
-
-Actions:
-* wpct_erp_forms_on_failure (array $submission, array $form): Fired on submission failure
-* wpct_erp_forms_after_submission (array $submission, array $form): Fired on successfully submited
-
-== Changelog ==
-
-= 1.0.0 =
-* Initial commit before fork from [WPCT Forms CE](https://git.coopdevs.org/coopdevs/website/wp/wp-plugins/wpct-forms-ce)
-- 
GitLab