[#9] added cancellation protection for recurring contributions

CRM/Twingle/Tools.php

@@ -0,0 +1,94 @@
+<?php
+/*------------------------------------------------------------+
+| SYSTOPIA Twingle Integration                                |
+| Copyright (C) 2019 SYSTOPIA                                 |
+| Author: B. Endres (endres@systopia.de)                      |
++-------------------------------------------------------------+
+| This program is released as free software under the         |
+| Affero GPL license. You can redistribute it and/or          |
+| modify it under the terms of this license which you         |
+| can read by viewing the included agpl.txt or online         |
+| at www.gnu.org/licenses/agpl.html. Removal of this          |
+| copyright header is strictly prohibited without             |
+| written permission from the original author(s).             |
++-------------------------------------------------------------*/
+
+use CRM_Twingle_ExtensionUtil as E;
+
+class CRM_Twingle_Tools {
+
+  /**
+   * This flag can be used to temporarily suspend twingle protection
+   * @var bool
+   */
+  public static $protection_suspended = FALSE;
+
+  /**
+   * Check if the attempted modification of the recurring contribution is allowed.
+   * If not, an exception will be raised
+   *
+   * @param $recurring_contribution_id int
+   * @param $change                    array
+   * @throws Exception if the change is not allowed
+   */
+  public static function checkRecurringContributionChange($recurring_contribution_id, $change) {
+    // check if a change to the status is planned
+    if (empty($change['contribution_status_id'])) return;
+
+    // check if the target status is not closed
+    if (in_array($change['contribution_status_id'], [2,5])) return;
+
+    // check if we're suspended
+    if (self::$protection_suspended) return;
+
+    // currently only works with prefixes
+    $prefix = CRM_Core_BAO_Setting::getItem('de.systopia.twingle', 'twingle_prefix');
+    if (empty($prefix)) return;
+
+    // check if protection is turned on
+    $protection_on = CRM_Core_BAO_Setting::getItem('de.systopia.twingle', 'twingle_protect_recurring');
+    if (empty($protection_on)) return;
+
+    // load the recurring contribution
+    $recurring_contribution = civicrm_api3('ContributionRecur', 'getsingle', [
+        'return' => 'trxn_id,contribution_status_id,payment_instrument_id',
+        'id'     => $recurring_contribution_id]);
+
+    // check if this is a SEPA transaction
+    //if (self::isSDD($recurring_contribution['payment_instrument_id'])) return;
+
+    // check if it's really a termination (i.e. current status is 2 or 5)
+    if (!in_array($recurring_contribution['contribution_status_id'], [2,5])) return;
+
+    // check if it's a Twingle contribution
+    if (substr($recurring_contribution['trxn_id'], 0, strlen($prefix)) == $prefix) {
+      // this is a Twingle contribution that is about to be terminated
+      throw new Exception(E::ts("This is a Twingle recurring contribution. It should be terminated through the Twingle interface, otherwise it will still be collected."));
+    }
+  }
+
+  /**
+   * Check if the given payment instrument is SEPA
+   *
+   * @param $payment_instrument_id string payment instrument
+   * @return boolean
+   */
+  public static function isSDD($payment_instrument_id) {
+    static $sepa_payment_instruments = NULL;
+    if ($sepa_payment_instruments === NULL) {
+      // init with instrument names
+      $sepa_payment_instruments = ['FRST', 'RCUR', 'OOFF'];
+
+      // lookup and add instrument IDs
+      $lookup = civicrm_api3('OptionValue', 'get', [
+          'option_group_id' => 'payment_instrument',
+          'name'            => ['IN' => $sepa_payment_instruments],
+          'return'          => 'value'
+      ]);
+      foreach ($lookup['values'] as $payment_instrument) {
+        $sepa_payment_instruments[] = $payment_instrument['value'];
+      }
+    }
+    return in_array($payment_instrument_id, $sepa_payment_instruments);
+  }
+}

api/v3/TwingleDonation/Cancel.php

@@ -122,12 +122,14 @@ function civicrm_api3_twingle_donation_Cancel($params) {
       ));
     }
     else {
+      CRM_Twingle_Tools::$protection_suspended = TRUE;
       $contribution = civicrm_api3($contribution_type, 'create', array(
         'id' => $contribution['id'],
         'cancel_date' => $params['cancelled_at'],
         'contribution_status_id' => 'Cancelled',
         'cancel_reason' => $params['cancel_reason'],
       ));
+      CRM_Twingle_Tools::$protection_suspended = FALSE;
     }
 
     $result = civicrm_api3_create_success($contribution);

api/v3/TwingleDonation/Endrecurring.php

@@ -113,11 +113,13 @@ function civicrm_api3_twingle_donation_endrecurring($params) {
       ));
     }
     else {
+      CRM_Twingle_Tools::$protection_suspended = TRUE;
       $contribution = civicrm_api3('ContributionRecur', 'create', array(
         'id' => $contribution['id'],
         'end_date' => $params['ended_at'],
         'contribution_status_id' => CRM_Twingle_Submission::CONTRIBUTION_STATUS_COMPLETED,
       ));
+      CRM_Twingle_Tools::$protection_suspended = FALSE;
     }
 
     $result = civicrm_api3_create_success($contribution);

settings/twingle.setting.php

@@ -31,6 +31,20 @@ return array(
     'is_contact' => 0,
     'description' => 'Whether to provide CiviSEPA functionality for manual debit payment method. This requires the CiviSEPA (org.project60.sepa) extension be installed.',
   ),
+  'twingle_protect_recurring' => array(
+      'group_name' => 'de.systopia.twingle',
+      'group' => 'de.systopia.twingle',
+      'name' => 'twingle_protect_recurring',
+      'type' => 'Boolean',
+      'quick_form_type' => 'YesNo',
+      'html_type' => 'radio',
+      'title' => 'Protect Recurring Contributions',
+      'default' => 0,
+      'add' => '4.6',
+      'is_domain' => 1,
+      'is_contact' => 0,
+      'description' => 'Will protect all recurring contributions created by Twingle from termination, since this does NOT terminate the Twingle collection process. Currently only works with a prefix',
+  ),
   'twingle_prefix' => array(
       'group_name' => 'de.systopia.twingle',
       'group' => 'de.systopia.twingle',

templates/CRM/Twingle/Form/Settings.hlp

@@ -16,6 +16,10 @@
     {ts domain="de.systopia.twingle" 1="<a href=\"https://github.com/project60/org.project60.sepa\" target=\"_blank\">CiviSEPA (<kbd>org.project60.sepa</kbd>) extension</a>"}When the %1 is enabled and one of its payment instruments is assigned to a Twingle payment method (practically the <em>debit_manual</em> payment method), submitting a Twingle donation through the API will create a SEPA mandate with the given data.{/ts}
 {/htxt}
 
+{htxt id='id-twingle_protect_recurring'}
+    {ts domain="de.systopia.twingle"}Will protect all recurring contributions created by Twingle from termination, since this does NOT terminate the Twingle collection process{/ts}
+{/htxt}
+
 {htxt id='id-twingle_prefix'}
     {ts domain="de.systopia.twingle"}You can use this setting to add a prefix to the Twingle transaction ID, in order to avoid collisions with other transaction ids.{/ts}
 {/htxt}

twingle.php

@@ -3,6 +3,15 @@
 require_once 'twingle.civix.php';
 use CRM_Twingle_ExtensionUtil as E;
 
+/**
+ * Implements hook_civicrm_pre().
+ */
+function twingle_civicrm_pre($op, $objectName, $id, &$params) {
+  if ($objectName == 'ContributionRecur' && $op == 'edit') {
+    CRM_Twingle_Tools::checkRecurringContributionChange($id, $params);
+  }
+}
+
 /**
  * Implements hook_civicrm_config().
  *