ProPeace/de.forumzfd.twinglecampaign
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

clean up

Browse source 
improve method documentation and more
This commit is contained in:
Marc Michalsky forumZFD 2021-02-01 14:33:03 +01:00
parent 9df3ff4153
commit 88474c10ac
Signed by untrusted user who does not match committer: marc.koch
GPG key ID: 12406554CFB028B9
10 changed files with 305 additions and 381 deletions
Download patch file Download diff file Expand all files Collapse all files

248
CRM/TwingleCampaign/BAO/Campaign.php
View file

@ -22,91 +22,30 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
/** /**
* Campaign constructor. * ## Campaign constructor.
* *
* @param array $campaign * @param array $values
* Result array of Twingle API call * @param int|null $id
*
* Origin of the arrays. It can be one of two constants:
* Campaign::TWINGLE|CIVICRM
*
* @throws Exception
*/ */
protected function __construct(array $campaign) { protected function __construct(array $values, int $id = NULL) {
$this->id = $id;
$tmpClassName = explode('_', get_class($this)); $tmpClassName = explode('_', get_class($this));
$this->className = array_pop($tmpClassName); $this->className = array_pop($tmpClassName);
// Set campaign values // Set campaign values
$this->update($campaign);
}
/**
* Check if a campaign already exists and if so set attributes
* to the values of the existing campaign.
*
* @return bool
* Returns TRUE id the campaign already exists
*
* @throws CiviCRM_API3_Exception
*
* @throws Exception
*/
public function exists(): bool {
if (!$this->values['id']) {
return FALSE;
}
$single = FALSE;
$query = ['sequential' => 1,];
switch($this->className) {
case 'TwingleProject':
$query['project_id'] = $this->values['id'];
break;
case 'TwingleEvent':
$query['event_id'] = $this->values['id'];
}
$result = civicrm_api3($this->className, 'get', $query);
// If there is more than one campaign for this entity, handle the duplicates
if ($result['count'] > 1) {
self::handleDuplicates($result);
}
else {
$single = TRUE;
}
// If this campaign already exists, get its attributes
if ($result['count'] == 1) {
// Extract campaign values from result array
$values = $result['values'][0];
// Set id attribute
$this->id = $values['id'];
// Set attributes to the values of the existing campaign
// to reflect the state of the actual campaign in the database
$this->update($values); $this->update($values);
return TRUE;
}
else {
return FALSE;
}
} }
/** /**
* Update an existing campaign * ## Update instance values
* This method updates the **$values** array of this instance with the values
* from the provided array if they are defined in
* *CRM/TwingleCampaign/resources/twingle_api_templates.json*
* *
* @param array $values * @param array $values
* Array with values to update * Array with values to update
*
*/ */
public function update(array $values) { public function update(array $values) {
// Update campaign values // Update campaign values
@ -129,67 +68,85 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
/** /**
* Deactivate all duplicates of a campaign but the newest one * ## Set embed data fields
* This method sets all embed data fields that are defined in
* *CRM/TwingleCampaign/resources/twingle_api_templates.json*
* *
* @param array $result * @param array $embedData
* * Array with embed data from Twingle API
* @throws CiviCRM_API3_Exception
*/ */
protected function handleDuplicates(array &$result) { public function setEmbedData(array $embedData) {
// Sort campaigns ascending by the value of the last_modified_date // Get all embed_data keys from template
uasort($result['values'], function ($a, $b) { $embed_data_keys = Cache::getInstance()
return $a['last_modified_date'] <=> $b['last_modified_date']; ->getTemplates()['project_embed_data'];
});
// Deactivate all but the first campaign // Transfer all embed_data values
while (sizeof($result['values']) > 1) { foreach ($embed_data_keys as $key) {
self::deactivateById(array_pop($result['values'])); $this->values[$key] = $embedData[$key];
} }
} }
/**
* Translate values between CiviCRM Campaigns and Twingle format public abstract function formatValues(array &$values, string $direction);
*
* @param array $values
* array of which values shall be translated
*
* @param string $direction
* TwingleProject::IN -> translate array values from Twingle to CiviCRM <br>
* TwingleProject::OUT -> translate array values from CiviCRM to Twingle
*
* @throws Exception
*/
public static abstract function formatValues(array &$values, string $direction);
/** /**
* Translate array keys between CiviCRM Campaigns and Twingle * ## Translate array keys between CiviCRM Campaigns and Twingle
* *
* @param array $values * Constants for **$direction**:<br>
* array of which keys to translate * **Campaign::IN** translate array keys from Twingle format into
*
* @param string $direction
* Campaign::IN -> translate array keys from Twingle format into
* CiviCRM format <br> * CiviCRM format <br>
* Campaign::OUT -> translate array keys from CiviCRM format into * **Campaign::OUT** translate array keys from CiviCRM format into
* Twingle format * Twingle format
* *
* @param array $values
* array of keys to translate
*
* @param string $direction
* const: Campaign::OUT or Campaign::OUT
*
* @throws Exception * @throws Exception
*/ */
public static abstract function translateKeys(array &$values, string $direction); public function translateKeys(array &$values, string $direction) {
// Get translations for fields
$field_translations = Cache::getInstance()
->getTranslations()[$this->className];
// Set the direction of the translation
if ($direction == self::OUT) {
$field_translations = array_flip($field_translations);
}
// Throw error if $direction constant does not match IN or OUT
elseif ($direction != self::IN) {
throw new Exception(
"Invalid Parameter $direction for translateKeys()"
);
}
// Translate keys
foreach ($field_translations as $origin => $translation) {
$values[$translation] = $values[$origin];
unset($values[$origin]);
}
}
/** /**
* Translate between field names and custom field names * ## Translate field names and custom field names
*
* Constants for **$direction**:<br>
* **Campaign::IN** translate array keys from Twingle format into
* CiviCRM format <br>
* **Campaign::OUT** translate array keys from CiviCRM format into
* Twingle format
* *
* @param array $values * @param array $values
* array of which keys shall be translated * array of keys to translate
* *
* @param string $direction * @param string $direction
* Campaign::IN -> translate field names into custom field names <br> * const: Campaign::OUT or Campaign::OUT
* Campaign::OUT -> translate custom field names into field names
*
*/ */
public function translateCustomFields(array &$values, string $direction) { public function translateCustomFields(array &$values, string $direction) {
@ -245,23 +202,6 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
} }
} }
/**
* Set embed data fields
*
* @param array $embedData
* Array with embed data from Twingle API
*/
public function setEmbedData(array $embedData) {
// Get all embed_data keys from template
$embed_data_keys = Cache::getInstance()
->getTemplates()['project_embed_data'];
// Transfer all embed_data values
foreach ($embed_data_keys as $key) {
$this->values[$key] = htmlspecialchars($embedData[$key]);
}
}
/** /**
* Set counter url * Set counter url
@ -273,8 +213,9 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
$this->values['counter'] = $counterUrl; $this->values['counter'] = $counterUrl;
} }
/** /**
* Deactivate this Campaign campaign * ## Deactivate this campaign
* *
* @return bool * @return bool
* TRUE if deactivation was successful * TRUE if deactivation was successful
@ -282,13 +223,12 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
* @throws CiviCRM_API3_Exception * @throws CiviCRM_API3_Exception
*/ */
public function deactivate(): bool { public function deactivate(): bool {
return self::deactivateByid($this->id); return self::deactivateByid($this->id);
} }
/** /**
* Deactivate a Campaign campaign by ID * ## Deactivate campaign by ID
* *
* @param $id * @param $id
* ID of the campaign that should get deactivated * ID of the campaign that should get deactivated
@ -319,28 +259,21 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
else { else {
return FALSE; return FALSE;
} }
} }
/**
* Get a response that describes the status of a Campaign
*
* @param string $status
* status of the Campaign you want the response for
*
* @return array
* Returns a response array that contains title, id, project_id and status
*/
public abstract function getResponse(string $status): array; public abstract function getResponse(string $status): array;
/** /**
* Validates $input to be either a DateTime string or an Unix timestamp * ## Get timestamp
* Validates **$input** to be either a *DateTime string* or an *Unix timestamp*
* and in both cases returns a *Unix time stamp*.
* *
* @param $input * @param $input
* Pass a DateTime string or a Unix timestamp * Provide a DateTime string or a Unix timestamp
* *
* @return int * @return int|null
* Returns a Unix timestamp or NULL if $input is invalid * Returns a Unix timestamp or NULL if $input is invalid
*/ */
public static function getTimestamp($input): ?int { public static function getTimestamp($input): ?int {
@ -361,27 +294,24 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
else { else {
return NULL; return NULL;
} }
} }
/**
* Return a timestamp of the last update of the Campaign
*
* @return int|string|null
*/
public abstract function lastUpdate(); public abstract function lastUpdate();
/** /**
* Validates $input to be either a DateTime string or an Unix timestamp * ## Get DateTime
* Validates **$input** to be either a *DateTime string* or an *Unix timestamp*
* and in both cases returns *DateTime string*.
* *
* @param $input * @param $input
* Pass a DateTime string or a Unix timestamp * Provide a DateTime string or a Unix timestamp
* *
* @return string * @return string
* Returns a DateTime string or NULL if $input is invalid * Returns a DateTime string or NULL if $input is invalid
*/ */
public static function getDateTime($input) { public static function getDateTime($input): ?string {
// Check whether $input is a Unix timestamp // Check whether $input is a Unix timestamp
if ( if (
@ -399,25 +329,17 @@ abstract class CRM_TwingleCampaign_BAO_Campaign {
else { else {
return NULL; return NULL;
} }
} }
/** /**
* Returns the project_id of a Campaign * ## Get id
* Returns the **id** of this campaign.
* *
* @return int * @return int
*/ */
public function getProjectId() { public function getId(): int {
return $this->values['id']; return (int) $this->id;
}
/**
* @return mixed
*/
public function getId() {
return $this->id;
} }
} }

88
CRM/TwingleCampaign/BAO/TwingleApiCall.php
View file

@ -19,7 +19,7 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
private $extensionName; private $extensionName;
/** /**
* TwingleApiCall constructor. * ## TwingleApiCall constructor
* *
* @param $apiKey * @param $apiKey
* *
@ -65,16 +65,17 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
} }
/** /**
* If $id parameter is empty, this function returns all projects for all * ## Get project from Twingle
* organisations this API key is assigned to. * If the **$id** parameter is empty, this function returns all projects for
* this organisation.
* *
* If $id parameter is given, this function returns a single project. * If the **$id** parameter is provided, this function returns a single
* project.
* *
* @param int|null $projectId * @param int|null $projectId
* * @return array|false
* @return mixed
*/ */
public function getProject(int $projectId = NULL) { public function getProject(int $projectId = NULL): ?array {
$url = empty($projectId) $url = empty($projectId)
? $this->protocol . 'project' . $this->baseUrl . 'by-organisation/' . $this->organisationId ? $this->protocol . 'project' . $this->baseUrl . 'by-organisation/' . $this->organisationId
@ -84,18 +85,20 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
} }
/** /**
* Sends an curl post call to Twingle to update an existing project and then * ## Push project to Twingle
* updates the TwingleProject campaign. * Sends a curl post call to Twingle to update an existing project.
*
* Returns an array with all project values.
* *
* @param TwingleProject $project * @param TwingleProject $project
* The TwingleProject object that should get pushed to Twingle * The TwingleProject object that should get pushed to Twingle
* *
* @return array * @return array
* Returns a response array that contains title, id, project_id and status
* @throws \Exception * @throws \Exception
*/ */
public function pushProject(TwingleProject &$project) { public function pushProject(TwingleProject &$project): array {
// Get only those values from the TwingleProject object which Twingle expects
$values = $project->export(); $values = $project->export();
// Prepare url for curl // Prepare url for curl
@ -112,18 +115,19 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
} }
/** /**
* Returns all Events for the given $projectId or a single event if an * ## Get event from Twingle
* $eventId is given, too. * Returns all events for the provided **$projectId** or a single event if an
* **$eventId** is provided, too.
* *
* @param int $projectId * @param int $projectId
*
* @param null|int $eventId * @param null|int $eventId
*
* @return array * @return array
* @throws Exception
*/ */
public function getEvent($projectId, $eventId = NULL) { public function getEvent(int $projectId, int $eventId = NULL): array {
$result = []; $result = [];
// Construct url for curl
$url = empty($eventId) $url = empty($eventId)
? $this->protocol . 'project' . $this->baseUrl . $projectId . '/event' ? $this->protocol . 'project' . $this->baseUrl . $projectId . '/event'
: $this->protocol . 'project' . $this->baseUrl . $projectId . '/event/' : $this->protocol . 'project' . $this->baseUrl . $projectId . '/event/'
@ -147,15 +151,15 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
// If no $eventId was given, expect one or more events. // If no $eventId was given, expect one or more events.
// Store the events, increase the offset and ask again until there // Store the events, increase the offset and ask again until there
// are no more events incoming. // are no more events incoming.
if ($response['data'] && !$eventId) { if (!$eventId) {
$result = array_merge($result, $response['data']); $result = array_merge($result, $response['data']);
$offset = $offset + $this->limit; $offset = $offset + $this->limit;
$finished = count($response['data']) < $this->limit; $finished = count($response['data']) < $this->limit;
} }
// If $eventId was given, expect only one event // If $eventId was given, expect only one event
else { else {
// If result the array contains 'message', the $eventId does not exist // If the response array contains 'message', the $eventId does not exist
if (!$result['message']) { if (!$response['message']) {
$result = $response; $result = $response;
} }
$finished = TRUE; $finished = TRUE;
@ -165,13 +169,15 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
} }
/** /**
* ## Get project embed data
* Get embed data for a specific project.
*
* @param $projectId * @param $projectId
* *
* @return array|NULL * @return array
* @throws \Exception * @throws Exception
*/ */
public public function getProjectEmbedData($projectId): array {
function getProjectEmbedData($projectId): array {
$result = $this->getProject($projectId); $result = $this->getProject($projectId);
@ -190,19 +196,21 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
/** /**
* Does a cURL and gives back the result array. * ## Send a GET cURL
* Sends a GET cURL and returns the result array.
* *
* @param $url * @param $url
* The url the curl should get sent to * The destination url
* *
* @param null $params * @param null $params
* The parameters you want to send (optional) * The parameters you want to send (optional)
* *
* @return array|bool * @return array
* Returns the result array of the curl or FALSE, if the curl failed * Returns the result array of the curl or FALSE, if the curl failed
* @throws Exception
*/ */
private private
function curlGet($url, $params = NULL) { function curlGet($url, $params = NULL): array {
if (!empty($params)) { if (!empty($params)) {
$url = $url . '?' . http_build_query($params); $url = $url . '?' . http_build_query($params);
} }
@ -213,27 +221,30 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
'Content-Type: application/json', 'Content-Type: application/json',
]); ]);
$response = json_decode(curl_exec($curl), TRUE); $response = json_decode(curl_exec($curl), TRUE);
if (empty($response)) {
$response = curl_error($curl);
}
curl_close($curl); curl_close($curl);
if ($response === FALSE) {
throw new Exception('GET curl failed');
}
return $response; return $response;
} }
/** /**
* Sends a curl post and gives back the result array. * ## Send a POST cURL
* Sends a POST cURL and returns the result array.
* *
* @param $url * @param $url
* The url the curl should get sent to * The destination url
* *
* @param $data * @param $data
* The data that should get posted * The data that should get send
* *
* @return false|mixed * @return array
* Returns the result array of the curl or FALSE, if the curl failed * Returns the result array of the curl or FALSE, if the curl failed
* @throws Exception
*/ */
private private
function curlPost($url, $data) { function curlPost($url, $data): array {
$curl = curl_init($url); $curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POST, TRUE); curl_setopt($curl, CURLOPT_POST, TRUE);
@ -244,11 +255,10 @@ class CRM_TwingleCampaign_BAO_TwingleApiCall {
$json = json_encode($data); $json = json_encode($data);
curl_setopt($curl, CURLOPT_POSTFIELDS, $json); curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
$response = json_decode(curl_exec($curl), TRUE); $response = json_decode(curl_exec($curl), TRUE);
if (empty($response)) {
$response = FALSE;
}
curl_close($curl); curl_close($curl);
if ($response === FALSE) {
throw new Exception('POST curl failed');
}
return $response; return $response;
} }
} }

25
CRM/TwingleCampaign/BAO/TwingleCampaign.php
View file

@ -1,7 +1,28 @@
<?php <?php
use CRM_TwingleCampaign_BAO_Campaign as Campaign;
class CRM_TwingleCampaign_BAO_TwingleCampaign extends Campaign { class CRM_TwingleCampaign_BAO_TwingleCampaign {
private $id;
private $tw_cid;
/**
* TwingleCampaign constructor.
*/
public function __construct() {
}
public function create() {
}
public function exists() {
}
} }

101
CRM/TwingleCampaign/BAO/TwingleEvent.php
View file

@ -9,12 +9,13 @@ use CRM_TwingleCampaign_ExtensionUtil as E;
class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign { class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
/** /**
* TwingleEvent constructor. * ## TwingleEvent constructor
* *
* @param array $event * @param array $event
* Result array of Twingle API call to * Event values
* https://project.twingle.de/api/$project_id/event *
* @param int|null $id * @param int|null $id
* CiviCRM Campaign id
* *
* @throws \Exception * @throws \Exception
*/ */
@ -36,11 +37,10 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
/** /**
* Create the Event as a campaign in CiviCRM if it does not exist * ## Create the Event as a campaign in CiviCRM if it does not exist
* Returns _TRUE_ if creation was successful or _FALSE if it creation failed.
* *
* @return bool * @return bool
* Returns _TRUE_ id creation was successful or _FALSE_ if it creation failed
*
* @throws CiviCRM_API3_Exception * @throws CiviCRM_API3_Exception
* @throws Exception * @throws Exception
*/ */
@ -48,11 +48,11 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
// Prepare project values for import into database // Prepare project values for import into database
$values_prepared_for_import = $this->values; $values_prepared_for_import = $this->values;
self::formatValues( $this::formatValues(
$values_prepared_for_import, $values_prepared_for_import,
self::IN self::IN
); );
self::translateKeys( $this->translateKeys(
$values_prepared_for_import, $values_prepared_for_import,
self::IN self::IN
); );
@ -107,19 +107,20 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
/** /**
* Translate values between CiviCRM Campaigns and Twingle * ## Translate values between CiviCRM Campaigns and Twingle formats
* Constants for **$direction**:<br>
* **TwingleProject::IN** translate array values from Twingle to CiviCRM format<br>
* **TwingleProject::OUT** translate array values from CiviCRM to Twingle format
* *
* @param array $values * @param array $values
* array of which values shall be translated * array of values to translate
* *
* @param string $direction * @param string $direction
* self::IN -> translate array values from Twingle to CiviCRM <br> * const: TwingleProject::IN or TwingleProject::OUT
* self::OUT -> translate array values from CiviCRM to Twingle
* *
* @throws Exception * @throws Exception
*/ */
public public function formatValues(array &$values, string $direction) {
static function formatValues(array &$values, string $direction) {
if ($direction == self::IN) { if ($direction == self::IN) {
@ -189,55 +190,15 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
/** /**
* Translate array keys between CiviCRM Campaigns and Twingle * ## Get a response
* * Get a response that describes the status of this TwingleEvent instance.
* @param array $values * Returns an array that contains **title**, **id**, **event_id**,
* array of which keys shall be translated * **project_id** and **status** (if provided)
*
* @param string $direction
* Campaign::IN -> translate array keys from Twingle format into
* CiviCRM format <br>
* Campaign::OUT -> translate array keys from CiviCRM format into
* Twingle format
*
* @throws Exception
*/
public
static function translateKeys(array &$values, string $direction) {
// Get translations for fields
$field_translations = Cache::getInstance()
->getTranslations()['TwingleEvent'];
// Set the direction of the translation
if ($direction == self::OUT) {
$field_translations = array_flip($field_translations);
}
// Throw error if $direction constant does not match IN or OUT
elseif ($direction != self::IN) {
throw new Exception(
"Invalid Parameter $direction for translateKeys()"
);
// TODO: use specific exception or create own
}
// Translate keys
foreach ($field_translations as $origin => $translation) {
$values[$translation] = $values[$origin];
unset($values[$origin]);
}
}
/**
* Get a response that describes the status of a TwingleEvent
* *
* @param string|null $status * @param string|null $status
* status of the TwingleEvent you want to give back along with the response * status of the TwingleEvent you want to give back along with the response
* *
* @return array * @return array
* Returns a response array that contains title, id, event_id, project_id and
* status
*/ */
public public
function getResponse(string $status = NULL): array { function getResponse(string $status = NULL): array {
@ -256,8 +217,9 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
/** /**
* Matches a single string that should contain first and lastname to match a * ## Match a contact
* contact or create a new one if it does not exist yet. * This method uses a single string that is expected to contain first and
* lastname to match a contact or create a new one if it does not exist yet.
* *
* @param string $names * @param string $names
* @param string $email * @param string $email
@ -288,13 +250,14 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
/** /**
* Gets the campaign id of the parent TwingleProject campaign. * ## Get parent campaign id
* Returns the campaign id of the parent TwingleProject campaign.
* *
* @return int|null * @return int|null
* @throws CiviCRM_API3_Exception * @throws CiviCRM_API3_Exception
*/ */
private private
function getParentCampaignId() { function getParentCampaignId(): ?int {
$cf_project_id = Cache::getInstance() $cf_project_id = Cache::getInstance()
->getCustomFieldMapping()['twingle_project_id']; ->getCustomFieldMapping()['twingle_project_id'];
$parentCampaign = civicrm_api3('Campaign', 'get', [ $parentCampaign = civicrm_api3('Campaign', 'get', [
@ -310,35 +273,37 @@ class CRM_TwingleCampaign_BAO_TwingleEvent extends Campaign {
} }
/** /**
* Return a timestamp of the last update of the Campaign * ## Last update
* Returns a timestamp of the last update of the TwingleEvent campaign.
* *
* @return int|string|null * @return int|string|null
*/ */
public public
function lastUpdate() { function lastUpdate() {
return self::getTimestamp($this->values['updated_at']); return self::getTimestamp($this->values['updated_at']);
} }
/** /**
* Returns the project_id of a TwingleEvent * ## Get project id
* Returns the **project_id** of this TwingleEvent.
* *
* @return int * @return int
*/ */
public public
function getProjectId() { function getProjectId(): int {
return (int) $this->values['project_id']; return (int) $this->values['project_id'];
} }
/** /**
* Returns the event_id of a TwingleEvent * ## Get event id
* Returns the **event_id** of this TwingleEvent.
* *
* @return int * @return int
*/ */
public public
function getEventId() { function getEventId(): int {
return (int) $this->values['id']; return (int) $this->values['id'];
} }
} }

118
CRM/TwingleCampaign/BAO/TwingleProject.php
View file

@ -7,16 +7,16 @@ use CRM_TwingleCampaign_BAO_Campaign as Campaign;
class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign { class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
/** /**
* TwingleProject constructor. * ## TwingleProject constructor
*
* @param array $values
* Project values
* *
* @param array $project
* Result array of Twingle API call to
* https://project.twingle.de/api/by-organisation/$organisation_id
* @param int|null $id * @param int|null $id
* * CiviCRM Campaign id
*/ */
public function __construct(array $project, int $id = NULL) { public function __construct(array $values, int $id = NULL) {
parent::__construct($project, $id); parent::__construct($values, $id);
$this->prefix = 'twingle_project_'; $this->prefix = 'twingle_project_';
$this->values['campaign_type_id'] = 'twingle_project'; $this->values['campaign_type_id'] = 'twingle_project';
@ -27,8 +27,10 @@ class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
/** /**
* Export values. Ensures that only those values will be exported which the * ## Export values
* Twingle API expects. * Ensures that only those values will be exported which the Twingle API
* expects. These values are defined in
* *CRM/TwingleCampaign/resources/twingle_api_templates.json*
* *
* @return array * @return array
* Array with all values to send to the Twingle API * Array with all values to send to the Twingle API
@ -55,25 +57,25 @@ class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
/** /**
* Create the Campaign as a campaign in CiviCRM if it does not exist * ## Create this TwingleProject as a campaign in CiviCRM
*
* Returns _TRUE_ if creation was successful or _FALSE_ if it creation failed.
* *
* @param bool $no_hook * @param bool $no_hook
* Do not trigger postSave hook to prevent recursion * Do not trigger postSave hook to prevent recursion
* *
* @return bool * @return bool
* Returns a boolean
*
* @throws \Exception * @throws \Exception
*/ */
public function create(bool $no_hook = FALSE): bool { public function create(bool $no_hook = FALSE): bool {
// Prepare project values for import into database // Prepare project values for import into database
$values_prepared_for_import = $this->values; $values_prepared_for_import = $this->values;
self::formatValues( $this->formatValues(
$values_prepared_for_import, $values_prepared_for_import,
self::IN self::IN
); );
self::translateKeys( $this->translateKeys(
$values_prepared_for_import, $values_prepared_for_import,
self::IN self::IN
); );
@ -121,17 +123,23 @@ class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
$this->create(); // this will also trigger the postSave hook $this->create(); // this will also trigger the postSave hook
} }
/**
* ## Translate values between CiviCRM Campaigns and Twingle formats
*
* Constants for **$direction**:<br>
* **TwingleProject::IN** translate array values from Twingle to CiviCRM format<br>
* **TwingleProject::OUT** translate array values from CiviCRM to Twingle format
* *
* @param array $values * @param array $values
* array of which values shall be translated * array of values to translate
* *
* @param string $direction * @param string $direction
* TwingleProject::IN -> translate array values from Twingle to CiviCRM <br> * const: TwingleProject::IN or TwingleProject::OUT
* TwingleProject::OUT -> translate array values from CiviCRM to Twingle
* *
* @throws Exception * @throws Exception
*/ */
public static function formatValues(array &$values, string $direction) { public function formatValues(array &$values, string $direction) {
if ($direction == self::IN) { if ($direction == self::IN) {
@ -164,7 +172,6 @@ class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
$values['allow_more'] = empty($values['allow_more']) $values['allow_more'] = empty($values['allow_more'])
? FALSE ? FALSE
: TRUE; : TRUE;
} }
else { else {
@ -175,73 +182,18 @@ class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
} }
} }
/**
* Translate array keys between CiviCRM Campaigns and Twingle
*
* @param array $values
* array of which keys shall be translated
*
* @param string $direction
* Campaign::IN -> translate array keys from Twingle format into
* CiviCRM format <br>
* Campaign::OUT -> translate array keys from CiviCRM format into
* Twingle format
*
* @throws Exception
*/
public static function translateKeys(array &$values, string $direction) {
// Get translations for fields
$field_translations = Cache::getInstance()
->getTranslations()['TwingleProject'];
// Set the direction of the translation
if ($direction == self::OUT) {
$field_translations = array_flip($field_translations);
}
// Throw error if $direction constant does not match IN or OUT
elseif ($direction != self::IN) {
throw new Exception(
"Invalid Parameter $direction for translateKeys()"
);
// TODO: use specific exception or create own
}
// Translate keys
foreach ($field_translations as $origin => $translation) {
$values[$translation] = $values[$origin];
unset($values[$origin]);
}
}
/** /**
* Set embed data fields * ## Get a response
* * Get a response that describes the status of this TwingleProject instance
* @param array $embedData * Returns an array that contains **title**, **id**, **project_id** and
* Array with embed data from Twingle API * **status** (if provided)
*/
public function setEmbedData(array $embedData) {
// Get all embed_data keys from template
$embed_data_keys = Cache::getInstance()
->getTemplates()['project_embed_data'];
// Transfer all embed_data values
foreach ($embed_data_keys as $key) {
$this->values[$key] = $embedData[$key];
}
}
/**
* Get a response that describes the status of a TwingleProject
* *
* @param string|null $status * @param string|null $status
* status of the TwingleProject you want to give back along with the response * status of the TwingleProject you want to give back along with the response
* *
* @return array * @return array
* Returns a response array that contains title, id, project_id and status *
*/ */
public function getResponse(string $status = NULL): array { public function getResponse(string $status = NULL): array {
$project_type = empty($this->values['type']) ? 'default' : $this->values['type']; $project_type = empty($this->values['type']) ? 'default' : $this->values['type'];
@ -258,19 +210,21 @@ class CRM_TwingleCampaign_BAO_TwingleProject extends Campaign {
return $response; return $response;
} }
/** /**
* Return a timestamp of the last update of the Campaign * ## Last update
* Returns a timestamp of the last update of the TwingleProject campaign.
* *
* @return int|string|null * @return int|string|null
*/ */
public function lastUpdate() { public function lastUpdate() {
return self::getTimestamp($this->values['last_update']); return self::getTimestamp($this->values['last_update']);
} }
/** /**
* Returns the project_id of a TwingleProject * ## Get project id
* Returns the **project_id** of this TwingleProject.
* *
* @return int * @return int
*/ */

11
api/v3/TwingleEvent/Get.php
View file

@ -143,8 +143,15 @@ function civicrm_api3_twingle_event_Get(array $params): array {
} }
} }
try { try {
TwingleEvent::translateKeys($returnValues[$event['id']], TwingleEvent::OUT); $tmp_event = new TwingleEvent([]);
TwingleEvent::formatValues($returnValues[$event['id']], TwingleEvent::OUT); $tmp_event->translateKeys(
$returnValues[$event['id']],
TwingleEvent::OUT
);
TwingleEvent::formatValues(
$returnValues[$event['id']],
TwingleEvent::OUT
);
} }
catch (Exception $e) { catch (Exception $e) {
throw new CiviCRM_API3_Exception($e->getMessage()); throw new CiviCRM_API3_Exception($e->getMessage());

37
api/v3/TwingleEvent/Sync.php
View file

@ -41,6 +41,13 @@ function _civicrm_api3_twingle_event_Sync_spec(array &$spec) {
'api.required' => 0, 'api.required' => 0,
'description' => E::ts('The key to access the Twingle API'), 'description' => E::ts('The key to access the Twingle API'),
]; ];
$spec['limit'] = [
'name' => 'limit',
'title' => E::ts('Limit'),
'type' => CRM_Utils_Type::T_INT,
'api.required' => 0,
'description' => E::ts('Limit for the number of events that should get requested per call to the Twingle API'),
];
} }
/** /**
@ -65,6 +72,7 @@ function _civicrm_api3_twingle_event_Sync_spec(array &$spec) {
* @return array * @return array
* API result descriptor * API result descriptor
* @throws \CiviCRM_API3_Exception * @throws \CiviCRM_API3_Exception
* @throws \Exception
* @see civicrm_api3_create_success * @see civicrm_api3_create_success
*/ */
function civicrm_api3_twingle_event_Sync(array $params): array { function civicrm_api3_twingle_event_Sync(array $params): array {
@ -80,9 +88,14 @@ function civicrm_api3_twingle_event_Sync(array $params): array {
// Try to retrieve twingleApi from cache or create a new // Try to retrieve twingleApi from cache or create a new
$twingleApi = Civi::cache()->get('twinglecampaign_twingle_api'); $twingleApi = Civi::cache()->get('twinglecampaign_twingle_api');
if (NULL === $twingleApi || $params['twingle_api_key']) { if (NULL === $twingleApi || $params['twingle_api_key'] || $params['limit']) {
try { try {
if ($params['limit']) {
$twingleApi = new TwingleApiCall($apiKey, $params['limit']);
}
else {
$twingleApi = new TwingleApiCall($apiKey); $twingleApi = new TwingleApiCall($apiKey);
}
} catch (Exception $e) { } catch (Exception $e) {
return civicrm_api3_create_error($e->getMessage()); return civicrm_api3_create_error($e->getMessage());
} }
@ -154,6 +167,18 @@ function civicrm_api3_twingle_event_Sync(array $params): array {
// Get all events for given project from Twingle and CiviCRM // Get all events for given project from Twingle and CiviCRM
if ($params['project_id']) { if ($params['project_id']) {
$events_from_twingle = $twingleApi->getEvent($params['project_id']); $events_from_twingle = $twingleApi->getEvent($params['project_id']);
// If Twingle does not know any events for this project_id (yet)
if ($events_from_twingle['count'] == 0) {
return civicrm_api3_create_success(
"Apparently this project does not have any events yet or " .
"the provided project_id is unknown to Twingle.",
$params,
'TwingleEvent',
'Sync'
);
}
$events_from_civicrm = civicrm_api3( $events_from_civicrm = civicrm_api3(
'TwingleEvent', 'TwingleEvent',
'get', 'get',
@ -181,7 +206,6 @@ function civicrm_api3_twingle_event_Sync(array $params): array {
'get', 'get',
['sequential' => 1] ['sequential' => 1]
); );
}
// Get all events for the chosen project from Twingle // Get all events for the chosen project from Twingle
foreach ($projects_from_civicrm['values'] as $project_from_civicrm) { foreach ($projects_from_civicrm['values'] as $project_from_civicrm) {
@ -192,6 +216,7 @@ function civicrm_api3_twingle_event_Sync(array $params): array {
); );
} }
$events_from_twingle = array_merge(... $events_from_twingle); $events_from_twingle = array_merge(... $events_from_twingle);
}
// Synchronize existing events or create new ones // Synchronize existing events or create new ones
foreach ($events_from_twingle as $event_from_twingle) { foreach ($events_from_twingle as $event_from_twingle) {
@ -275,7 +300,7 @@ function civicrm_api3_twingle_event_Sync(array $params): array {
return civicrm_api3_create_success( return civicrm_api3_create_success(
$result_values, $result_values,
$params, $params,
'TwingleProject', 'TwingleEvent',
'Sync' 'Sync'
); );
} }
@ -292,7 +317,7 @@ function civicrm_api3_twingle_event_Sync(array $params): array {
*/ */
function instantiateEvent($values): CRM_TwingleCampaign_BAO_TwingleEvent { function instantiateEvent($values): CRM_TwingleCampaign_BAO_TwingleEvent {
try { try {
return new TwingleEvent($values); return new TwingleEvent($values, $values['id']);
} catch (Exception $e) { } catch (Exception $e) {
throw new CiviCRM_API3_Exception( throw new CiviCRM_API3_Exception(
$e->getMessage(), $e->getMessage(),
@ -379,7 +404,7 @@ function sync(TwingleEvent $event,
array $params): array { array $params): array {
// If Twingle's timestamp of the event differs from the timestamp of the // If Twingle's timestamp of the event differs from the timestamp of the
// CiviCRM TwingleProject campaign, update the campaign on CiviCRM's side. // CiviCRM TwingleEvent campaign, update the campaign on CiviCRM's side.
// NOTE: Changes on TwingleEvents are not meant to get pushed to Twingle // NOTE: Changes on TwingleEvents are not meant to get pushed to Twingle
if ($event_from_twingle['updated_at'] != $event->lastUpdate()) { if ($event_from_twingle['updated_at'] != $event->lastUpdate()) {
return updateLocally($event_from_twingle, $event, $params, $twingleApi); return updateLocally($event_from_twingle, $event, $params, $twingleApi);
@ -387,7 +412,7 @@ function sync(TwingleEvent $event,
// If both versions are still synchronized // If both versions are still synchronized
else { else {
$response[] = $event->getResponse('TwingleEvent up to date'); $response = $event->getResponse('TwingleEvent up to date');
return civicrm_api3_create_success( return civicrm_api3_create_success(
$response, $response,
$params, $params,

29
api/v3/TwingleProject/Create.php
View file

@ -86,14 +86,33 @@ function _civicrm_api3_twingle_project_Create_spec(array &$spec) {
* @see civicrm_api3_create_success * @see civicrm_api3_create_success
* *
*/ */
function civicrm_api3_twingle_project_Create($params) { function civicrm_api3_twingle_project_Create($params): array {
$returnValues = [];
// For logging purpose
$extensionName = E::LONG_NAME;
// instantiate project
$project = new TwingleProject($params, 'TWINGLE'); $project = new TwingleProject($params, 'TWINGLE');
if (!$project->exists()) { // Try to create the TwingleProject campaign
$returnValues = $project->create(); try {
$project->create();
return civicrm_api3_create_success(
$project->getResponse('TwingleProject created'),
$params,
'TwingleProject',
'Create'
);
} catch(Exception $e){
$errorMessage = $e->getMessage();
Civi::log()->error(
"$extensionName could not create TwingleProject: $errorMessage",
$project->getResponse()
);
return civicrm_api3_create_error(
"Could not create TwingleProject: $errorMessage",
$project->getResponse()
);
} }
return civicrm_api3_create_success($returnValues, $params, 'TwingleProject', 'Create');
} }

5
api/v3/TwingleProject/Get.php
View file

@ -152,8 +152,9 @@ function civicrm_api3_twingle_project_Get(array $params): array {
} }
} }
try { try {
TwingleProject::translateKeys($returnValues[$project['id']], TwingleProject::OUT); $tmp_project = new TwingleProject([]);
TwingleProject::formatValues($returnValues[$project['id']], TwingleProject::OUT); $tmp_project->translateKeys($returnValues[$project['id']], TwingleProject::OUT);
$tmp_project->formatValues($returnValues[$project['id']], TwingleProject::OUT);
} }
catch (Exception $e) { catch (Exception $e) {
throw new API_Exception($e->getMessage()); throw new API_Exception($e->getMessage());

2
api/v3/TwingleSync/Sync.php
View file

@ -74,7 +74,7 @@ function civicrm_api3_twingle_sync_Sync($params) {
$is_test = $params['is_test']; $is_test = $params['is_test'];
} }
// If function call provides an API key, use it instead of the API key set // If call provides an API key, use it instead of the API key set
// on the extension settings page // on the extension settings page
$apiKey = empty($params['twingle_api_key']) $apiKey = empty($params['twingle_api_key'])
? trim(Civi::settings()->get('twingle_api_key')) ? trim(Civi::settings()->get('twingle_api_key'))