When invalidating a websites report, allow plugins to invalidate additional sites automatically (#12729)

* When invalidating a websites report, allow plugins to invalidate additional sites automatically

* Remame to Archiving.getIdSitesToMarkArchivesAsInvalidated

2 files changed, 27 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3c8c487be1..9a1f5c310f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@ This is the Developer Changelog for Matomo platform developers. All changes in o
 
 The Product Changelog at **[matomo.org/changelog](https://matomo.org/changelog)** lets you see more details about any Matomo release, such as the list of new guides and FAQs, security fixes, and links to all closed issues. 
 
+## Matomo 3.5.0
+* New event `Archiving.getIdSitesToMarkArchivesAsInvalidates` that lets plugins customize the behaviour of report invalidations.
+
 ## Matomo 3.4.0
 
 ### Breaking Changes
diff --git a/core/Archive/ArchiveInvalidator.php b/core/Archive/ArchiveInvalidator.php
index 6ecc5b8734..14140046aa 100644
--- a/core/Archive/ArchiveInvalidator.php
+++ b/core/Archive/ArchiveInvalidator.php
@@ -15,6 +15,7 @@ use Piwik\DataAccess\ArchiveTableCreator;
 use Piwik\DataAccess\Model;
 use Piwik\Date;
 use Piwik\Option;
+use Piwik\Piwik;
 use Piwik\Plugins\CoreAdminHome\Tasks\ArchivesToPurgeDistributedList;
 use Piwik\Plugins\PrivacyManager\PrivacyManager;
 use Piwik\Period;
@@ -135,6 +136,29 @@ class ArchiveInvalidator
     {
         $invalidationInfo = new InvalidationResult();
 
+        /**
+         * Triggered when a Matomo user requested the invalidation of some reporting archives. Using this event, plugin
+         * developers can automatically invalidate another site, when a site is being invalidated. A plugin may even
+         * remove an idSite from the list of sites that should be invalidated to prevent it from ever being
+         * invalidated.
+         *
+         * **Example**
+         *
+         *     public function getIdSitesToMarkArchivesAsInvalidates(&$idSites)
+         *     {
+         *         if (in_array(1, $idSites)) {
+         *             $idSites[] = 5; // when idSite 1 is being invalidated, also invalidate idSite 5
+         *         }
+         *     }
+         *
+         * @param array &$idSites An array containing a list of site IDs which are requested to be invalidated.
+         */
+        Piwik::postEvent('Archiving.getIdSitesToMarkArchivesAsInvalidated', array(&$idSites));
+        // we trigger above event on purpose here and it is good that the segment was created like
+        // `new Segment($segmentString, $idSites)` because when a user adds a site via this event, the added idSite
+        // might not have this segment meaning we avoid a possible error. For the workflow to work, any added or removed
+        // idSite does not need to be added to $segment.
+
         $datesToInvalidate = $this->removeDatesThatHaveBeenPurged($dates, $invalidationInfo);
 
         if (empty($period)) {