CIVIMUTIL-8 Version 1.3.4. New feature - Set Membership End Date to e…

…nd of the month; update README; civix upgrade. Update Settings page.
agileware · Jan 25, 2024 · 9e67d4f · 9e67d4f
1 parent d443c66
commit 9e67d4f
Show file tree

Hide file tree

Showing 11 changed files with 240 additions and 460 deletions.
diff --git a/README.md b/README.md
@@ -3,15 +3,17 @@
 [Membership Utils](https://github.com/agileware/au.com.agileware.membershiputils) is a CiviCRM extension providing some useful functions to help manage memberships in [CiviCRM](https://civicrm.org), including:
 1. Membership Statuses: 'Duplicate' and 'Not Renewing'
 2. Scheduled Job, `Find Duplicate Memberships` which finds duplicate Memberships and sets the status to 'Duplicate'.
-3. Feature to automatically adjust the membership end date to the end of the month. For example: a membership with an end date of 16/04/2022 will be changed to 30/04/2022. This feature is useful if you want to have all membership end dates occur on the last day of the month, rather than the default which is mid-month.
-4. Scheduled Job, `Adjust Membership End Date` which updates the membership end date for all membership, setting the end date to the end of month.
+3. Feature to automatically adjust the **membership end date** to the **end of the month** when creating or updating a membership. For example: a membership with an end date of 16/04/2022 will be changed to 30/04/2022. This feature is useful if you want to have all membership end dates occur on the last day of the month, rather than the default which is mid-month.
+4. Feature to automatically **set the membership end date** to a **specific date** when creating or updating a membership. 
+5. Scheduled Job, `Adjust Membership End Date` which sets the membership end date to the end of month.
+6. Scheduled Job, `Set specific Membership End Date` which sets the membership end date to a specific date.
 
 ## Duplicate Memberships
 
 Duplicate memberships in CiviCRM is a major issue for Membership Managers and the `Find Duplicate Memberships` job alleviates this issue by automatically changing the membership status of duplicate memberships to *Duplicate*. A membership is deemed to be a duplicate if:
 1. The membership is of the same membership type
 2. The membership is older than the current membership
-3. The membership is has a status of Current, Expired or Grace
+3. The membership has a status of Current, Expired or Grace
 
 By changing the membership status to *Duplicate*, this then prevents duplicate Membership Renewal Reminders from being sent to the Contacts, avoiding potential confusion and/or negative feedback to your organisation.
 
@@ -27,7 +29,15 @@ This feature is useful if you want to have all membership end dates occur on the
 
 This feature can be enabled or disabled on the `CiviCRM > Administer > Membership Utilities Settings` page, `/wp-admin/admin.php?page=CiviCRM&q=civicrm%2Fadmin%2Fsetting%2Fmembershiputils`.
 
-If you have existing memberships that need to be updated, then execute the Scheduled Job, `Adjust Membership End Date`. This will also update the membership end date for **New**, **Current** and **Grace** memberships, setting the end date to the end of month.
+If you have existing memberships that need to be updated, then execute the Scheduled Job, `Adjust Membership End Date` (API:  membershiputils.adjustmembershipenddate). This will update the memberships with a status of either: **New**, **Current** and **Grace**, setting the end date to the end of month.
+
+## Specific Membership End Date
+
+This feature is useful if you want to have all membership end dates occur on a specific date. For example, if your organisation provides membership which have a 3 year term and all memberships must be aligned with that term.
+
+This feature can be enabled or disabled on the `CiviCRM > Administer > Membership Utilities Settings` page, `/wp-admin/admin.php?page=CiviCRM&q=civicrm%2Fadmin%2Fsetting%2Fmembershiputils`.
+
+If you have existing memberships that need to be updated, then execute the Scheduled Job, `Set specific Membership End Date` (API:  membershiputils.Specificmembershipenddate). This will update the memberships with a status of either: **New**, **Current** and **Grace**, setting the end date to the date specified in the settings.
 
 # Installation
 

diff --git a/api/v3/Membershiputils/Adjustmembershipenddate.php b/api/v3/Membershiputils/Adjustmembershipenddate.php
@@ -1,18 +1,6 @@
 <?php
 
 use Civi\Api4\Membership;
-use CRM_Membershiputils_ExtensionUtil as E;
-
-/**
- * Job.Adjustmembershipenddate API specification (optional)
- * This is used for documentation and validation.
- *
- * @param array $spec description of fields supported by this API call
- *
- * @see https://docs.civicrm.org/dev/en/latest/framework/api-architecture/
- */
-function _civicrm_api3_membershiputils_Adjustmembershipenddate_spec(&$spec) {
-}
 
 /**
  * Job.Adjustmembershipenddate API
@@ -29,26 +17,34 @@ function _civicrm_api3_membershiputils_Adjustmembershipenddate_spec(&$spec) {
  * @see civicrm_api3_create_success
  *
  */
-function civicrm_api3_membershiputils_Adjustmembershipenddate($params) {
+function civicrm_api3_membershiputils_Adjustmembershipenddate($params): array {
   try {
-    // Get all memberships
-    $memberships = Membership::get()
-      ->addSelect('id', 'end_date')
-      ->addWhere('status_id:name', 'IN', ['New', 'Current', 'Grace'])
-      ->execute()->getArrayCopy();
-    foreach ($memberships as $membership) {
-      // Calculate the end of month date for the membership
-      $end_date = date_create($membership['end_date']);
-      $start_month = date_create($end_date->format('Y-m') . '-01');
-      $new_end_date = date_modify($start_month, '+1 month -1 day');
+		// If this option is enabled then action, otherwise skip
+	  if ( Civi::settings()->get( 'adjust_membership_end_date' ) ) {
+		  // Get all memberships
+		  $memberships = Membership::get()
+		                           ->addSelect( 'id', 'end_date' )
+		                           ->addWhere( 'status_id:name', 'IN', [
+			                           'New',
+			                           'Current',
+			                           'Grace'
+		                           ] )
+		                           ->execute()->getArrayCopy();
+		  foreach ( $memberships as $membership ) {
+			  // Calculate the end of month date for the membership
+			  $end_date     = date_create( $membership['end_date'] );
+			  $start_month  = date_create( $end_date->format( 'Y-m' ) . '-01' );
+			  $new_end_date = date_modify( $start_month, '+1 month -1 day' );
+
+			  // Update the membership
+			  Membership::update()
+			            ->addValue( 'end_date', $new_end_date->format( 'Y-m-d' ) )
+			            ->addWhere( 'id', '=', $membership['id'] )
+			            ->execute();
+		  }
 
-      // Update the membership
-      Membership::update()
-        ->addValue('end_date', $new_end_date->format('Y-m-d'))
-        ->addWhere('id', '=', $membership['id'])
-        ->execute();
-    }
-    return civicrm_api3_create_success(TRUE, $params, 'membershiputils', 'Adjustmembershipenddate');
+		  return civicrm_api3_create_success( TRUE, $params, 'membershiputils', 'Adjustmembershipenddate' );
+	  }
   }
   catch (Exception $e) {
     throw new CRM_Core_Exception('Error updating adjusting membership end date. Error: ' . $e->getMessage());

diff --git a/api/v3/Membershiputils/Findduplicatememberships.php b/api/v3/Membershiputils/Findduplicatememberships.php
@@ -1,7 +1,5 @@
 <?php
 
-use CRM_Membershiputils_ExtensionUtil as E;
-
 /**
  * Membershiputils.Findduplicatememberships API
  *
@@ -13,7 +11,7 @@
  *
  * @see civicrm_api3_create_success
  */
-function civicrm_api3_membershiputils_Findduplicatememberships() {
+function civicrm_api3_membershiputils_Findduplicatememberships(): array {
   /* Example query to locate duplicate memberships
    SELECT `duplicate`.*, `current`.`id` `current_id`, `current`.`status_id` `current_status_id`, `current`.`join_date` `current_join_date`, `current`.`start_date` `current_start_date`, `current`.`end_date` `current_end_date`
         FROM civicrm_membership `duplicate` INNER JOIN civicrm_membership `current`

diff --git a/api/v3/Membershiputils/Specificmembershipenddate.php b/api/v3/Membershiputils/Specificmembershipenddate.php
@@ -0,0 +1,50 @@
+<?php
+
+use Civi\Api4\Membership;
+
+/**
+ * Job.Specificmembershipenddate API
+ *
+ * Scheduled job which will bulk adjust the membership end date for all
+ * membership, setting the end date to the end of month
+ *
+ * @param array $params
+ *
+ * @return array
+ *   API result descriptor
+ *
+ * @throws API_Exception
+ * @see civicrm_api3_create_success
+ *
+ */
+function civicrm_api3_membershiputils_Specificmembershipenddate($params): array {
+  try {
+		// If this option is enabled then action, otherwise skip
+	  if ( Civi::settings()->get( 'use_specific_membership_end_date' ) ) {
+		  // Get all memberships
+		  $memberships = Membership::get()
+		                           ->addSelect( 'id', 'end_date' )
+		                           ->addWhere( 'status_id:name', 'IN', [
+			                           'New',
+			                           'Current',
+			                           'Grace'
+		                           ] )
+		                           ->execute()->getArrayCopy();
+		  foreach ( $memberships as $membership ) {
+			  // Set a specific end date
+			  $new_end_date = date_create_from_format('Y-m-d', Civi::settings()->get('specific_membership_end_date'));
+
+			  // Update the membership
+			  Membership::update()
+			            ->addValue( 'end_date', $new_end_date->format( 'Y-m-d' ) )
+			            ->addWhere( 'id', '=', $membership['id'] )
+			            ->execute();
+		  }
+
+		  return civicrm_api3_create_success( TRUE, $params, 'membershiputils', 'Specificmembershipenddate' );
+	  }
+  }
+  catch (Exception $e) {
+    throw new CRM_Core_Exception('Error setting specific membership end date. Error: ' . $e->getMessage());
+  }
+}
diff --git a/info.xml b/info.xml
@@ -14,20 +14,23 @@
     <url desc="Support">https://agileware.com.au/contact</url>
     <url desc="Licensing">http://www.gnu.org/licenses/agpl-3.0.html</url>
   </urls>
-  <releaseDate>2022-07-04</releaseDate>
-  <version>1.3.3</version>
-  <develStage>beta</develStage>
+  <releaseDate>2024-01-25</releaseDate>
+  <version>1.3.4</version>
+  <develStage>stable</develStage>
   <compatibility>
-    <ver>5.0</ver>
+    <ver>5.27</ver>
   </compatibility>
-  <comments></comments>
+  <comments/>
   <classloader>
     <psr4 prefix="Civi\" path="Civi"/>
+    <psr0 prefix="CRM_" path="."/>
   </classloader>
   <civix>
     <namespace>CRM/Membershiputils</namespace>
+    <format>23.02.1</format>
   </civix>
   <mixins>
-    <mixin>mgd-php@1.0.0</mixin>
+    <mixin>menu-xml@1.0.0</mixin>
+    <mixin>setting-php@1.0.0</mixin>
   </mixins>
 </extension>