Merge pull request #19 from 8fold/elemental

BC: Remove Buildable contract and implementation

Author: joshbruce

.github/workflows/php82.yml

@@ -0,0 +1,34 @@
+name: PHP 8.2
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup PHP Action
+        uses: shivammathur/[email protected]
+        with:
+          php-version: '8.2'
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Run style check
+        run: composer run style
+
+      - name: Run static analyzer
+        run: composer run stan
+
+      - name: Run tests
+        run: composer run test

README.md

@@ -1,15 +1,14 @@
 # 8fold XML Builder for PHP
 
 XML Builder is designed to build a `string`, not a document object model (DOM)
-or abstract syntax tree (AST). If you are looking to achieve either a DOM or AST,
-there are other libraries and native implementations to do so
-([PHP:DOM](https://www.php.net/manual/en/simplexml.examples-basic.php) and
-[SimpleXML](https://www.php.net/manual/en/simplexml.examples-basic.php), for example).
+or abstract syntax tree (AST).
+
+For DOM or AST, there are other libraries and native implementations (ex. [PHP:DOM](https://www.php.net/manual/en/book.dom.php) and [SimpleXML](https://www.php.net/manual/en/simplexml.examples-basic.php)).
 
 You might use XML Builder to generate a string you feed into either PHP:DOM or
 Simple XML. Or, use the string as the body of an HTTP response.
 
-Use the `Element` class to create individual nodes within the document itself.
+Use the `Element` class to create individual nodes within the document.
 
 Use the `Document` class to generate the doctype declaration and root level element.
 
@@ -52,10 +51,9 @@ Output (formatted):
 </root>
 ```
 
-Alternatively, there is a shorthand variation that can also be used.
+Alternatively, there is a shorthand variation.
 
-The shorthand method uses the `__callStatic` PHP magic method to use the method
-name called as the document and element name, respectively.
+The shorthand method uses the `__callStatic` PHP magic method.
 
 ```php
 use Eightfold\XMLBuilder\Document;
@@ -72,7 +70,7 @@ Document::root(
 // output: Same as previous example.
 ```
 
-Both the `Document` and `Element` classes can be converted directly to a `string` using the `__toString()` magic method.
+Both the `Document` and `Element` classes can be converted directly to a `string` using the `__toString()` PHP magic method.
 
 ```php
 use Eightfold\XMLBuilder\Document;
@@ -89,7 +87,7 @@ echo Document::root(
 // output: Same as previous example.
 ```
 
-Comments are also available:
+Comments are available:
 
 ```php
 use Eightfold\XMLBuilder\Document;
@@ -121,16 +119,11 @@ Output (unformatted):
 
 ## Details
 
-This library primarily came about from an experiment in which PHP was viewed
-without the additional capability of being a template engine. No need to parse a
-string to generate a complete string and future response.
+The origins of this library was an experiment where PHP was viewed as a "pure" programming language, not a template engine that grew into being a language.
 
-The secondary pain point was to keep the feel of writing human-friendly XML
-(tabs and spaces) while reducing the potential for human error; specifically,
-mismatched beginning and ending tags.
+The primary pain point was to maintain the feel of writing human-readable XML (tabs and spaces) while reducing the risk of human error; specifically, mismatched beginning and end tags.
 
-Finally, working with PHP:DOM and SimpleXML felt cumbersome when generating HTML
-and XML documents.
+The secondary pain point was that PHP:DOM and SimpleXML felt cumbersome when generating XML and HTML documents.
 
 ## Other
 

src/Cdata.php

@@ -4,14 +4,10 @@
 
 namespace Eightfold\XMLBuilder;
 
-use Eightfold\XMLBuilder\Contracts\Buildable;
+use Stringable;
 
-use Eightfold\XMLBuilder\Implementations\Buildable as BuildableImp;
-
-class Cdata implements Buildable
+class Cdata implements Stringable
 {
-    use BuildableImp;
-
     public static function create(string $content): static
     {
         return new static($content);

src/Comment.php

@@ -4,14 +4,10 @@
 
 namespace Eightfold\XMLBuilder;
 
-use Eightfold\XMLBuilder\Contracts\Buildable;
+use Stringable;
 
-use Eightfold\XMLBuilder\Implementations\Buildable as BuildableImp;
-
-class Comment implements Buildable
+class Comment implements Stringable
 {
-    use BuildableImp;
-
     public static function create(string $content): static
     {
         return new static($content);

src/Concatenate.php

@@ -3,17 +3,14 @@
 
 namespace Eightfold\XMLBuilder;
 
-use Eightfold\XMLBuilder\Contracts\Buildable;
-use Eightfold\XMLBuilder\Contracts\ContentWithoutElement;
-
 use Stringable;
 
-use Eightfold\XMLBuilder\Implementations\Buildable as BuildableImp;
+use Eightfold\XMLBuilder\Contracts\ContentWithoutElement;
+
 use Eightfold\XMLBuilder\Implementations\ContentWithoutElement as ContentWithoutElementImp;
 
-class Concatenate implements Buildable, ContentWithoutElement
+class Concatenate implements Stringable, ContentWithoutElement
 {
-    use BuildableImp;
     use ContentWithoutElementImp;
 
     public function __toString(): string

src/Contracts/Buildable.php

@@ -4,23 +4,20 @@
 
 namespace Eightfold\XMLBuilder;
 
-use Eightfold\XMLBuilder\Contracts\Buildable;
-use Eightfold\XMLBuilder\Contracts\Contentable;
-
 use Stringable;
 
+use Eightfold\XMLBuilder\Contracts\Contentable;
+
 use Eightfold\XMLBuilder\Concatenate;
 
 use Eightfold\XMLBuilder\Callables\PropertyArrayToString;
 
 use Eightfold\XMLBuilder\Implementations\Properties as PropertiesImp;
-use Eightfold\XMLBuilder\Implementations\Buildable as BuildableImp;
 use Eightfold\XMLBuilder\Implementations\Contentable as ContentableImp;
 
-class Document implements Buildable, Contentable
+class Document implements Stringable, Contentable
 {
     use PropertiesImp;
-    use BuildableImp;
     use ContentableImp;
 
     private string $version = '1.0';
@@ -38,28 +35,12 @@ public function withVersion(string|float|int $version): self
         return $this;
     }
 
-    /**
-     * @deprecated 1.4 Use `withVersion` instead.
-     */
-    public function setVersion(string|float|int $version): self
-    {
-        return $this->withVersion($version);
-    }
-
     public function withEncoding(string $encoding): self
     {
         $this->encoding = $encoding;
         return $this;
     }
 
-    /**
-     * @deprecated 1.4 Use `withEncoding` instead.
-     */
-    public function setEncoding(string $encoding): self
-    {
-        return $this->withEncoding($encoding);
-    }
-
     public function removeEncoding(): self
     {
         $this->encoding = '';
@@ -72,14 +53,6 @@ public function withStandalone(bool $standalone): self
         return $this;
     }
 
-    /**
-     * @deprecated 1.4 Use `withStandalone` instead.
-     */
-    public function setStandalone(bool $standalone = true): self
-    {
-        return $this->withStandalone($standalone);
-    }
-
     public function removeStandalone(): self
     {
         $this->standalone = '';

src/Document.php

@@ -4,21 +4,18 @@
 
 namespace Eightfold\XMLBuilder;
 
-use Eightfold\XMLBuilder\Contracts\Buildable;
-use Eightfold\XMLBuilder\Contracts\Contentable;
-
 use Stringable;
 
+use Eightfold\XMLBuilder\Contracts\Contentable;
+
 use Eightfold\XMLBuilder\Concatenate;
 
 use Eightfold\XMLBuilder\Implementations\Properties as PropertiesImp;
-use Eightfold\XMLBuilder\Implementations\Buildable as BuildableImp;
 use Eightfold\XMLBuilder\Implementations\Contentable as ContentableImp;
 
-class Element implements Buildable, Contentable
+class Element implements Stringable, Contentable
 {
     use PropertiesImp;
-    use BuildableImp;
     use ContentableImp;
 
     private bool $omitEndTag = false;

src/Element.php

@@ -10,33 +10,14 @@
 
 class CdataBaselineTest extends TestCase
 {
-    /**
-     *@test
-     */
-    public function cdata_is_stringable(): void
-    {
-        $this->assertEquals(
-            (string) Cdata::create('content'),
-            '<![CDATA[content]]>'
-        );
-    }
-
     /**
      *@test
      */
     public function cdata_can_be_initialized_statically(): void
     {
-        $this->assertEquals(
-            Cdata::create('content')->build(),
-            '<![CDATA[content]]>'
+        $this->assertSame(
+            '<![CDATA[content]]>',
+            (string) Cdata::create('content')
         );
     }
-
-    /**
-     *@test
-     */
-    public function cdata_exists(): void
-    {
-        $this->assertTrue(class_exists(Cdata::class));
-    }
 }

src/Implementations/Buildable.php

@@ -10,33 +10,14 @@
 
 class CommentBaselineTest extends TestCase
 {
-    /**
-     *@test
-     */
-    public function comment_is_stringable(): void
-    {
-        $this->assertEquals(
-            (string) Comment::create('content'),
-            "\n" . '<!-- content -->' . "\n"
-        );
-    }
-
     /**
      *@test
      */
     public function comment_can_be_initialized_statically(): void
     {
-        $this->assertEquals(
-            Comment::create('content')->build(),
-            "\n" . '<!-- content -->' . "\n"
+        $this->assertSame(
+            "\n" . '<!-- content -->' . "\n",
+            (string) Comment::create('content')
         );
     }
-
-    /**
-     *@test
-     */
-    public function comment_exists(): void
-    {
-        $this->assertTrue(class_exists(Comment::class));
-    }
 }