refs #6508 add some comments

core/ArchiveProcessor/Rules.php

@@ -128,11 +128,13 @@ class Rules
     }
 
     /**
-     * Given a monthly archive table, will delete all reports that are now outdated,
-     * or reports that ended with an error
+     * Returns false if we should not purge data for this month,
+     * or returns a timestamp indicating outdated archives older than this timestamp (processed before) can be purged.
+     *
+     * Note: when calling this function it is assumed that the callee will purge the outdated archives afterwards.
      *
      * @param \Piwik\Date $date
-     * @return int|bool  False, or timestamp indicating which archives to delete
+     * @return int|bool  Outdated archives older than this timestamp should be purged
      */
     public static function shouldPurgeOutdatedArchives(Date $date)
     {

core/DataAccess/ArchivePurger.php

@@ -24,7 +24,6 @@ class ArchivePurger
 {
     public static function purgeInvalidatedArchives()
     {
-
         $archiveTables = ArchiveTableCreator::getTablesArchivesInstalled();
 
         foreach ($archiveTables as $archiveTable) {
@@ -56,6 +55,12 @@ class ArchivePurger
         return new Model();
     }
 
+    /**
+     * Removes the outdated archives for the given month.
+     * (meaning they are marked with a done flag of ArchiveWriter::DONE_OK_TEMPORARY or ArchiveWriter::DONE_ERROR)
+     *
+     * @param Date $dateStart Only the month will be used
+     */
     public static function purgeOutdatedArchives(Date $dateStart)
     {
         $purgeArchivesOlderThan = Rules::shouldPurgeOutdatedArchives($dateStart);
@@ -64,7 +69,7 @@ class ArchivePurger
             return;
         }
 
-        $idArchivesToDelete = self::getTemporaryArchiveIdsOlderThan($dateStart, $purgeArchivesOlderThan);
+        $idArchivesToDelete = self::getOutdatedArchiveIds($dateStart, $purgeArchivesOlderThan);
 
         if (!empty($idArchivesToDelete)) {
             self::deleteArchiveIds($dateStart, $idArchivesToDelete);
@@ -78,7 +83,7 @@ class ArchivePurger
                    implode(',', $idArchivesToDelete));
     }
 
-    protected static function getTemporaryArchiveIdsOlderThan(Date $date, $purgeArchivesOlderThan)
+    protected static function getOutdatedArchiveIds(Date $date, $purgeArchivesOlderThan)
     {
         $archiveTable = ArchiveTableCreator::getNumericTable($date);
 
@@ -94,8 +99,10 @@ class ArchivePurger
         return $idArchivesToDelete;
     }
 
-    /*
-     * Deleting "Custom Date Range" reports after 1 day, since they can be re-processed and would take up un-necessary space
+    /**
+     * Deleting "Custom Date Range" reports after 1 day, since they can be re-processed and would take up un-necessary space.
+     *
+     * @param $date Date
      */
     protected static function deleteArchivesWithPeriodRange(Date $date)
     {
@@ -103,12 +110,18 @@ class ArchivePurger
         $blobTable    = ArchiveTableCreator::getBlobTable($date);
         $yesterday    = Date::factory('yesterday')->getDateTime();
 
-        Log::debug("Purging Custom Range archives: done [ purged archives older than %s from %s / blob ]",
-                   $yesterday, $numericTable);
+        self::getModel()->deleteArchivesWithPeriod($numericTable, $blobTable, Piwik::$idPeriods['range'], $yesterday);
 
-        self::getModel()->deleteArchivesWithPeriodRange($numericTable, $blobTable, Piwik::$idPeriods['range'], $yesterday);
+        Log::debug("Purging Custom Range archives: done [ purged archives older than %s from %s / blob ]",
+            $yesterday, $numericTable);
     }
 
+    /**
+     * Deletes by batches Archive IDs in the specified month,
+     *
+     * @param Date $date
+     * @param $idArchivesToDelete
+     */
     protected static function deleteArchiveIds(Date $date, $idArchivesToDelete)
     {
         $batches      = array_chunk($idArchivesToDelete, 1000);

core/DataAccess/Model.php

@@ -55,13 +55,10 @@ class Model
         return Db::fetchAll($query, array($purgeArchivesOlderThan));
     }
 
-    /*
-     * Deleting "Custom Date Range" reports, since they can be re-processed and would take up un-necessary space
-     */
-    public function deleteArchivesWithPeriodRange($numericTable, $blobTable, $range, $date)
+    public function deleteArchivesWithPeriod($numericTable, $blobTable, $period, $date)
     {
         $query = "DELETE FROM %s WHERE period = ? AND ts_archived < ?";
-        $bind  = array($range, $date);
+        $bind  = array($period, $date);
 
         Db::query(sprintf($query, $numericTable), $bind);