deprecate ptln()

This method was used to ensure some basic readability in the created
HTML sources long before Firebug and later the builtin inspector tools
in browsers pretty printed the HTML for you. Today, this is no longer
needed.

This adds a custom rector rule to automatically change all occurances to
echo statements.

_test/rector.php

@@ -2,6 +2,7 @@
 
 declare(strict_types=1);
 
+use dokuwiki\test\rector\DokuWikiPtlnRector;
 use Rector\Caching\ValueObject\Storage\FileCacheStorage;
 use Rector\CodeQuality\Rector\Array_\CallableThisArrayToAnonymousFunctionRector;
 use Rector\CodeQuality\Rector\Concat\JoinStringConcatRector;
@@ -37,6 +38,9 @@ use Rector\Strict\Rector\Empty_\DisallowedEmptyRuleFixerRector;
 use Rector\TypeDeclaration\Rector\Property\TypedPropertyFromAssignsRector;
 
 return static function (RectorConfig $rectorConfig): void {
+    // FIXME we may want to autoload these later
+    require_once __DIR__ . '/rector/DokuWikiPtlnRector.php';
+
     $rectorConfig->paths([
         __DIR__ . '/../inc/',
         __DIR__ . '/../lib/',
@@ -185,4 +189,6 @@ return static function (RectorConfig $rectorConfig): void {
         'utf8_bad_replace' => 'dokuwiki\Utf8\Clean::replaceBadBytes',
         'utf8_correctIdx' => 'dokuwiki\Utf8\Clean::correctIdx',
     ]);
+
+    $rectorConfig->rule(DokuWikiPtlnRector::class);
 };

_test/rector/DokuWikiPtlnRector.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace dokuwiki\test\rector;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Stmt\Echo_;
+use PhpParser\Node\Stmt\Expression;
+use Rector\Core\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * Replace ptln() calls with echo
+ */
+class DokuWikiPtlnRector extends AbstractRector
+{
+
+    /** @inheritdoc */
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Replace ptln() calls with echo', [
+            new CodeSample(
+                <<<'CODE_SAMPLE'
+ptln('Hello World', 7);
+CODE_SAMPLE,
+                <<<'CODE_SAMPLE'
+echo 'Hello World';
+CODE_SAMPLE
+            ),
+        ]);
+    }
+
+    /** @inheritdoc */
+    public function getNodeTypes(): array
+    {
+        return [Expression::class];
+    }
+
+    /** @inheritdoc */
+    public function refactor(Node $node)
+    {
+        if (!$node->expr instanceof FuncCall) {
+            return null;
+        }
+
+        if (!$this->nodeNameResolver->isName($node->expr, 'ptln')) {
+            return null;
+        }
+
+        return new Echo_([
+            $node->expr->args[0]->value
+        ]);
+    }
+}

inc/common.php

@@ -81,21 +81,6 @@ function blank(&$in, $trim = false)
     return empty($in);
 }
 
-/**
- * print a newline terminated string
- *
- * You can give an indention as optional parameter
- *
- * @author Andreas Gohr <andi@splitbrain.org>
- *
- * @param string $string  line of text
- * @param int    $indent  number of spaces indention
- */
-function ptln($string, $indent = 0)
-{
-    echo str_repeat(' ', $indent)."$string\n";
-}
-
 /**
  * strips control characters (<32) from the given string
  *

inc/deprecated.php

@@ -722,3 +722,19 @@ class IXR_Value extends \IXR\DataType\Value
     }
 }
 
+/**
+ * print a newline terminated string
+ *
+ * You can give an indention as optional parameter
+ *
+ * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $string  line of text
+ * @param int    $indent  number of spaces indention
+ * @deprecated 2023-08-31 use echo instead
+ */
+function ptln($string, $indent = 0)
+{
+    DebugHelper::dbgDeprecatedFunction('echo');
+    echo str_repeat(' ', $indent) . "$string\n";
+}