rework serializers (#155)

  * `SerializerInterface` interface
    * BREAKING: renamed to `Serializer`
    * BREAKING: Method `serialize()` got a new optional parameter `$prettyPrint`
  * `BaseSerializer` abstract class
    * BREAKING: complete redesign
  * `{Json,Xml}Serializer` class
    * BREAKING: complete redesign

Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

.gitattributes

@@ -34,8 +34,9 @@ composer.lock text eol=lf diff=json
 /examples               export-ignore
 /docs/dev               export-ignore
 
-# files that are forced to be exported in "dist" releaes
-/phpdoc.dist.xml        -export-ignore
+# files that are forced to be exported in "dist" release
+/README.md              -export-ignore
 /NOTICE                 -export-ignore
 /LICENSE                -export-ignore
 /semver.txt             -export-ignore
+/phpdoc.dist.xml        -export-ignore

HISTORY.md

@@ -81,17 +81,20 @@ API changes
 * `\CycloneDX\Core\Serialize` namespace
   * Overall
     * BREAKING: renamed namespace to `Serialization` ([#5] via [#146])
-  * `BaseSerializer` class
-    * BREAKING: removed deprecated method `setSpec()` (via [#144])
-  * `BaseValidator` class
-    * BREAKING: removed deprecated method `setSpec()` (via [#144])
+  * `SerializerInterface` interface
+    * BREAKING: renamed to `Serializer` ([#133] via [#155])
+    * BREAKING: existing method `serialize()` got a new optional parameter `$prettyPrint` (via [#155])
+  * `BaseSerializer` abstract class
+    * BREAKING: complete redesign (via [#155])
+  * `{Json,Xml}Serializer` class
+    * BREAKING: complete redesign (via [#155])
   * `{DOM,JSON}\NormalizerFactory` classes
     * BREAKING: removed method `makeForLicenseExpression()` (via [#131])
     * BREAKING: removed method `makeForDisjunctiveLicense()` (via [#131])
     * BREAKING: removed method `makeForDisjunctiveLicenseRepository()` (via [#131])
     * BREAKING: removed method `makeForHashRepositonary()` - use `makeForHashDictionary()` instead ([#133] via [#131])
     * BREAKING: removed method `setSpec()` (via [#131])
-    * Added new method `makeForHashDictionary()` ([#133] via [#131])
+    * Added method `makeForHashDictionary()` ([#133] via [#131])
     * Added method `makeForLicense()` (via [#131])
     * Added method `makeForLicenseRepository()` (via [#131])
   * `{DOM,JSON}\Normalizers` namespaces
@@ -107,6 +110,8 @@ API changes
         This is considered a non-breaking change, because the behaviour was already documented in the API, even though there was no need for an implementation before.
     * `ExternalReferenceNormalizer` classes
       * Changed, so that it tries to convert unsupported types to "other", before it throws an `\DomainException` ([#137] via [#147])
+  * `JSON\Normalizers\BomNormalizer` class
+    * Changed: method `normalize`'s result data may contain the `$schema` string (via [#155])
   * `JSON\Normalizers\ExternalReferenceNormalizer` class
     * BREAKING: method `normalize` may throw `\UnexpectedValueException` when the url is invalid to format "ini-reference" (via [#151])
 * `\CycloneDX\Core\Spdx` namespace
@@ -115,16 +120,17 @@ API changes
   * BREAKING: completely reworked everything ([#139] via [#142])  
     See the code base for references
 * `\CycloneDX\Core\Validation` namespace
-  * `XmlValidator` classes
-    * Added support for CycloneDX v1.4 ([#57] via [#65])
-  * `JsonValidator` classes
+  * `BaseValidator` class
+    * BREAKING: removed deprecated method `setSpec()` (via [#144])
+  * `ValidatorInterface` interface
+    * BREAKING: renamed interface to `Validator` ([#133] via [#143])
+  * `Validators\{Json,Xml}Validator` classes
     * Added support for CycloneDX v1.4 ([#57] via [#65])
+  * `Validators\JsonValidator` classes
     * Utilizes a much more competent validation library than before ([#80] via [#151])
-  * `JsonStrictValidator` class
+  * `Validators\JsonStrictValidator` class
     * Added support for CycloneDX v1.4 ([#57] via [#65])
     * Utilizes a much more competent validation library than before ([#80] via [#151])
-  * `ValidatorInterface` interface
-    * BREAKING: renamed interface to `Validator` ([#133] via [#143])
 
 [#5]: https://github.com/CycloneDX/cyclonedx-php-library/issues/5
 [#6]: https://github.com/CycloneDX/cyclonedx-php-library/issues/6
@@ -148,6 +154,7 @@ API changes
 [#146]: https://github.com/CycloneDX/cyclonedx-php-library/pull/146
 [#149]: https://github.com/CycloneDX/cyclonedx-php-library/pull/149
 [#151]: https://github.com/CycloneDX/cyclonedx-php-library/pull/151
+[#155]: https://github.com/CycloneDX/cyclonedx-php-library/pull/155
 
 ## 1.6.3 - 2022-09-15
 

README.md

@@ -90,6 +90,12 @@ $bom->getComponents()->addItems(
 );
 ```
 
+## API documentation
+
+There is no pre-rendered documentation at the time.  
+Instead, there is a prepared config for [phpDoc3](https://docs.phpdoc.org/guide/getting-started/index.html)
+that you can use to generate the docs for yourself.
+
 ## Conflicts
 
 Due to the fact that this library was split out of [`/src/Core` of cyclonedx-php-composer (346e6200fb2f5086061b15c2ee44f540893ce97d)](https://github.com/CycloneDX/cyclonedx-php-composer/tree/346e6200fb2f5086061b15c2ee44f540893ce97d/src/Core)  

examples/build_and_serialize.php

@@ -26,19 +26,31 @@
 // Example how to serialize a Bom to JSON / XML.
 
 $bom = new \CycloneDX\Core\Models\Bom();
-$bom->getComponents()->addItems(
-    new \CycloneDX\Core\Models\Component(
-        \CycloneDX\Core\Enums\Classification::LIBRARY,
-        'myComponent'
+$bom->getMetadata()->setComponent(
+    $rootComponent = new \CycloneDX\Core\Models\Component(
+        \CycloneDX\Core\Enums\Classification::APPLICATION,
+        'myApp'
     )
 );
+$component = new \CycloneDX\Core\Models\Component(
+    \CycloneDX\Core\Enums\Classification::LIBRARY,
+    'myComponent'
+);
+$bom->getComponents()->addItems($component);
+$rootComponent->getDependencies()->addItems($component->getBomRef());
 
 $spec = \CycloneDX\Core\Spec\SpecFactory::make1dot4();
 
-$jsonSerializer = new \CycloneDX\Core\Serialization\JsonSerializer($spec);
-$serializedJSON = $jsonSerializer->serialize($bom);
+$prettyPrint = false;
+
+$jsonSerializer = new \CycloneDX\Core\Serialization\JsonSerializer(
+    new \CycloneDX\Core\Serialization\JSON\NormalizerFactory($spec)
+);
+$serializedJSON = $jsonSerializer->serialize($bom, $prettyPrint);
 echo $serializedJSON, \PHP_EOL;
 
-$xmlSerializer = new \CycloneDX\Core\Serialization\XmlSerializer($spec);
-$serializedXML = $xmlSerializer->serialize($bom);
+$xmlSerializer = new \CycloneDX\Core\Serialization\XmlSerializer(
+    new \CycloneDX\Core\Serialization\DOM\NormalizerFactory($spec)
+);
+$serializedXML = $xmlSerializer->serialize($bom, $prettyPrint);
 echo $serializedXML, \PHP_EOL;

phpdoc.dist.xml

@@ -15,7 +15,10 @@
                 <path>src</path>
             </source>
             <default-package-name>CycloneDX Library</default-package-name>
-            <include-source>false</include-source>
+            <ignore-tags>
+                <ignore-tag>SuppressWarnings</ignore-tag>
+                <ignore-tag>psalm-suppress</ignore-tag>
+            </ignore-tags>
         </api>
     </version>
 </phpdocumentor>

src/Core/Serialization/BaseSerializer.php

@@ -25,70 +25,92 @@
 
 use CycloneDX\Core\Models\Bom;
 use CycloneDX\Core\Models\BomRef;
-use CycloneDX\Core\Spec\Spec;
+use Exception;
 
 /**
- * @author jkowalleck
+ * @template TNormalizedBom
  */
-abstract class BaseSerializer implements SerializerInterface
+abstract class BaseSerializer implements Serializer
 {
     /**
-     * @readonly
+     * Get a list of all {@see \CycloneDX\Core\Models\BomRef} in {@see \CycloneDX\Core\Models\Bom}.
+     * The list might contain duplicates.
+     *
+     * @return BomRef[]
+     *
+     * @psalm-return list<BomRef>
      */
-    private Spec $spec;
-
-    public function __construct(Spec $spec)
+    private function getAllBomRefs(Bom $bom): array
     {
-        $this->spec = $spec;
-    }
+        $allBomRefs = [];
+        $allComponents = $bom->getComponents()->getItems();
+        $metadataComponent = $bom->getMetadata()->getComponent();
+        if (null !== $metadataComponent) {
+            $allComponents[] = $metadataComponent;
+        }
+        foreach ($allComponents as $component) {
+            $allBomRefs[] = $component->getBomRef();
+            array_push($allBomRefs, ...$component->getDependencies()->getItems());
+        }
 
-    public function getSpec(): Spec
-    {
-        return $this->spec;
+        return $allBomRefs;
     }
 
     /**
-     * {@inheritdoc}
+     * Normalize for serialization.
+     *
+     * Also utilizes {@see \CycloneDX\Core\Serialization\BomRefDiscriminator}
+     * to guarantee that each BomRef has a unique value.
+     *
+     * @throws Exception
+     *
+     * @return TNormalizedBom a version of the Bom that was normalized for serialization
      */
-    public function serialize(Bom $bom): string
+    private function normalize(BOM $bom)
     {
         $bomRefDiscriminator = new BomRefDiscriminator(...$this->getAllBomRefs($bom));
         $bomRefDiscriminator->discriminate();
+        // This IS NOT the place to put meaning to the BomRef values. This would be out of scope.
+        // This IS the place to make BomRef values (temporary) unique in their own document scope.
         try {
-            return $this->normalize($bom);
+            return $this->realNormalize($bom);
         } finally {
             $bomRefDiscriminator->reset();
         }
     }
 
     /**
-     * Normalize the Bom to a string.
-     *
-     * May throw implementation-dependent Exceptions.
+     * {@inheritDoc}
      *
-     * @psalm-return non-empty-string
+     * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
      */
-    abstract protected function normalize(Bom $bom): string;
+    final public function serialize(Bom $bom, ?bool $prettyPrint = null): string
+    {
+        return $this->realSerialize(
+            $this->normalize($bom),
+            $prettyPrint
+        );
+    }
 
     /**
-     * @return BomRef[]
+     * Normalize a {@see \CycloneDX\Core\Models\Bom} to the data structure that {@see realSerialize()} can handle.
+     *
+     * @throws Exception
+     *
+     * @return TNormalizedBom a version of the Bom that was normalized for serialization
      */
-    private function getAllBomRefs(Bom $bom): array
-    {
-        $allBomRefs = [];
-
-        $allComponents = $bom->getComponents()->getItems();
-
-        $metadataComponent = $bom->getMetadata()->getComponent();
-        if (null !== $metadataComponent) {
-            $allComponents[] = $metadataComponent;
-        }
+    abstract protected function realNormalize(Bom $bom);
+    // no typehint for return type, as it is not actually `mixed` but a templated type.
 
-        foreach ($allComponents as $component) {
-            $allBomRefs[] = $component->getBomRef();
-            array_push($allBomRefs, ...$component->getDependencies()->getItems());
-        }
-
-        return $allBomRefs;
-    }
+    /**
+     * Serialize a {@see realNormalize() normalized} version of a {@see \CycloneDX\Core\Models\Bom}.
+     *
+     * @param TNormalizedBom $normalizedBom a version of the Bom that was normalized for serialization
+     *
+     * @throws Exception
+     *
+     * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
+     */
+    abstract protected function realSerialize($normalizedBom, ?bool $prettyPrint): string;
+    // no typehint for `$normalizedBom` parameter, as it is not actually `mixed` but a templated type.
 }

src/Core/Serialization/JSON/Normalizers/BomNormalizer.php

@@ -27,6 +27,7 @@
 use CycloneDX\Core\Models\Bom;
 use CycloneDX\Core\Models\Metadata;
 use CycloneDX\Core\Serialization\JSON\_BaseNormalizer;
+use CycloneDX\Core\Spec\Version;
 
 /**
  * @author jkowalleck
@@ -37,12 +38,20 @@ class BomNormalizer extends _BaseNormalizer
 
     private const BOM_FORMAT = 'CycloneDX';
 
+    private const SCHEMA = [
+        Version::v1dot1 => null,
+        Version::v1dot2 => 'http://cyclonedx.org/schema/bom-1.2b.schema.json',
+        Version::v1dot3 => 'http://cyclonedx.org/schema/bom-1.3a.schema.json',
+        Version::v1dot4 => 'http://cyclonedx.org/schema/bom-1.4.schema.json',
+    ];
+
     public function normalize(Bom $bom): array
     {
         $factory = $this->getNormalizerFactory();
 
         return array_filter(
             [
+                '$schema' => self::SCHEMA[$factory->getSpec()->getVersion()] ?? null,
                 'bomFormat' => self::BOM_FORMAT,
                 'specVersion' => $factory->getSpec()->getVersion(),
                 'version' => $bom->getVersion(),