API Deprecate code

src/Control/Director.php

@@ -73,6 +73,7 @@ class Director implements TemplateGlobalProvider
     /**
      * @config
      * @var string
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     private static $alternate_base_folder;
 
@@ -82,6 +83,7 @@ class Director implements TemplateGlobalProvider
      *
      * @config
      * @var bool|null
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     private static $alternate_public_dir = null;
 

src/Control/Email/Email.php

@@ -115,7 +115,9 @@ class Email extends ViewableData
      */
     public static function getSendAllEmailsTo()
     {
-        return static::mergeConfiguredEmails('send_all_emails_to', 'SS_SEND_ALL_EMAILS_TO');
+        return Deprecation::withNoReplacement(function () {
+            return static::mergeConfiguredEmails('send_all_emails_to', 'SS_SEND_ALL_EMAILS_TO');
+        });
     }
 
     /**
@@ -125,7 +127,9 @@ class Email extends ViewableData
      */
     public static function getCCAllEmailsTo()
     {
-        return static::mergeConfiguredEmails('cc_all_emails_to', 'SS_CC_ALL_EMAILS_TO');
+        return Deprecation::withNoReplacement(function () {
+            return static::mergeConfiguredEmails('cc_all_emails_to', 'SS_CC_ALL_EMAILS_TO');
+        });
     }
 
     /**
@@ -135,7 +139,9 @@ class Email extends ViewableData
      */
     public static function getBCCAllEmailsTo()
     {
-        return static::mergeConfiguredEmails('bcc_all_emails_to', 'SS_BCC_ALL_EMAILS_TO');
+        return Deprecation::withNoReplacement(function () {
+            return static::mergeConfiguredEmails('bcc_all_emails_to', 'SS_BCC_ALL_EMAILS_TO');
+        });
     }
 
     /**
@@ -145,7 +151,9 @@ class Email extends ViewableData
      */
     public static function getSendAllEmailsFrom()
     {
-        return static::mergeConfiguredEmails('send_all_emails_from', 'SS_SEND_ALL_EMAILS_FROM');
+        return Deprecation::withNoReplacement(function () {
+            return static::mergeConfiguredEmails('send_all_emails_from', 'SS_SEND_ALL_EMAILS_FROM');
+        });
     }
 
     /**
@@ -154,9 +162,11 @@ class Email extends ViewableData
      * @param string $config Config key
      * @param string $env Env variable key
      * @return array Array of email addresses
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     protected static function mergeConfiguredEmails($config, $env)
     {
+        Deprecation::notice('4.13.0', 'Will be removed without equivalent functionality to replace it');
         // Normalise config list
         $normalised = [];
         $source = (array)static::config()->get($config);

src/Control/HTTP.php

@@ -576,9 +576,11 @@ class HTTP
      * Return static variable cache_age in second
      *
      * @return int
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     public static function get_cache_age()
     {
+        Deprecation::notice('4.13.0', 'Will be removed without equivalent functionality to replace it');
         return self::$cache_age;
     }
 }

src/Core/BaseKernel.php

@@ -276,7 +276,9 @@ abstract class BaseKernel implements Kernel
         }
 
         // Check saved session
-        $env = $this->sessionEnvironment();
+        $env = Deprecation::withNoReplacement(function () {
+            return $this->sessionEnvironment();
+        });
         if ($env) {
             return $env;
         }
@@ -293,9 +295,11 @@ abstract class BaseKernel implements Kernel
      * Check or update any temporary environment specified in the session.
      *
      * @return null|string
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     protected function sessionEnvironment()
     {
+        Deprecation::notice('4.13.0', 'Will be removed without equivalent functionality to replace it.');
         if (!$this->booted) {
             // session is not initialyzed yet, neither is manifest
             return null;

src/Core/CustomMethods.php

@@ -193,9 +193,11 @@ trait CustomMethods
     /**
      * @param object $extension
      * @return array
+     * @deprecated 4.13.0 Will be replaced by findMethodsFrom() in CMS 5
      */
     protected function findMethodsFromExtension($extension)
     {
+        Deprecation::notice('4.13.0', 'Will be replaced by findMethodsFrom() in CMS 5');
         if (method_exists($extension, 'allMethodNames')) {
             if ($extension instanceof Extension) {
                 try {
@@ -236,7 +238,9 @@ trait CustomMethods
             );
         }
 
-        $methods = $this->findMethodsFromExtension($extension);
+        $methods = Deprecation::withNoReplacement(function () use ($extension) {
+            return $this->findMethodsFromExtension($extension);
+        });
         if ($methods) {
             if ($extension instanceof Extension) {
                 Deprecation::notice(
@@ -279,7 +283,9 @@ trait CustomMethods
             );
         }
 
-        $methods = $this->findMethodsFromExtension($extension);
+        $methods = Deprecation::withNoReplacement(function () use ($extension) {
+            return $this->findMethodsFromExtension($extension);
+        });
         if ($methods) {
             foreach ($methods as $method) {
                 if (!isset(self::$extra_methods[$class][$method])) {

src/Core/Extensible.php

@@ -131,7 +131,10 @@ trait Extensible
     {
         $extensions = $this->getExtensionInstances();
         foreach ($extensions as $extensionClass => $extensionInstance) {
-            foreach ($this->findMethodsFromExtension($extensionInstance) as $method) {
+            $methods = Deprecation::withNoReplacement(function () use ($extensionInstance) {
+                return $this->findMethodsFromExtension($extensionInstance);
+            });
+            foreach ($methods as $method) {
                 $this->addCallbackMethod($method, function ($inst, $args) use ($method, $extensionClass) {
                     /** @var Extensible $inst */
                     $extension = $inst->getExtensionInstance($extensionClass);

src/Dev/Tasks/MigrateFileTask.php

@@ -57,7 +57,13 @@ class MigrateFileTask extends BuildTask
 
     public function __construct()
     {
-        Deprecation::notice('4.12.0', 'Will be removed without equivalent functionality to replace it', Deprecation::SCOPE_CLASS);
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice(
+                '4.13.0',
+                'Will be removed without equivalent functionality to replace it',
+                Deprecation::SCOPE_CLASS
+            );
+        });
         parent::__construct();
     }
 

src/Dev/TestMailer.php

@@ -4,11 +4,13 @@ namespace SilverStripe\Dev;
 
 use SilverStripe\Control\Email\Mailer;
 use Swift_Attachment;
+use SilverStripe\Dev\Deprecation;
 
 class TestMailer implements Mailer
 {
     /**
      * @var array
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     protected $emailsSent = [];
 
@@ -58,7 +60,9 @@ class TestMailer implements Mailer
             $serialised['HtmlContent'] = $htmlContent;
         }
 
-        $this->saveEmail($serialised);
+        Deprecation::withNoReplacement(function () use ($serialised) {
+            $this->saveEmail($serialised);
+        });
 
         return true;
     }
@@ -67,9 +71,11 @@ class TestMailer implements Mailer
      * Save a single email to the log
      *
      * @param array $data A map of information about the email
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     protected function saveEmail($data)
     {
+        Deprecation::notice('4.13.0', 'Will be removed without equivalent functionality to replace it');
         $this->emailsSent[] = $data;
     }
 

src/ORM/Connect/MySQLQuery.php

@@ -2,6 +2,8 @@
 
 namespace SilverStripe\ORM\Connect;
 
+use SilverStripe\Dev\Deprecation;
+
 /**
  * A result-set from a MySQL database (using MySQLiConnector)
  * Note that this class is only used for the results of non-prepared statements
@@ -45,16 +47,22 @@ class MySQLQuery extends Query
         }
     }
 
+    /**
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
+     */
     public function seek($row)
     {
-        if (is_object($this->handle)) {
+        return Deprecation::withNoReplacement(function () use ($row) {
-            // Fix for https://github.com/silverstripe/silverstripe-framework/issues/9097 without breaking the seek() API
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
-            $this->handle->data_seek($row);
+            if (is_object($this->handle)) {
-            $result = $this->nextRecord();
+                // Fix for https://github.com/silverstripe/silverstripe-framework/issues/9097 without breaking the seek() API
-            $this->handle->data_seek($row);
+                $this->handle->data_seek($row);
-            return $result;
+                $result = $this->nextRecord();
-        }
+                $this->handle->data_seek($row);
-        return null;
+                return $result;
+            }
+            return null;
+        });
     }
 
     public function numRecords()
@@ -65,8 +73,14 @@ class MySQLQuery extends Query
         return null;
     }
 
+    /**
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
+     */
     public function nextRecord()
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
+        });
         $floatTypes = [MYSQLI_TYPE_FLOAT, MYSQLI_TYPE_DOUBLE, MYSQLI_TYPE_DECIMAL, MYSQLI_TYPE_NEWDECIMAL];
 
         if (is_object($this->handle) && ($row = $this->handle->fetch_array(MYSQLI_NUM))) {

src/ORM/Connect/MySQLStatement.php

@@ -4,6 +4,7 @@ namespace SilverStripe\ORM\Connect;
 
 use mysqli_result;
 use mysqli_stmt;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * Provides a record-view for mysqli prepared statements
@@ -102,15 +103,21 @@ class MySQLStatement extends Query
         $this->currentRecord = false;
     }
 
+    /**
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
+     */
     public function seek($row)
     {
-        $this->rowNum = $row - 1;
+        return Deprecation::withNoReplacement(function () use ($row) {
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
+            $this->rowNum = $row - 1;
 
-        // Fix for https://github.com/silverstripe/silverstripe-framework/issues/9097 without breaking the seek() API
+            // Fix for https://github.com/silverstripe/silverstripe-framework/issues/9097 without breaking the seek() API
-        $this->statement->data_seek($row);
+            $this->statement->data_seek($row);
-        $result = $this->next();
+            $result = $this->next();
-        $this->statement->data_seek($row);
+            $this->statement->data_seek($row);
-        return $result;
+            return $result;
+        });
     }
 
     public function numRecords()
@@ -118,8 +125,14 @@ class MySQLStatement extends Query
         return $this->statement->num_rows();
     }
 
+    /**
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
+     */
     public function nextRecord()
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
+        });
         // Skip data if out of data
         if (!$this->statement->fetch()) {
             return false;

src/ORM/Connect/PDOConnector.php

@@ -11,6 +11,8 @@ use PDOException;
 
 /**
  * PDO driver database connector
+ *
+ * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
  */
 class PDOConnector extends DBConnector implements TransactionManager
 {
@@ -87,6 +89,17 @@ class PDOConnector extends DBConnector implements TransactionManager
      */
     protected $inTransaction = false;
 
+    public function __construct()
+    {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice(
+                '4.13.0',
+                'Will be removed without equivalent functionality to replace it',
+                Deprecation::SCOPE_CLASS
+            );
+        });
+    }
+
     /**
      * Flush all prepared statements
      */

src/ORM/Connect/PDOQuery.php

@@ -2,8 +2,12 @@
 
 namespace SilverStripe\ORM\Connect;
 
+use SilverStripe\Dev\Deprecation;
+
 /**
  * A result-set from a PDO database.
+ *
+ * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
  */
 class PDOQuery extends Query
 {
@@ -18,10 +22,16 @@ class PDOQuery extends Query
      */
     public function __construct(PDOStatementHandle $statement)
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice(
+                '4.13.0',
+                'Will be removed without equivalent functionality to replace it',
+                Deprecation::SCOPE_CLASS
+            );
+        });
         // Since no more than one PDOStatement for any one connection can be safely
         // traversed, each statement simply requests all rows at once for safety.
         // This could be re-engineered to call fetchAll on an as-needed basis
-
         $this->results = $statement->typeCorrectedFetchAll();
         $statement->closeCursor();
     }

src/ORM/Connect/PDOStatementHandle.php

@@ -4,6 +4,7 @@ namespace SilverStripe\ORM\Connect;
 
 use PDO;
 use PDOStatement;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * A handle to a PDOStatement, with cached column metadata, and type conversion
@@ -11,6 +12,8 @@ use PDOStatement;
  * Column metadata can't be fetched from a native PDOStatement after multiple calls in some DB backends,
  * so we wrap in this handle object, which also takes care of tidying up content types to keep in line
  * with the SilverStripe 4.4+ type expectations.
+ *
+ * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
  */
 class PDOStatementHandle
 {
@@ -36,6 +39,13 @@ class PDOStatementHandle
      */
     public function __construct(PDOStatement $statement)
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice(
+                '4.13.0',
+                'Will be removed without equivalent functionality to replace it',
+                Deprecation::SCOPE_CLASS
+            );
+        });
         $this->statement = $statement;
     }
 

src/ORM/Connect/Query.php

@@ -4,6 +4,7 @@ namespace SilverStripe\ORM\Connect;
 
 use SilverStripe\Core\Convert;
 use Iterator;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * Abstract query-result class. A query result provides an iterator that returns a map for each record of a query
@@ -34,6 +35,7 @@ abstract class Query implements Iterator
      * The current record in the iterator.
      *
      * @var array
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     protected $currentRecord = null;
 
@@ -41,6 +43,7 @@ abstract class Query implements Iterator
      * The number of the current row in the iterator.
      *
      * @var int
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     protected $rowNum = -1;
 
@@ -48,6 +51,7 @@ abstract class Query implements Iterator
      * Flag to keep track of whether iteration has begun, to prevent unnecessary seeks
      *
      * @var bool
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     protected $queryHasBegun = false;
 
@@ -169,52 +173,68 @@ abstract class Query implements Iterator
      * Makes use of {@link seek()} and {@link numRecords()}, takes care of the plumbing.
      *
      * @return void
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     #[\ReturnTypeWillChange]
     public function rewind()
     {
-        if ($this->queryHasBegun && $this->numRecords() > 0) {
+        Deprecation::withNoReplacement(function () {
-            $this->queryHasBegun = false;
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
-            $this->currentRecord = null;
+            if ($this->queryHasBegun && $this->numRecords() > 0) {
-            $this->seek(0);
+                $this->queryHasBegun = false;
-        }
+                $this->currentRecord = null;
+                $this->seek(0);
+            }
+        });
     }
 
     /**
      * Iterator function implementation. Return the current item of the iterator.
      *
      * @return array
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     #[\ReturnTypeWillChange]
     public function current()
     {
-        if (!$this->currentRecord) {
+        return Deprecation::withNoReplacement(function () {
-            return $this->next();
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
-        } else {
+            if (!$this->currentRecord) {
-            return $this->currentRecord;
+                return $this->next();
-        }
+            } else {
+                return $this->currentRecord;
+            }
+        });
     }
 
     /**
      * Iterator function implementation. Return the first item of this iterator.
      *
      * @return array
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     public function first()
     {
-        $this->rewind();
+        return Deprecation::withNoReplacement(function () {
-        return $this->current();
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
+            $this->rewind();
+            return $this->current();
+        });
     }
 
     /**
      * Iterator function implementation. Return the row number of the current item.
      *
      * @return int
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     #[\ReturnTypeWillChange]
     public function key()
     {
-        return $this->rowNum;
+        return Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
+            return $this->rowNum;
+        });
     }
 
     /**
@@ -222,34 +242,43 @@ abstract class Query implements Iterator
      * Makes use of {@link nextRecord()}, takes care of the plumbing.
      *
      * @return array
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     #[\ReturnTypeWillChange]
     public function next()
     {
-        $this->queryHasBegun = true;
+        return Deprecation::withNoReplacement(function () {
-        $this->currentRecord = $this->nextRecord();
+            Deprecation::notice('4.13.0', 'Will be replaced by getIterator() in CMS 5');
-        $this->rowNum++;
+            $this->queryHasBegun = true;
-        return $this->currentRecord;
+            $this->currentRecord = $this->nextRecord();
+            $this->rowNum++;
+            return $this->currentRecord;
+        });
     }
 
     /**
      * Iterator function implementation. Check if the iterator is pointing to a valid item.
      *
      * @return bool
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     #[\ReturnTypeWillChange]
     public function valid()
     {
-        if (!$this->queryHasBegun) {
+        return Deprecation::withNoReplacement(function () {
-            $this->next();
+            Deprecation::notice('4.13.0', 'Will be removed without equivalent functionality to replace it.');
-        }
+            if (!$this->queryHasBegun) {
-        return $this->currentRecord !== false;
+                $this->next();
+            }
+            return $this->currentRecord !== false;
+        });
     }
 
     /**
      * Return the next record in the query result.
      *
      * @return array
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     abstract public function nextRecord();
 
@@ -265,6 +294,7 @@ abstract class Query implements Iterator
      *
      * @param int $rowNum Row number to go to.
      * @return array
+     * @deprecated 4.13.0 Will be replaced by getIterator() in CMS 5
      */
     abstract public function seek($rowNum);
 }

src/ORM/DataList.php

@@ -11,6 +11,7 @@ use ArrayIterator;
 use Exception;
 use InvalidArgumentException;
 use LogicException;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * Implements a "lazy loading" DataObjectSet.
@@ -785,9 +786,13 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
      * Returns a generator for this DataList
      *
      * @return \Generator&DataObject[]
+     * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
      */
     public function getGenerator()
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.13.0', 'Will be removed without equivalent functionality to replace it');
+        });
         $query = $this->dataQuery->query()->execute();
 
         while ($row = $query->record()) {

src/ORM/Map_Iterator.php

@@ -3,9 +3,12 @@
 namespace SilverStripe\ORM;
 
 use Iterator;
+use SilverStripe\Dev\Deprecation;
 
 /**
  * Builds a map iterator around an Iterator.  Called by Map
+ *
+ * @deprecated 4.13.0 Will be removed without equivalent functionality to replace it
  */
 class Map_Iterator implements Iterator
 {
@@ -35,6 +38,13 @@ class Map_Iterator implements Iterator
      */
     public function __construct(Iterator $items, $keyField, $titleField, $firstItems = null, $lastItems = null)
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice(
+                '4.13.0',
+                'Will be removed without equivalent functionality to replace it',
+                Deprecation::SCOPE_CLASS
+            );
+        });
         $this->items = $items;
         $this->keyField = $keyField;
         $this->titleField = $titleField;