Warn when calling UrlManager methods before Craft is initialized + im…

…proved doc blocks

resolves #3028

CHANGELOG-v3.md

@@ -16,6 +16,7 @@
 - Web-based queue workers now call `craft\helpers\App::maxPowerCaptain()` before running the queue. ([#3011](https://github.com/craftcms/cms/issues/3011))
 - The PHP Info utility no longer displays the original values for settings and only the current environment value. ([#2990](https://github.com/craftcms/cms/issues/2990))
 - Loosened up most of Craft’s Composer dependency constraints.
+- `craft\web\UrlManager::createUrl()`, `createAbsoluteUrl()`, and `getMatchedElement()` now log warnings if they’re called before Craft has been fully initialized. ([#3028](https://github.com/craftcms/cms/issues/3028))
 
 ### Fixed
 - Fixed a bug where sidebar meta info on Edit User pages was bleeding over the edge of the page’s content area.

src/web/UrlManager.php

@@ -11,6 +11,7 @@
 use craft\base\Element;
 use craft\base\ElementInterface;
 use craft\events\RegisterUrlRulesEvent;
+use craft\helpers\App;
 use craft\helpers\ArrayHelper;
 use craft\helpers\UrlHelper;
 use craft\web\UrlRule as CraftUrlRule;
@@ -30,9 +31,12 @@ class UrlManager extends \yii\web\UrlManager
      * @event RegisterUrlRulesEvent The event that is triggered when registering
      * URL rules for the Control Panel.
      *
+     * ::: warning
      * This event gets called during class initialization, so you should always
      * use a class-level event handler.
+     * :::
      *
+     * ---
      * ```php
      * use craft\events\RegisterUrlRulesEvent;
      * use craft\web\UrlManager;
@@ -48,9 +52,12 @@ class UrlManager extends \yii\web\UrlManager
      * @event RegisterUrlRulesEvent The event that is triggered when registering
      * URL rules for the front-end site.
      *
+     * ::: warning
      * This event gets called during class initialization, so you should always
      * use a class-level event handler.
+     * :::
      *
+     * ---
      * ```php
      * use craft\events\RegisterUrlRulesEvent;
      * use craft\web\UrlManager;
@@ -130,6 +137,11 @@ public function parseRequest($request)
      */
     public function createUrl($params)
     {
+        if (!Craft::$app->getIsInitialized()) {
+            Craft::warning(__METHOD__ . "() was called before the application was fully initialized.\n" .
+                "Stack trace:\n" . App::backtrace(), __METHOD__);
+        }
+
         $params = (array)$params;
         unset($params[$this->routeParam]);
 
@@ -144,6 +156,11 @@ public function createUrl($params)
      */
     public function createAbsoluteUrl($params, $scheme = null)
     {
+        if (!Craft::$app->getIsInitialized()) {
+            Craft::warning(__METHOD__ . "() was called before the application was fully initialized.\n" .
+                "Stack trace:\n" . App::backtrace(), __METHOD__);
+        }
+
         $params = (array)$params;
         unset($params[$this->routeParam]);
 
@@ -179,10 +196,30 @@ public function setRouteParams(array $params)
     /**
      * Returns the element that was matched by the URI.
      *
+     * ::: warning
+     * This should only be called once the application has been fully initialized.
+     * Otherwise some plugins may be unable to register [[EVENT_REGISTER_CP_URL_RULES]]
+     * and [[EVENT_REGISTER_SITE_URL_RULES]] event handlers successfully.
+     * :::
+     *
+     * ---
+     * ```php
+     * use craft\web\Application;
+     *
+     * Craft::$app->on(Application::EVENT_INIT, function() {
+     *     $element = Craft::$app->urlManager->getMatchedElement();
+     * }
+     * ```
+     *
      * @return ElementInterface|false
      */
     public function getMatchedElement()
     {
+        if (!Craft::$app->getIsInitialized()) {
+            Craft::warning(__METHOD__ . "() was called before the application was fully initialized.\n" .
+                "Stack trace:\n" . App::backtrace(), __METHOD__);
+        }
+
         if ($this->_matchedElement !== null) {
             return $this->_matchedElement;
         }