API Throw deprecation warnings for bad configuration (#10702)

src/Control/Director.php

@@ -73,7 +73,6 @@ 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;
 

src/Control/HTTPApplication.php

@@ -6,12 +6,15 @@
 use SilverStripe\Core\Application;
 use SilverStripe\Core\Environment;
 use SilverStripe\Core\Kernel;
+use SilverStripe\Core\Manifest\Module;
 use SilverStripe\Core\Startup\FlushDiscoverer;
 use SilverStripe\Core\Startup\CompositeFlushDiscoverer;
 use SilverStripe\Core\Startup\CallbackFlushDiscoverer;
 use SilverStripe\Core\Startup\RequestFlushDiscoverer;
 use SilverStripe\Core\Startup\ScheduledFlushDiscoverer;
 use SilverStripe\Core\Startup\DeployFlushDiscoverer;
+use SilverStripe\Dev\Deprecation;
+use SilverStripe\GraphQL\TypeCreator;
 
 /**
  * Invokes the HTTP application within an ErrorControlChain
@@ -133,6 +136,10 @@ public function execute(HTTPRequest $request, callable $callback, $flush = false
             return $this->callMiddleware($request, function ($request) use ($callback, $flush) {
                 // Pre-request boot
                 $this->getKernel()->boot($flush);
+
+                // This is the earliest point we can do this and guarantee it's hit exactly once per request.
+                $this->warnAboutDeprecatedSetups();
+
                 return call_user_func($callback, $request);
             });
         } catch (HTTPResponse_Exception $ex) {
@@ -141,4 +148,48 @@ public function execute(HTTPRequest $request, callable $callback, $flush = false
             $this->getKernel()->shutdown();
         }
     }
+
+    /**
+     * Trigger deprecation notices for legacy configuration which is deprecated but
+     * doesn't have deprecation notices directly on the relevant API
+     *
+     * Don't remove this method even if it's just a no-op - we'll reuse this mechanism
+     * in the future as needed.
+     */
+    private function warnAboutDeprecatedSetups()
+    {
+        // TypeCreator is a class unique to GraphQL v3 - we use it in other areas to detect
+        // which version is being used.
+        if (class_exists(TypeCreator::class)) {
+            Deprecation::notice(
+                '4.13.0',
+                'silverstripe/graphql 3.x is deprecated. Upgrade to 4.x instead.'
+                . ' See https://docs.silverstripe.org/en/4/upgrading/upgrading_to_graphql_4/',
+                Deprecation::SCOPE_GLOBAL
+            );
+        }
+
+        // The alternate_public_dir config property is deprecated, but because it's
+        // always fetched it'll throw a deprecation warning whether you've set it or not.
+        // There are also multiple mechanisms which can result in this bad configuration.
+        if (PUBLIC_DIR !== 'public' || Director::publicDir() !== PUBLIC_DIR) {
+            Deprecation::notice(
+                '4.13.0',
+                'Use of a public webroot other than "public" is deprecated.'
+                . ' See https://docs.silverstripe.org/en/4/changelogs/4.1.0#public-folder/',
+                Deprecation::SCOPE_GLOBAL
+            );
+        }
+
+        // This change of defaults has no other deprecation notice being emitted currently.
+        $project = new Module(BASE_PATH, BASE_PATH);
+        if ($project->getResourcesDir() === '') {
+            Deprecation::notice(
+                '4.13.0',
+                'The RESOURCES_DIR constant will change to "_resources" by default.'
+                . ' See https://docs.silverstripe.org/en/5/changelogs/5.0.0/#api-general',
+                Deprecation::SCOPE_GLOBAL
+            );
+        }
+    }
 }

src/Dev/Deprecation.php

@@ -10,19 +10,13 @@
 use SilverStripe\Core\Manifest\Module;
 
 /**
- * Handles raising an notice when accessing a deprecated method
+ * Handles raising an notice when accessing a deprecated method, class, configuration, or behaviour.
  *
- * A pattern used in SilverStripe when deprecating a method is to add something like
- *   user_error('This method is deprecated', E_USER_NOTICE);
- * to the method
- *
- * However sometimes we want to mark that a method will be deprecated in some future version and shouldn't be used in
+ * Sometimes we want to mark that a method will be deprecated in some future version and shouldn't be used in
  * new code, but not forbid in the current version - for instance when that method is still heavily used in framework
  * or cms.
  *
- * This class abstracts the above pattern and adds a way to do that.
- *
- * Each call to notice passes a version that the notice will be valid from.
+ * See https://docs.silverstripe.org/en/contributing/release_process/#deprecation
  */
 class Deprecation
 {

thirdparty/swiftmailer/Swift/MailTransport.php

@@ -5,6 +5,8 @@
  * It has been slightly modified to meet phpcs standards and initialise Swift_DependencyContainer
  */
 
+use SilverStripe\Dev\Deprecation;
+
 /*
  * This file is part of SwiftMailer.
  * (c) 2004-2009 Chris Corbyn
@@ -19,6 +21,7 @@
  * @author Chris Corbyn
  *
  * at deprecated since 5.4.5 (to be removed in 6.0)
+ * @deprecated 4.12.0 Sending email using the mail() function is deprecated. Use sendmail or SMTP instead
  */
 // @codingStandardsIgnoreStart
 // ignore missing namespace
@@ -32,6 +35,10 @@ class Swift_MailTransport extends Swift_Transport_MailTransport
      */
     public function __construct($extraParams = '-f%s')
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.12.0', 'Sending email using the mail() function is deprecated. Use sendmail or SMTP instead', Deprecation::SCOPE_CLASS);
+        });
+
         call_user_func_array(
             [$this, 'Swift_Transport_MailTransport::__construct'],
             $this->getDependencies() ?? []

thirdparty/swiftmailer/Swift/Transport/MailInvoker.php

@@ -17,6 +17,7 @@
  * This interface intercepts calls to the mail() function.
  *
  * @author     Chris Corbyn
+ * @deprecated 4.12.0 Will be replaced with symfony/mailer
  */
 // @codingStandardsIgnoreStart
 // ignore missing namespace

thirdparty/swiftmailer/Swift/Transport/MailTransport.php

@@ -5,6 +5,8 @@
  * It has been slightly modified to meet phpcs standards and to update method signatures to match the swiftmailer v6
  */
 
+use SilverStripe\Dev\Deprecation;
+
 /*
  * This file is part of SwiftMailer.
  * (c) 2004-2009 Chris Corbyn
@@ -26,7 +28,7 @@
  *
  * @author Chris Corbyn
  *
- * at deprecated since 5.4.5 (to be removed in 6.0)
+ * @deprecated 4.12.0 Sending email using the mail() function is deprecated. Use sendmail or SMTP instead
  */
 // @codingStandardsIgnoreStart
 // ignore missing namespace
@@ -50,6 +52,9 @@ class Swift_Transport_MailTransport implements Swift_Transport
      */
     public function __construct(Swift_Transport_MailInvoker $invoker, Swift_Events_EventDispatcher $eventDispatcher)
     {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.12.0', 'Sending email using the mail() function is deprecated. Use sendmail or SMTP instead', Deprecation::SCOPE_CLASS);
+        });
         // @trigger_error(sprintf('The %s class is deprecated since version 5.4.5 and will be removed in 6.0. Use the Sendmail or SMTP transport instead.', __CLASS__), E_USER_DEPRECATED);
 
         $this->_invoker = $invoker;

thirdparty/swiftmailer/Swift/Transport/SimpleMailInvoker.php

@@ -5,6 +5,8 @@
  * It has been slightly modified to meet phpcs standards
  */
 
+use SilverStripe\Dev\Deprecation;
+
 /*
  * This file is part of SwiftMailer.
  * (c) 2004-2009 Chris Corbyn
@@ -17,12 +19,20 @@
  * This is the implementation class for {@link Swift_Transport_MailInvoker}.
  *
  * @author     Chris Corbyn
+ * @deprecated 4.12.0 Sending email using the mail() function is deprecated. Use sendmail or SMTP instead
  */
 // @codingStandardsIgnoreStart
 // ignore missing namespace
 class Swift_Transport_SimpleMailInvoker implements Swift_Transport_MailInvoker
 // @codingStandardsIgnoreEnd* It has been slightly modified to meet phpcs standards
 {
+    public function __construct()
+    {
+        Deprecation::withNoReplacement(function () {
+            Deprecation::notice('4.12.0', 'Sending email using the mail() function is deprecated. Use sendmail or SMTP instead', Deprecation::SCOPE_CLASS);
+        });
+    }
+
     /**
      * Send mail via the mail() function.
      *