[TASK] Deprecate __toString()

Part of #998

Author: oliverklee

CHANGELOG.md

@@ -32,6 +32,7 @@ Please also have a look at our
 
 ### Deprecated
 
+- Deprecate `__toString()` (#1006)
 - `OutputFormat` properties for space around list separators as an array (#880)
 
 ### Removed

src/CSSList/AtRuleBlockList.php

@@ -42,6 +42,9 @@ public function atRuleArgs(): string
         return $this->arguments;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/CSSList/CSSList.php

@@ -402,6 +402,9 @@ public function removeDeclarationBlockBySelector($selectors, $removeAll = false)
         }
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/CSSList/KeyFrame.php

@@ -51,6 +51,9 @@ public function getAnimationName()
         return $this->animationName;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Comment/Comment.php

@@ -50,6 +50,9 @@ public function setComment(string $commentText): void
         $this->commentText = $commentText;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/OutputFormatter.php

@@ -159,7 +159,7 @@ public function safely(callable $callable): ?string
     }
 
     /**
-     * Clone of the `implode` function, but calls `render` with the current output format instead of `__toString()`.
+     * Clone of the `implode` function, but calls `render` with the current output format.
      *
      * @param array<array-key, Renderable|string> $values
      */

src/Property/CSSNamespace.php

@@ -54,6 +54,9 @@ public function getLineNo(): int
         return $this->lineNumber;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Property/Charset.php

@@ -71,6 +71,9 @@ public function getCharset()
         return $this->charset->getString();
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Property/Import.php

@@ -72,6 +72,9 @@ public function getLocation()
         return $this->location;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Property/Selector.php

@@ -113,6 +113,9 @@ public function setSelector($selector): void
         $this->specificity = null;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->getSelector();

src/Renderable.php

@@ -6,6 +6,9 @@
 
 interface Renderable
 {
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string;
 
     public function render(OutputFormat $outputFormat): string;

src/Rule/Rule.php

@@ -260,6 +260,9 @@ public function getIsImportant()
         return $this->isImportant;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/RuleSet/AtRuleSet.php

@@ -53,6 +53,9 @@ public function atRuleArgs()
         return $this->arguments;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/RuleSet/DeclarationBlock.php

@@ -142,6 +142,8 @@ public function getSelectors()
 
     /**
      * @throws OutputException
+     *
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
      */
     public function __toString(): string
     {

src/RuleSet/RuleSet.php

@@ -255,6 +255,9 @@ public function removeRule($mRule): void
         }
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/CSSFunction.php

@@ -105,6 +105,9 @@ public function getArguments()
         return $this->aComponents;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/CSSString.php

@@ -90,6 +90,9 @@ public function getString()
         return $this->string;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/Color.php

@@ -224,6 +224,9 @@ public function getColorDescription()
         return $this->getName();
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/LineName.php

@@ -49,6 +49,9 @@ public static function parse(ParserState $parserState): LineName
         return new LineName($aNames, $parserState->currentLine());
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/Size.php

@@ -210,6 +210,9 @@ public function isRelative(): bool
         return false;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/URL.php

@@ -76,6 +76,9 @@ public function getURL()
         return $this->oURL;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

src/Value/ValueList.php

@@ -83,6 +83,9 @@ public function setListSeparator($sSeparator): void
         $this->sSeparator = $sSeparator;
     }
 
+    /**
+     * @deprecated in V8.8.0, will be removed in V9.0.0. Use `render` instead.
+     */
     public function __toString(): string
     {
         return $this->render(new OutputFormat());

tests/Functional/Comment/CommentTest.php

@@ -13,19 +13,6 @@
  */
 final class CommentTest extends TestCase
 {
-    /**
-     * @test
-     */
-    public function toStringRendersCommentEnclosedInCommentDelimiters(): void
-    {
-        $comment = 'There is no spoon.';
-        $subject = new Comment();
-
-        $subject->setComment($comment);
-
-        self::assertSame('/*' . $comment . '*/', (string) $subject);
-    }
-
     /**
      * @test
      */

tests/FunctionalDeprecated/.gitkeep

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\FunctionalDeprecated\Comment;
+
+use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\Comment\Comment;
+
+/**
+ * @covers \Sabberworm\CSS\Comment\Comment
+ */
+final class CommentTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function toStringRendersCommentEnclosedInCommentDelimiters(): void
+    {
+        $comment = 'There is no spoon.';
+        $subject = new Comment();
+
+        $subject->setComment($comment);
+
+        self::assertSame('/*' . $comment . '*/', (string) $subject);
+    }
+}