Deprecate the craft.retcon variable

CHANGELOG.md

@@ -6,4 +6,6 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## 3.0.0 - 2024-03-28
 ### Added
-- Craft 5.0 compatibility
+- Added Craft 5.0 compatibility
+### Changed
+- Deprecated the `craft.retcon` variable

README.md

@@ -109,7 +109,7 @@ public function init() {
 
 A "selector" in Retcon is the same thing as a selector in CSS – i.e. something like `'img'`, `'.foo'` or `h3 + p`.
 
-In Retcon 2.x, _almost all CSS selectors_ will work – see the [CssSelector](https://symfony.com/doc/3.3/components/css_selector.html) docs for further details on selectors.
+In Retcon 2+, _almost all CSS selectors_ will work – see the [CssSelector](https://symfony.com/doc/3.3/components/css_selector.html) docs for further details on selectors.
 
 #### Multiple selectors
 

src/Retcon.php

@@ -9,6 +9,7 @@
 use mmikkel\retcon\services\RetconService;
 use mmikkel\retcon\twigextensions\RetconTwigExtension;
 use mmikkel\retcon\models\RetconSettings;
+use mmikkel\retcon\variables\RetconVariable;
 
 use yii\base\Event;
 
@@ -36,14 +37,14 @@ public function init()
         // Add in our Twig extensions
         Craft::$app->getView()->registerTwigExtension(new RetconTwigExtension());
 
-        // Register our variables
+        // Register our variables (this is deprecated in Retcon 3.0.0 and will be removed in Retcon 4)
         Event::on(
             CraftVariable::class,
             CraftVariable::EVENT_INIT,
             function (Event $event) {
                 /** @var CraftVariable $variable */
                 $variable = $event->sender;
-                $variable->set('retcon', RetconService::class);
+                $variable->set('retcon', RetconVariable::class);
             }
         );
     }

src/variables/RetconVariable.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace mmikkel\retcon\variables;
+
+use Craft;
+
+use mmikkel\retcon\Retcon;
+use mmikkel\retcon\services\RetconService;
+
+use yii\base\UnknownMethodException;
+
+/**
+ * @deprecated 3.0.0 Using the craft.retcon variable is discouraged and Twig filters should be used instead
+ */
+class RetconVariable
+{
+    public function __call($name, $arguments)
+    {
+        $class = new \ReflectionClass(RetconService::class);
+        $methods = \array_reduce($class->getMethods(\ReflectionMethod::IS_PUBLIC), function ($carry, $method) {
+            if ($method->class === RetconService::class) {
+                $carry[] = $method->name;
+            }
+            return $carry;
+        }, []);
+        if (!in_array($name, $methods, true)) {
+            throw new UnknownMethodException('Unknown method: ' . $name);
+        }
+        $filterName = 'retcon' . ucfirst($name);
+        Craft::$app->getDeprecator()->log(__METHOD__ . '_' . $name, "The `craft.retcon.$name` variable is deprecated. Use the `|$filterName` Twig filter instead.");
+        return Retcon::getInstance()->retcon->$name(...$arguments);
+    }
+}