From f54f3bf262d62b71f659a6a93257d9ec0e001f5c Mon Sep 17 00:00:00 2001
From: Marc Michalsky forumZFD <michalsky@forumzfd.de>
Date: Mon, 28 Sep 2020 14:13:19 +0200
Subject: [PATCH] add comments

---
 api/v3/TwingleSync/Get.php                   |  8 +++++---
 api/v3/TwingleSync/models/TwingleApiCall.php | 11 +++++++----
 api/v3/TwingleSync/models/TwingleProject.php | 20 ++++++++++++++++++++
 3 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/api/v3/TwingleSync/Get.php b/api/v3/TwingleSync/Get.php
index b672e31..ad16036 100644
--- a/api/v3/TwingleSync/Get.php
+++ b/api/v3/TwingleSync/Get.php
@@ -19,7 +19,7 @@ function _civicrm_api3_twingle_sync_Get_spec(&$spec) {
     'title'        => E::ts('Twingle API key'),
     'type'         => CRM_Utils_Type::T_STRING,
     'api.required' => 0,
-    'description'  => E::ts('The key you need to access the Twingle API'),
+    'description'  => E::ts('The key to access the Twingle API'),
   ];
   $spec['test'] = [
     'name'         => 'test',
@@ -45,13 +45,15 @@ function _civicrm_api3_twingle_sync_Get_spec(&$spec) {
 function civicrm_api3_twingle_sync_Get($params) {
   $result_values = [];
 
+  // If function call provides an API key, use it instead of the API key set
+  // on the extension settings page
   $apiKey = empty($params['twingle_api_key'])
     ? CRM_Core_BAO_Setting::getItem('', 'twingle_api_key')
     : $params['twingle_api_key'];
 
-  // TODO: Do the magic!
+  // Get all projects from Twingle and store them in $projects
 
-  $twingleApi = new TwingleApiCall($apiKey);
+  // Create projects as campaigns if they do not exist and store results in
   $result_values['projects'] = $twingleApi->getProject();
   foreach ($result_values['projects'] as $project) {
     if (is_array($project)) {
diff --git a/api/v3/TwingleSync/models/TwingleApiCall.php b/api/v3/TwingleSync/models/TwingleApiCall.php
index 1a8d874..2d0bfcf 100644
--- a/api/v3/TwingleSync/models/TwingleApiCall.php
+++ b/api/v3/TwingleSync/models/TwingleApiCall.php
@@ -99,10 +99,13 @@ class TwingleApiCall {
     return $result;
   }
 
-  public function createProject($values) {
-    try {
-      if (is_array($values)) {
-        $project = new TwingleProject($values);
+  /**
+   * @param $values
+   *
+   * @return array|null
+   * @throws \CiviCRM_API3_Exception
+   * @throws \Exception
+   */
         return $project->create();
       }
     } catch (\Exception $e) {
diff --git a/api/v3/TwingleSync/models/TwingleProject.php b/api/v3/TwingleSync/models/TwingleProject.php
index b3d4d88..4c9d102 100644
--- a/api/v3/TwingleSync/models/TwingleProject.php
+++ b/api/v3/TwingleSync/models/TwingleProject.php
@@ -53,6 +53,10 @@ class TwingleProject {
   }
 
   /**
+   * Get all related custom fields as CustomField objects in an static array.
+   * This function will be fully executed only once, when the TwingleProject
+   * class gets instantiated for the first time.
+   *
    * @throws \Exception
    */
   private static function init() {
@@ -77,6 +81,12 @@ class TwingleProject {
     self::$bInitialized = TRUE;
   }
 
+  /**
+   * Create the project as a campaign in CiviCRM if it does not exist
+   *
+   * @return array
+   * @throws \CiviCRM_API3_Exception
+   */
   public function create() {
     $values = $this->values;
     try {
@@ -86,6 +96,11 @@ class TwingleProject {
     }
   }
 
+  /**
+   * Formats values to import them as campaigns
+   *
+   * @param $values
+   */
   private function formatForImport(&$values) {
 
     // Change timestamp into DateTime string
@@ -100,6 +115,11 @@ class TwingleProject {
     }
   }
 
+  /**
+   * Formats values to send them to Twingle API
+   *
+   * @param $values
+   */
   private function formatForExport(&$values) {
 
     // Change DateTime string into timestamp