have a list which XML/JSON properties are supported in the data model and in the serializers.

a list ala

| bom | Cyclonedx\Core\Models\Code |
| bom.component | Cyclonedx\Core\Models\Component |

etc ...

see https://cyclonedx.org/use-cases/#external-references

caused by CycloneDX/cyclonedx-php-composer#129

Json normalizers returns object of stdClass instead of associative arrays

• therefore revisit the serializes in general and simplify them !

benefit:

• distinguish key-value stores from lists: lists/sets are arrays, key/value-stores are objects
• this will help typing a lot !

the concept of the constructors must be to accept only the mandatory properties of the object.
nothing more.

some model constructors accept unnecessary parameters.
This is to be changed.

related to CycloneDX/cyclonedx-php-composer#87

• tag a version
• release a version
• add in the CDX tool center -- via CycloneDX/cyclonedx.org#55

describe how models, enums, serializer and all work together.

since support for php7.3 is dropped,
we can use WeakRefs for the normalizer factory, so it does not need to create a new instance every time ...

current copyright holder is Steve Springett @stevespringett .

Even though i am the original author, I added this notice as it was the usual with the CycloneDX implementations back then.
Today, the @CycloneDX used to go with a copyright to OWASP.

Proposal: change copyright holder to "OWASP Foundation.".

function a (Foo ...$items ): void { /* ... */}
function b (): Generator { yield new Foo(); }

no longer needed:

a(...iterator_to_array(b()));

can do:

a(...b());

instead of throwing an exception if a type of an external reference was not supported, it might help to self-heal and try to use the type "other"
THis way, less information is lost, wen normalizing to a spec that does not support all external-reference-types

make the component's version an optional propperty. as of SPEC 1.4 the bom.component.version can be omitted entirely.

when rendering/normalizing to XML/JSON: the empty version identifier is to be set as an empty string.

see CycloneDX/specification#90
see https://github.com/CycloneDX/specification/blob/ccbf7b5781ef534cd62616e3c4221004c7c82a66/schema/bom-1.4.schema.json#L266-L269
see https://github.com/CycloneDX/specification/blob/ccbf7b5781ef534cd62616e3c4221004c7c82a66/schema/bom-1.4.xsd#L281-L286

a config for the phpdoc exists in a working state: phpdoc.dist.xml

when running phpdoc3
the docs are created as expected.

GOAL

• have docs generated and published somewhere.

possible solution:

generating

• phpdoc
• doxygen
• DocFX
• any other option ?

hosting

• host at https://readthedocs.org/
  • read: https://mike42.me/blog/2018-06-how-to-create-effective-php-project-documentation-with-read-the-docs
• have a docu branch that might hold docs and have them published via github pages.
  ala https://github.com/CycloneDX/cyclonedx-python-lib/pull/10/files
• any other option ?

related : https://github.com/CycloneDX/cyclonedx-python-lib/pull/10/files

• keep test coverage at ~100% << it lowered during new implementations in prep for this release
• remove the v2 dev hint from README
• ... TO BE CONTINUED ...
• finish all in https://github.com/CycloneDX/cyclonedx-php-library/milestone/1
• follow https://github.com/CycloneDX/cyclonedx-php-library/blob/master/docs/dev/processes/major_version_switch.md

A core feature of CycloneDX are annotations in the form of properties.
These are free key-value stores, that exist on certain data structures:

• component
• metadata
• bom (XML only - see CycloneDX/specification#130)

Goal:

• have these new structures implemented and made available on the following existing data modes
  • component - #165
  • metadata - #165
  • bom - #229
• have XML and JSON normalizer render these new structures
  • component - #165
  • metadata - #165
  • bom - #229
    ❗ Attention: must not render in JSON results - see CycloneDX/specification#130
• have tests for new data structures - 100% coverage -- #232

-[x] rename namespace CycloneDX\Core\Serialize to CycloneDX\Core\Serialization
-[x] rename namespace CycloneDX\Core\Validate to CycloneDX\Core\Validation

there are some baselines ...
they need to be addressed. -> fixed or supressed

furthermore:

• address baseline
• remove baseline
• move config to /.phpmd.xml
• finaly: folder .phpmd was removed`

the projects goal is to provide psalm hints,
and it scans itself during CI rnus.

lets report to shepherd.

we could then put a badge for it in the readme.

• fix all TODO
• fix all DEMPRECATED

to improve typing, all list-like elements become lists. always.
all map-like become maps. always.
no null values anymore.

motivation: simply call myStructure->get<ListLike>()->append() - no check needed, whether the get<ListLike>() returned null or something ...

this is considered a breaking change, as return types might change.

for renaming, see #66

• have a tool that finds code duplications
• reduce code duplications (in serializers) by using traits or method inheritances

the decision paper has a section about switching to a better json schema validator, when possible.

this time has come: the schema files were fixed, php7.3 is no longer supported.
let's switched to opis/json-schema for JSON validation

acc / crit:

• opis/json-schema is used for JSON validation in productive code
• opis/json-schema is used for JSON validation in tests
• other json schema validator dependencies were removed
• updated decision paper describing the terms of the current schema validator, and hint to older version of the document.

❗ currently blocked by CycloneDX/specification#138

current normalizers create elements with hardcoded tagNames.
The tag names are better to be injectable, so the normalizers are reusable.

background: in XML the definitions are applied by inheritance.
Therefore, the point where a definition is applied may decide what the tagName is.

please add support for component.author according to

• JSON: https://cyclonedx.org/docs/1.4/json/#components_items_author
• XML: https://cyclonedx.org/docs/1.2/xml/#type_component

attention: author is not available in CycloneDX v1.1 or before

caused by CycloneDX/cyclonedx-php-composer#261

this thing is no assertion, it does not throw.
its a predicate for filters.

ISSUE: current implementation treats xsd:anyURI as an URL.

xsd:anyURI is more than a URL
documentation: http://www.w3.org/TR/xmlschema-2/#anyURI
see also http://books.xmlschemata.org/relaxng/ch19-77009.html
see also http://www.datypic.com/sc/xsd/t-xsd_anyURI.html

current implementation is done wrong - as followed:

filter_var($url, \FILTER_VALIDATE_URL)

to implement license evidences downstream it is required to have the needed models. see #238

Additionally, it is needed to have an option to store/serialize license texts.

• extend/addg models & add tests
• JSON normalizer & tests
• XML normalizer & tests

on 2022-11-28 the support for php7.4 will end. see https://www.php.net/supported-versions.php

lets take this for a change to switch the min-version of this lib to 8.0 .
see https://www.php.net/manual/en/migration80.new-features.php

so to use the new language features, a breaking change will happen:

• all of #6
• drop php7.4 from CI
• drop php7.4 from composer manifest (php: ^8.0)
• migrate to php80 via php-cs-fixer
• remove public use of AbstractDisjunctiveLicense and use correct union type instead. the class is already marked as internal.
• use union types where needed - so EVERYTHING is properly typed, finally

GOAL:

• improve SPDX license expression detection -- incorporate https://packagist.org/packages/composer/spdx-licenses
• have the license model just take what they are given - no validation inside
• factory may validate/check and generate the correct data types: preferred order: SpdxID, Expression, NamedLicense as fallback.
• normalizers need to check for valid SPDX license id, as the model does no longer assert this.

requires CycloneDX/specification#106

the current JSON result follows an existing schema, described in https://github.com/CycloneDX/specification/tree/master/schema

feature request: add the used schema as a property $schema of the resulting json.
the value must be the $id of the schema used.

example:

{
  "$schema": "http://cyclonedx.org/schema/bom-1.3.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.3",
  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "version": 1,
  "components": [
    {
      "type": "library",
      "name": "acme-library",
      "version": "1.0.0"
    }
  ]
}

acc / critt

• have php 8.1 tested in the CI/CT

the enum classes became native enums via #140

This means we dont have consts, but cases.
Constants were written in uppercase in the past, which originates to times when here when no IDEs, so people would easily know these were constants not properties ....

this is outdated foo.

Let's rename the cases and user UpperCamelCase for naming conventions.
And while on it, sort them alphabetically.

CycloneDX changed since spec V1.3
it is not only a bill of materials, but is a document format for several purposes. See https://cyclonedx.org/capabilities/

Proposal: rename Models\BOM to something else.
name ideas:

• Models\CycloneData
• Models\CycloneDocument
• Models\Document

• XML schema: https://github.com/CycloneDX/specification/blob/master/schema/ext/vulnerability-1.0.xsd
• docs: https://cyclonedx.org/ext/vulnerability/
• example: https://cyclonedx.org/use-cases/#vulnerability-disclosure

✋ issue: there is no JSON port for this extension - see CycloneDX/specification#37
🚧 unless we have a valid json schema for it, it is impossible to properly implement for all SBoM results

caused-by: CycloneDX/cyclonedx-php-composer#142

rename some classes so they match the already common names (that are also mentioned in the README alreeady)

• DisjunctiveLicenseWithName -> NamedLicense
• DisjunctiveLicenseWithId -> SpdxLicense

rename makeDisjunctiveWithName ??
rename makeDisjunctiveWithId ??

currently every spec is an own class. ala class Spec14 implements Spec { }

proposal: have Spec be a class, and have a factory that creates implmentations for 1.4, 1.3, ...
this factory could use waek references, so t can cache already generated instances, without taking up to much memory.

currently readonly properties are private, annotated as @readonly and available via a getter.

since php8.1 native support for readonly properties exists.

proposal

• remove the getter
• make the property public
• make the property readonly - via #208

attention

• there are issues when it comes to modifications in __clone() - -therefore, not fully rolled out
• there are extended works needed to make the test cases aware ...
• failed try: #207

caused by CycloneDX/cyclonedx-php-composer#158

have all the XML strings that are anyURI somehow fixed before rendering the XML.
affected elements:

• component.purl
• license.url
• externalReterence.url
• and so on ...

according to XML spec the anyURI needs to conform to https://www.ietf.org/rfc/rfc2396.txt

 * @see http://www.w3.org/TR/xmlschema-2/#anyURI
 * @see http://www.datypic.com/sc/xsd/t-xsd_anyURI.html


    /* URIs require that some characters be escaped with their hexadecimal Unicode code point preceded by the %
     * character. This includes non-ASCII characters and some ASCII characters, namely control characters, spaces,
     * and the following characters (unless they are used as deliimiters in the URI): <>#%{}|\^`.
     * [...]
     * The only values that are not accepted are ones that make inappropriate use of reserved characters, such as ones that contain multiple # characters or have % characters that are not followed by two hexadecimal digits.
     * -- as of http://www.datypic.com/sc/xsd/t-xsd_anyURI.html
     */

the method LicenseFactory::makeDisjunctiveFromExpression() was poorly implemented, and therefore should be removed.

CycloneDX spec 1.4 was released.
lets download the schema files and make them available in this project.

• have phpmd running with baseline - via #30
• fix the mess
• remove the baseline

due to proper typing we coul open the visibility of a lot of properties -> make them public.

see also: #128

on 2021-12-06 the support for php7.3 ended. see https://www.php.net/supported-versions.php

lets take this for a change to switch the min-version of this lib to 7.4 .
see https://www.php.net/manual/en/migration74.new-features.php

so to use the new language features, a breaking change will happen:

• drop php7.3 from CI
• drop php7.3 from composer manifest (php: ^7.4)
• migrate to php74 via php-cs-fixer
• make class properties type-save
• bump ergebnis/composer-normalize to a later version that does not need php7.3 - #46
• review the proposals below

PROPOSAL: remove getters and setters, if a property can be made type safe and converted to public.

PRO

• less methods to maintain

CON

• no setters = cannot use chained setters ala $instance->setA(1)->setB(2);

code changes

from

class C {
  /** @var bool */
  private $prop = true;

  /** @return $this */
  public function setProp(bool $prop): self
  {
     $this->prop = $prop;
     return $this;
  }
}

to

class C {
  public bool $prop = true;
}

introduce mutation tests / test mutations

products:

• https://infection.github.io/
• ... to be continued

acc / crit

• have mutation testing avialable -- via #129
• have mutation testing as part of CI/CT in github pipeline
• have mutation testing as part of CI/CT in composer test suite
• have mutation testing passing (no escapes and so on )

some namespaces and structures can be renamed
as the actual usage showed that they are either wrong, or impractical or to long,or there are just other options with more actual meaning

see also: #5

namespaces

• Repositories -> Collections as it contains maps, dictionaries and repositories

classes/interfaces

• MetaData -> Metadata
• HashRepository -> HashDictionary
• ValidatorInterface -> Validator
• Spdx\License -> Spdx\LicenseValidator
• SerializerInterface -> Serializer

methods

• {get,set}ComponentRepository() -> {get,set}Components()
• {get,set}ExternalReferenceRepository() -> {get,set}ExternalReferences()
• {get,set}HashRepository() -> {get,set}Hashes()
• {get,set}DependenciesBomRefRepository() -> {get,set}Dependencies()
• {get,set}MetaData() -> {get,set}Metadata()
• all commection's methods should be streamlined to {add/get}Items instead of diffferent add<SomeItemType>

overall

• every ocurrence of [mM]etaData with a capital "D' -> [mM]etadata (small "d")

current serializers generate the normalizers on their own.
but the normalizers should be injectable, so others can modify the normliazed output, before normalizing

current implementation uses abstract classes for enums.

since version 8.1 PHP finally has native enum support. see https://www.php.net/manual/en/language.types.enumerations.php

proposal: change all enum-likes to actual enums

CycloneDX spec v1.5 is in the making.
When it is final, it should be supported by the next upcoming major version of this library.

Implementations will require to interfaces and base implementation API, which results in breaking changes.

nobody cares for the authors, as long as the commiter gave consent to the current cproject's license agreement.

so remove all the @author remarks

to implement license evidences downstream it is required to have the needed models.

see https://cyclonedx.org/docs/1.3/json/#components_items_evidence
see https://cyclonedx.org/docs/1.3/xml/#type_componentEvidenceType

✍️ name shall be ComponentEvidence

• models & tests
• JSON normalizer & tests
• XML normalizer & tests

✔️ while at it, maybe also add component.copyright if it was missing.