Add an iterator to make it easier to perform database migrations

Summary: See D3006, D3007. Make it easier to do migrations like that without holding all results in memory.

Test Plan:
Ran this code with an artificially small page size (2):

  foreach (new LiskMigrationIterator(new DifferentialRevision()) as $rev) {
    echo "Revision ".$rev->getID()."\n";
  }

Verified each revision as loaded and processed.

Reviewers: vrana, btrahan

Reviewed By: btrahan

CC: aran

Maniphest Tasks: T1162

Differential Revision: https://secure.phabricator.com/D3008

src/__phutil_library_map__.php

@@ -492,6 +492,7 @@ phutil_register_library_map(array(
     'LiskIsolationTestCase' => 'infrastructure/storage/lisk/__tests__/LiskIsolationTestCase.php',
     'LiskIsolationTestDAO' => 'infrastructure/storage/lisk/__tests__/LiskIsolationTestDAO.php',
     'LiskIsolationTestDAOException' => 'infrastructure/storage/lisk/__tests__/LiskIsolationTestDAOException.php',
+    'LiskMigrationIterator' => 'infrastructure/storage/lisk/LiskMigrationIterator.php',
     'ManiphestAction' => 'applications/maniphest/constants/ManiphestAction.php',
     'ManiphestAuxiliaryFieldDefaultSpecification' => 'applications/maniphest/auxiliaryfield/ManiphestAuxiliaryFieldDefaultSpecification.php',
     'ManiphestAuxiliaryFieldSpecification' => 'applications/maniphest/auxiliaryfield/ManiphestAuxiliaryFieldSpecification.php',
@@ -1231,7 +1232,7 @@ phutil_register_library_map(array(
     'ConduitAPI_differential_close_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_createcomment_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_creatediff_Method' => 'ConduitAPIMethod',
-    'ConduitAPI_differential_createinline_Method' => 'ConduitAPIMethod',
+    'ConduitAPI_differential_createinline_Method' => 'ConduitAPI_differential_Method',
     'ConduitAPI_differential_createrawdiff_Method' => 'ConduitAPI_differential_Method',
     'ConduitAPI_differential_createrevision_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_find_Method' => 'ConduitAPIMethod',
@@ -1241,7 +1242,7 @@ phutil_register_library_map(array(
     'ConduitAPI_differential_getcommitpaths_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_getdiff_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_getrevision_Method' => 'ConduitAPIMethod',
-    'ConduitAPI_differential_getrevisioncomments_Method' => 'ConduitAPIMethod',
+    'ConduitAPI_differential_getrevisioncomments_Method' => 'ConduitAPI_differential_Method',
     'ConduitAPI_differential_getrevisionfeedback_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_markcommitted_Method' => 'ConduitAPIMethod',
     'ConduitAPI_differential_parsecommitmessage_Method' => 'ConduitAPIMethod',
@@ -1536,6 +1537,7 @@ phutil_register_library_map(array(
     'LiskIsolationTestCase' => 'PhabricatorTestCase',
     'LiskIsolationTestDAO' => 'LiskDAO',
     'LiskIsolationTestDAOException' => 'Exception',
+    'LiskMigrationIterator' => 'Iterator',
     'ManiphestAction' => 'ManiphestConstants',
     'ManiphestAuxiliaryFieldDefaultSpecification' => 'ManiphestAuxiliaryFieldSpecification',
     'ManiphestAuxiliaryFieldTypeException' => 'Exception',

src/infrastructure/storage/lisk/LiskMigrationIterator.php

@@ -0,0 +1,77 @@
+<?php
+
+/*
+ * Copyright 2012 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Iterate over every object of a given type, without holding all of them in
+ * memory. This is useful for performing database migrations.
+ *
+ *   $things = new LiskMigrationIterator(new LiskThing());
+ *   foreach ($things as $thing) {
+ *     // do something
+ *   }
+ *
+ * NOTE: This only works on objects with a normal `id` column.
+ *
+ * @task storage
+ */
+final class LiskMigrationIterator implements Iterator {
+
+  private $object;
+  private $cursor;
+  private $data;
+
+  public function __construct(LiskDAO $object) {
+    $this->object = $object;
+  }
+
+  public function rewind() {
+    $this->cursor = 0;
+    $this->data = array();
+    $this->next();
+  }
+
+  public function valid() {
+    if (!$this->data) {
+      $this->next();
+    }
+    return (bool)$this->data;
+  }
+
+  public function current() {
+    return end($this->data);
+  }
+
+  public function key() {
+    return $this->current()->getID();
+  }
+
+  public function next() {
+    if ($this->data) {
+      return array_pop($this->data);
+    }
+    $this->data = $this->object->loadAllWhere(
+      'id > %d ORDER BY id ASC LIMIT %d',
+      $this->cursor,
+      100);
+    if ($this->data) {
+      $this->cursor = last($this->data)->getID();
+      $this->data = array_reverse($this->data);
+    }
+  }
+
+}