Bluem-WordPress and WooCommerce plug-in for Payment, Mandates, iDIN & IBAN-Name check
This is the developer repository and notes for the bluem WordPress and WooCommerce plug-in. The stable, production-ready version of the plug-in is available from the WordPress plug-in directory: wordpress.org/plugins/bluem/.
Use this repository to get insight and possibly contribute to the development of this plug-in.
This plug-in requires PHP >= 8.0.
If you use our plug-in files or databases in your own custom development, please disable auto-update and check each update manually before installing. Our plug-in files or database tables structure may change during time.
Work on the dev-master branch. This branch is used for development and testing. The master branch is locked and should only be used for production-ready releases
Run
make add_git_hooks
to enable git hooks, which will automatically run unit tests and CS linting (soon) before any commit.
- Also if you want to lint or use automatic lint-fixes, ensure that the PHP CS fixer is installed in the
tools
folder.
make unit_test
Your local environment (a WordPress website instance has to be running, at localhost:8000).
make acceptance_test
If you want to use this repository, follow the following steps to compile
- Download the contents of this repository as a ZIP file, or clone it to your computer
- Install Composer on your local machine
- Run the
composer update
command in the downloaded folder. This will generate avendor
folder and install all required dependencies and libraries. - Ensure the folder and its contents are located at the
./wp-content/plugins/bluem-woocommerce
path. (You could also compress the contents of this folder into a ZIP file and upload this into your site). - Your plug-in should now be visible within your WordPress plugin list. Activate the plug-in from this page
If possible, please run the installation procedure on a testing environment first, before installing the plug-in in a development environment.
If you are having trouble running the above commands, please contact us. We are glad to help or to provide a compiled version of the above See the Support section for instructions on how to do this.
Use the Bluem -> Settings page to configure the plug-in completely.
Please note: You have to activate the specific parts of the plug-in that you want to use. All separate services can be activated independently. By default, they are not activated.
See this example as how you could do this by adding a novel filter to the id bluem_woocommerce_enhance_mandate_request
:
add_filter('bluem_woocommerce_enhance_mandate_request', 'bluem_add_customer_name_to_mandate', 10, 1);
/**
* allow third parties to add additional data to the request object through this additional action
*
* @param [type] $request
* @return void
*/
function bluem_add_customer_name_to_mandate(
Bluem\BluemPHP\EmandateBluemRequest $request
)
{
global $current_user;
// or something like: $current_user->display_name;
$request->addAdditionalData("CustomerName", $current_user->user_login);
return $request;
}
See this example as how you could do this by adding a novel filter to the id bluem_woocommerce_enhance_payment_request
:
add_filter('bluem_woocommerce_enhance_payment_request', 'bluem_add_customer_name_to_payment', 10, 1);
/**
* allow third parties to add additional data to the request object through this additional action
*
* @param [type] $request
* @return void
*/
function bluem_add_customer_name_to_payment(
$request
)
{
global $current_user;
// or something like: $current_user->display_name;
$request->addAdditionalData("CustomerName", $current_user->user_login);
return $request;
}
By default, idin shortcode responses are simply saved but not validated to a user database.
The identification is also stored as-is, so there is no check on whether a name or other piece of information exactly matches. You still have to do that yourself, via a filter or a piece of code that you can work with like this. This is because the validation is expected to be very domain and customer specific.
You can find out if the validation was successful by using the following PHP code in a plug-in or template:
if(function_exists('bluem_idin_user_validated')) {
$validated = bluem_idin_user_validated();
if($validated) {
// validated
} else {
// not validated
}
}
These results can be obtained as an object by using the following PHP code in a plug-in or template:
if(function_exists('bluem_idin_retrieve_results')) {
$results = bluem_idin_retrieve_results();
// print, show or save the results
// for example:
echo $results->BirthDateResponse; // prints 1975-07-25
echo $results->NameResponse->LegalLastName; // prints Vries
}
Add a filter for id bluem_checkout_check_idin_validated_filter
if you want to add a filter to block the checkout procedure based on the IDIN validation procedure being completed.
If the injected function returns true, the checkout is enabled. If you return false, the checkout is blocked and a notice is shown.
Example that would block checkout if validation is not executed:
add_filter(
'bluem_checkout_check_idin_validated_filter',
'my_plugin_check_idin_validated_filter_function',
10,
1
);
function my_plugin_check_idin_validated_filter_function()
{
if (!bluem_idin_user_validated()) {
return false;
}
return true;
}
By default, this is disabled as it is quite context specific if the webshop is strict.
- delete
vendor/bluem-development/bluem-php/examples
to be sure as it is not necessary in production.
You can use our plug-in to initiate an eMandate transaction directly from, as example, within an App.
All u have to do is make a GET request to bluem-woocommerce/mandate_instant_request with the debtorreference
as query.
Make sure the debtorreference is unique and refers to an customer/user.
Set the return URI within the Bluem plug-in settings.
It is possible to include our eMandate-meganism in a page, by using the [bluem_machtigingsformulier]
shortcode.
Besides of the integration with WooCommerce, we also have integrations with the popular ContactForm 7 and Gravity Forms. Below you'll find the instructions to activate and use the integration.
- The integration(s) has to be enabled in the Bluem -> Settings page first before they will work.
To activate our ContactForm 7 integration, in the form settings, go to the tab additional settings. Enter the following codesnippets to active the flow:
bluem_mandate=true
bluem_mandate_reason="Mandate reason"
bluem_mandate_success="Bedankt voor het afgeven van de machtiging"
bluem_mandate_failure="De machtiging is mislukt. Probeer het opnieuw."
bluem_mandate_type="RCUR"
bluem_is_ajax=true
Also, add a checkbox with the name 'bluem_mandate_approve'. This will give the user-permission to perform the mandate request. Otherwise, the form will be submitted but our mandate request wouldn't be executed. U can mark the checkbox within ContactForm 7 as required to always force the mandate request after form submission.
To activate our Gravity Forms integration, you have to add some hidden fields to the form to activate the flow.
bluem_mandate=true
bluem_mandate_reason="Lidmaatschap"
bluem_mandate_success="Bedankt voor het afgeven van de machtiging"
bluem_mandate_failure="De machtiging is mislukt. Probeer het opnieuw."
bluem_mandate_type="OOFF"
Also, add a checkbox with the name 'bluem_mandate_approve' (under 'Advanced' section, after enabling dynamic entries) and a label with the value 'true'. This will give the user-permission to perform the mandate request. Otherwise, the form will be submitted but our mandate request wouldn't be executed. U can mark the checkbox within Gravity Forms as required to always force the mandate request after form submission.
Add a hidden field with this label and value to your form if the form is being called through AJAX.
bluem_is_ajax=true
Also, if you want to store additional transaction details, add hidden fields with the following field names. Our plug-in will fill these fields so that they are saved with the other form data. The transaction and details are always visible through our plug-in page.
bluem_mandate_accountname = Name of the accountholder
bluem_mandate_datetime = Date and time of registration
bluem_mandate_iban = IBAN of the account
bluem_mandate_request_id = MandateID
Our plug-in will store the above data in the fields with the corresponding names.
The Dockerfile within this package is used to run composer with a specific PHP version. Please follow the steps below to build a Docker environment and run composer.
- Build the Docker environment.
docker build -t my-php8-composer .
- Run composer in the created Docker environment.
docker run --rm -v $(pwd):/var/www my-php8-composer composer show
- Prepare plug-in dependencies before deployment.
docker run --rm -v $(pwd):/var/www my-php8-composer composer update --no-dev
If you have any questions, please email [email protected].
// @todo: add Woo Product update key if necessary, check https://docs.woocommerce.com/document/create-a-plugin/ // @todo: Localize all error messages to english primarily // @todo: finish docblocking // deprecate function bluem_db_create_link soon