Add a helper for posting an event when something is copied (#23664)

Author: snake14

plugins/CoreHome/EntityDuplicator/DuplicateRequestResponse.php

@@ -11,8 +11,10 @@
 
 namespace Piwik\Plugins\CoreHome\EntityDuplicator;
 
+use Piwik\Piwik;
+
 /**
- *
+ * The object for building a consistent response to the duplication of an entity.
  */
 class DuplicateRequestResponse
 {
@@ -36,6 +38,15 @@ class DuplicateRequestResponse
      */
     protected $additionalData;
 
+    /**
+     * @var array Optional array containing the data required for the event to be posted on success. If set, the event
+     *   will be triggered when the getResponseArray method is called.
+     *
+     * @see self::setRequestDataForEvent()
+     * @see self::getResponseArray()
+     */
+    protected $eventDataToPost;
+
     /**
      * Get an instance of the object and store it's initial state for comparison later
      */
@@ -135,6 +146,11 @@ public function getResponseArray(): array
             throw new \Exception('No duplicate request response properties were set.');
         }
 
+        // If the flag is set to post the event and the request was successful, post the event for the duplication
+        if ($this->success && $this->eventDataToPost !== null) {
+            Piwik::postEvent('EntityDuplicator.DuplicationSuccessful', $this->eventDataToPost);
+        }
+
         return $responseArray;
     }
 
@@ -145,9 +161,45 @@ private function getCurrentState(): array
     {
         // Get an array of all the property values
         $state = get_object_vars($this);
-        // Exclude the state property
+        // Exclude the state property and eventDataToPost
         unset($state['initialState']);
+        unset($state['eventDataToPost']);
 
         return $state;
     }
+
+    /**
+     * Set the arguments to be used while posting the event when the response array is built. This is used by plugins
+     *   which use this class while generating the response to a duplication request.
+     *
+     * @param string $entityTypeTranslation Translation key for the name of the type of entity. E.g. Goals_Goal,
+     *   Heatmaps_Heatmap, etc.
+     * @param string $entityName The name of the entity being copied. E.g. 'Goal that does thing' or'Home page heatmap'.
+     * @param int|null $idEntity The ID of the entity being copied. E.g. 2 or 900. It's optional since some entities
+     *   might only have a string identifier which should be provided as the entityName.
+     * @param int|null $idSite ID of the source site. It's optional in case the entity being copied is not site scoped,
+     *   like a system-wide configuration.
+     * @param array|null $idDestinationSites IDs of the destination sites. This is optional for the same reason as
+     *   idSite but also since it doesn't need to be provided if the only destination site is the source site (idSite).
+     * @param array|null $additionalData Optional array of additional data relating to the entity being copied.
+     *
+     * @return void
+     */
+    public function setRequestDataForEvent(
+        string $entityTypeTranslation,
+        string $entityName,
+        ?int $idEntity = null,
+        ?int $idSite = null,
+        ?array $idDestinationSites = null,
+        ?array $additionalData = null
+    ): void {
+        $this->eventDataToPost = [
+            $entityTypeTranslation,
+            $entityName,
+            $idEntity,
+            $idSite,
+            $idDestinationSites,
+            $additionalData,
+        ];
+    }
 }