cyclonedx / cyclonedx-php-composer

Create CycloneDX Software Bill of Materials (SBOM) from PHP Composer projects

CycloneDX PHP Composer Plugin

---

A plugin for PHP's Composer that generates Software Bill of Materials (SBOM) in CycloneDX format.

Based on OWASP Software Component Verification Standard for Software Bill of Materials's criteria, this tool is capable of producing SBOM documents almost passing Level-2 (only signing needs to be done externally).

The resulting SBOM documents follow official specifications and standards, and might have properties following cdx:composer Namespace Taxonomy .

Requirements

• PHP ^8.1
• Composer ^2.3

However, there are older versions of this plugin available, which support PHP ^5.5||^7.0||^8.0 with Composer ^1.0||^2.0 .

Installation

As a global Composer plugin:

composer global require cyclonedx/cyclonedx-php-composer

As a development dependency of the current project:

composer require --dev cyclonedx/cyclonedx-php-composer

Usage

After successful installation, the Composer command CycloneDX:make-sbom is available.

$ composer CycloneDX:make-sbom --help

Description:
  Generate a CycloneDX Bill of Materials from a PHP Composer project.

Usage:
  CycloneDX:make-sbom [options] [--] [<composer-file>]

Arguments:
  composer-file                                       Path to Composer config file.
                                                      [default: "composer.json" file in current working directory]

Options:
      --output-format=OUTPUT-FORMAT                   Which output format to use.
                                                      {choices: "JSON", "XML"}
                                                      [default: "XML"]
      --output-file=OUTPUT-FILE                       Path to the output file.
                                                      Set to "-" to write to STDOUT
                                                      [default: "-"]
      --omit=OMIT                                     Omit dependency types.
                                                      {choices: "dev", "plugin"}
                                                      (multiple values allowed)
      --spec-version=SPEC-VERSION                     Which version of CycloneDX spec to use.
                                                      {choices: "1.1", "1.2", "1.3", "1.4", "1.5", "1.6"}
                                                      [default: "1.5"]
      --output-reproducible|--no-output-reproducible  Whether to go the extra mile and make the output reproducible.
                                                      This might result in loss of time- and random-based-values.
      --validate|--no-validate                        Formal validate the resulting BOM.
      --mc-version=MC-VERSION                         Version of the main component.
                                                      This will override auto-detection.
  -h, --help                                          Display help for the given command.
  -q, --quiet                                         Do not output any message
  -v|vv|vvv, --verbose                                Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Demo

For a demo of cyclonedx-php-composer see the demo projects.

How it works

This tool utilizes composer itself, to collect evidence for installed composer packages.
In terms of evidence collection, actually installed setups are preferred over pure lock file analysis.
Required evidence:

• composer config/manifest file (e.g. composer.json file)
• any of:
  • an actual composer setup (the result after running composer install [...] on your project)
  • a working composer lock file (e.g. composer.lock file)

Internals

This tool utilizes the CycloneDX PHP library to generate the actual data structures, normalize/serializ them and validate the SBOM result.

This tool does not expose any additional public API or classes - all code is marked as @internal and might change without any notice during version upgrades.

Contributing

Feel free to open issues, bugreports or pull requests.
See the CONTRIBUTING file for details.

License

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
See the LICENSE file for the full license.

cyclonedx-php-composer's Issues

Add package's CPE to BOM

Is your feature request related to a problem? Please describe.

OWASP's Dependency track internal analyser uses only CPE (not PURL) to match components with NVD vulnerabilities.
The current version of this package does not seem to include CPE in the generated BOM file
When uploaded to dependency track, the default analyser fails to match any php dependency to known vulnerabilities.

Describe the solution you'd like

In the generated bom in cyclonedx format, include the CPE of all packages

Describe alternatives you've considered

Dependency track can be configured to user other scanners, which can handle the provided packages PURLs
But it would be better to be able to benefit also from the https://nvd.nist.gov/vuln

Packagist is also integrating nist's NVDs, but having all the information centralised in the dependency track application would be great

Additional context

With the example of https://nvd.nist.gov/vuln/detail/CVE-2021-3603
the expected CPE is cpe:2.3:a:phpmailer_project:phpmailer:*:*:*:*:*:*:*:* ( |<=6.4.1 )

Looking at the composer.json file, there's no mention of phpmailer_project, neither on packagist's page
https://packagist.org/packages/phpmailer/phpmailer#v5.2.26
I don't know how it should be built with the available composer's data...?

DOCS: descibe the architecture

describe the architecture of the plugin
target audience: developers

validate the resulting file

👟 this feature is currently in progress.

idea:
validate resulting XML/JSON

how to do it:

• ship the supported schemata files in the res folder in a way they dont need any internet connection to download additional files - done via #90
• write a validator class
  • refactor existing schema validators in the integration-tests therefore
  • apply it in the integration tests, too
  • for XML
  • for JSON based on the strict schema
• add a CLI switch: --no-validate to diable validation, but have validation enabled per default
• add validator to the command
  • if validation enabled: validate the result based on shipped offline files (test with network disabled)
  • if validation failes: prompt an error message, show link to "create issue" and ask for the composer.lock file
• validation is done on the serialized string, before any file is written.
• validation is not part of the serialization itself, but an extra step.

Add support for dependency graph introduced in v1.2 of the spec

see https://cyclonedx.org/use-cases/#dependency-graph

support php8.1

php.81 will be available late2021

add support for it in

• composer.json
• CI chain - via #53

IDEA: refactor Model "License"

currently there is only License
refactor it to be multiples:

• LicenseWithId
• LicenseWithName
• LicenseExpression

benefit: have license models for v1.3 features enabled, have a proper factory(?) and proper typing

IDEA: cleaner code via php-cs-fixer

• all used global constanets come via use
• all used global methods come via use
• all used classes come via use

pin dev dependencies

• phpunit
• others, if possible
• dont use v previx in versions

Add composer itself to SBOM

this plugin utilizes composer.
even composer might have CVEs (see https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=composer+php)
therefore composer itself should be added as a component to SBOM somehow.

[LEGAL] change copyright holder to "OWASP Foundation"

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.".

remove composer v1 support

composer2 is the successor to composer1.
drop support for composer1

widen package deps if possible

requires #23

support/require `cyclonedx/cyclonedx-library:^2.0`

see https://github.com/CycloneDX/cyclonedx-php-library/milestone/1

best result: support v1 and v2
acceptable: no longer support v1

component's version is optional

depends on CycloneDX/cyclonedx-php-library#27

if the component's version is optional,
then the composer's default of RootPackage::DEFAULT_PRETTY_VERSION must be detected and set to null/empty-string

furthermore, the value of --mc-version CLI arg is allowed to be empty.

parameter/option to set `metadata.component.version`

status quo

if php/composer is unable to detect a version in the root component,
then it will use 1.0.0+no-version-set instead.

this version is taken to the SBoM without any modifcations.

how to reproduce

1. clone the current code
2. (re)move the .git dir
3. setup the demos/symfony/ project & generate the SBoMs
4. see metadata.component.version -> value will be 1.0.0+no-version-set

feature request

add an CLI option to override the metadata.component.version

some background

composer tries to detect the version based on the VCS (svn/hg/git/...)
if this is impossible, the version is set to \Composer\Package\RootPackage::DEFAULT_PRETTY_VERSION

acc / crit

• CLI param/flag/switch is called --mc-version,
  is optional(+non-empty if present),
  help text is "Version of the main component"
• if CLI param/flag/switch is empty/missing, the SBoM is unmodified - versions stay as set by composer
• CLI option sets the version of the main component (metadata.component.version)
• CLI option sets the version of the main component's PURL (metadata.component.purl)

v3: restructure CLI

current CLI has:

• default for output file (bom.xml/bom.json) - depending on presence of switch --json
• output file can be redirected with option --output-file
• switch to get JSON output - if not present, output is XML
• output spec (1.1 / 1.2 / ...) is not switchable - the one that is implemented is used

possible enhancements:

• output the result on STDOUT if argument of --output-file is set to -.
• instead of a switch --json it might be better to have an option for this, with a proper default to "XML".
  this would allow adding future output formats without breaking changes to the CLI.
  option could be called --output-format
  --> was done via #80
• add an option to choose the desired output spec (1.0 / 1.1 / 1.2 / ...) with a default to the latest implemented one.
  this allow the plugin to stay backward compatible to existing workflows but still implement the latest spec.
  option could be called --spec-version
• switch --exclude-dev becomes a VALUE_NEGATABLE - see https://symfony.com/blog/new-in-symfony-5-3-negatable-command-options
  so it will look like --dev-dependencies or --no-dev-dependencies(default)
  ⚠️ currently not possible in composer - this version of symfony is not bundled with composer
• switch --exclude-plugins becomes a VALUE_NEGATABLE - see https://symfony.com/blog/new-in-symfony-5-3-negatable-command-options
  so it will look like --plugin-dependencies or --no-plugin-dependencies(default)
  ⚠️ currently not possible in composer - this version of symfony is not bundled with composer
• update CLI help in the README
• per default dont be verbose - detect via $verbose = OutputInterface::VERBOSITY_VERBOSE === $output->getVerbosity();

revisit json implementation

via #16 a preview for json 1.2 was implemented
needs to revisit existing implementation and
review it based on https://github.com/CycloneDX/specification/blob/master/schema/bom-1.2.schema.json

support php 8.1

acc / critt

• have php 8.1 tested in the CI/CT

refactor the plugin to make integration-tests possible

currently the code of CycloneDX\Composer\Plugin is not integration-testable in a good way,
and needs some love.

since the whole code is marked as @internal a refactoring can be done without causing breaking changes.

core library: make bomRefs unique

upcomng core lib improvement to render dependency graphs via bomRefs need to make sure, that all bomRefs are actually unique.
currently the validator should check for this, but there is noting in place to assert this.

process ala

    public function serialize(Bom $bom): string
    {
        $this->uniqueBomRefs();
        try {
            return $this->normalize($bom);
        } finally {
            $this->restoreBomRefs();
        }
    }

Modify the generated package URL to match purl-spec

As per https://github.com/package-url/purl-spec a package URL is as follows:

scheme:type/namespace/name@version?qualifiers#subpath

This package generates URLs such as pkg://composer/... which don't follow the specification, the // part needs to be removed.

fix https://github.com/CycloneDX/cyclonedx-php-composer/runs/2426830069

caused by #60

add known vulnerabilities from packagist.org to the SBoM result

CDX sbom knows vulnerabilities via

• schema extension: vulnerability
  • 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 - see CycloneDX/specification#37
  • 🚧 unless we have a valid json schema for it, it is impossible to properly implement for all SBoM results
• PROPOSAL: spec 1.4 - CycloneDX/specification#91
• PROPOSAL: CycloneDX/specification#44

packagist.org - composer's primary source - has an API to list known vulnerabilities per package.
see the docs: https://packagist.org/apidoc#list-security-advisories
implementation detail: the API might have a special handling for leading v in versions - or a special format for version-constraints(which might be handle-able by composers internal version-constraint-library)

---

summary of feedback/ ideas:

• IDEA: implement a switch to enable/disable the feature - since some CI/admins don't like unnoticed web traffic to some API
• IDEA: fetch these API data and add relevant information to the resulting SBOM.
• IDEA: As the tool is often used during build processes it might be good to have an optional non-zero exit code if a vulnerability is found. Makes it easy to “break the build” if that's what people want. (thanks @coderpatros )

---

if fetching data from API fails, simply prompt an error on the increased "verbosity"-log-level and dont add any vulns to the SBom result

have a `.phar` released

Is your feature request related to a problem? Please describe.

on CI, i always need to have a php composer available in order to create an SBOM of a composer.lock

Describe the solution you'd like

have a bundled .phar added to every release, that includes composer & the CDX composer plugin

Additional context

acc / crit

• phar includes a version of php composer & CDX plugin
• phar bundles pinned versions of all dependencies
  • lock file in the repo
  • add SBOM to PHAR for to know what is in it
• building PHAR is automated part of very release
• CI tests to build PHAR and execute integration/demos on every CT run
• IDEA: https://github.com/humbug/php-scoper is part of build process

used installedRepo instead of lockedRepo, if possible

fetching a project's components from the lock file is fine.
but it would be better to fetch them from composer's internal "installed" repository.
this is a locked repo that holds info of the actual installed components, like a component is installed as dist or src .... etc ...

the installedRepo is to be preferred over the lockedRepo.

implementation details:

• see vendor/composer/installed.json - which is accessible via \Composer\Composer::getRepositoryManager()->getLocalRepository() as a \Composer\Repository\RepositoryInterface -
  usable just like the already used \Composer\Repository\LockArrayRepository
• maybe related: Composer\InstalledVersions::getInstalledPackages()

might be related to #129

Own references to `bom.metadata.tools.tool.externalReferences`

requires https://github.com/CycloneDX/cyclonedx-php-library/milestone/3

as of CDX spec 1.4 the following existts: bom.metadata.tools.tool.externalReferences
a list of external references.

acc / crit

• repo of the tool is added as an external reference

addictional / undecided :

• tool updater code fetches external references from the package.
  • code already exists for components - it can be re-used here - make it an re0usabe factory/builder ?

add `bom.metadata.tools[].tool.externalReferences`

add bom.metadata.tools[].tool.externalReferences

this requires CDX v1.4 - see https://github.com/CycloneDX/cyclonedx-php-library/milestones/3

add package infos as "externalReferences"

see https://cyclonedx.org/use-cases/#external-references
caused: CycloneDX/cyclonedx-php-library#7
requires: https://github.com/CycloneDX/cyclonedx-php-library/releases/tag/v1.1.0

fetch these (optional) information from composer packages:
according to the CDX externalReferenceType:

• vcs
  • see "VCS" below
• issue-tracker
  • "issues" in https://getcomposer.org/doc/04-schema.md#support
• website
  • https://getcomposer.org/doc/04-schema.md#homepage
• advisories
  • maybe use packagist's buildin? what about alternative/private package repos - like packgist.com
• bom -
• mailing-list -
• social -
• chat
  • "chat" in https://getcomposer.org/doc/04-schema.md#support
  • "irc" in https://getcomposer.org/doc/04-schema.md#support
• [documentation
  • "docs" in https://getcomposer.org/doc/04-schema.md#support
  • "docs" in https://getcomposer.org/doc/04-schema.md#support
• support
  • any of the not already used ones from in https://getcomposer.org/doc/04-schema.md#support
• distribution
  • see "dist " below
  • "source" in https://getcomposer.org/doc/04-schema.md#support
• license -
• build-meta -
• build-system -
• other
  • funding: https://getcomposer.org/doc/04-schema.md#funding

VCS / dist

this one might be tricky, since it MUST reflect which actual package source was used. (dist- or source-package)
use the installation-source of the installed-lock (see #122) .

on the other hand it might be possible to simply add both sources as they might be in a lockfile.

example:

{
  "packages": [
    {
        "name": "swaggest/json-diff",
        "version": "v3.8.3",
        "version_normalized": "3.8.3.0",
        "source": {
            "type": "git",
            "url": "https://github.com/swaggest/json-diff.git",
            "reference": "bb3e3b4e9d842bb2e48f31ea568d0459968d1d42"
        },
        "dist": {
            "type": "zip",
            "url": "https://api.github.com/repos/swaggest/json-diff/zipball/bb3e3b4e9d842bb2e48f31ea568d0459968d1d42",
            "reference": "bb3e3b4e9d842bb2e48f31ea568d0459968d1d42",
            "shasum": ""
        },
        "require": {
            "ext-json": "*"
        },
        "require-dev": {
            "phpunit/phpunit": "^4.8.23"
        },
        "time": "2021-09-25T22:09:03+00:00",
        "type": "library",
        "installation-source": "dist"
    }
  ]
}

ExternalReference.url XML validation error `xs:anyURI`

• the version you are using
  cyclonedx/cyclonedx-php-composer V3.9.0

• your operating system and version
  WSL2.0 Ubuntu 20.04 on Windows 10

• reproducible steps (1 2 3...) that cause the issue including any required files
  Execute "php composer.phar make-bom --exclude-dev --output-file=composer-bom.xml ./composer.json"

• what you expected, versus what happened
  The system generates an composer-bom.xml file, but instead the system gives an error. See error and reason below

• any relevant screenshots and other outputs
  Output:

Validate BOM with CycloneDX\Core\Validation\Validators\XmlValidator for 1.3
ValidationError:
ValidationError: Element '{http://cyclonedx.org/schema/bom/1.3}url': '**http://pear.php.net/bugs/search.php?cmd=display&package_name[]=PEAR_Exception**' is not a valid value of the atomic type 'xs:anyURI'.

the drush/drush requirements tree has pear/pear_exception as an requirement.
Inside the composer.json of this module there is an URL with [] (See support->issues in the content below)

the systems fails validating the output with the following message:

Validate BOM with CycloneDX\Core\Validation\Validators\XmlValidator for 1.3
ValidationError:
ValidationError: Element '{http://cyclonedx.org/schema/bom/1.3}url': 'http://pear.php.net/bugs/search.php?cmd=display&package_name[]=PEAR_Exception' is not a valid value of the atomic type 'xs:anyURI'.

Generating the same file with --no-validate generates the file correctly, which we merge with our NPM bom file and upload to dTrack

{
            "name": "pear/pear_exception",
            "version": "v1.0.1",
            "source": {
                "type": "git",
                "url": "https://github.com/pear/PEAR_Exception.git",
                "reference": "dbb42a5a0e45f3adcf99babfb2a1ba77b8ac36a7"
            },
            "dist": {
                "type": "zip",
                "url": "https://api.github.com/repos/pear/PEAR_Exception/zipball/dbb42a5a0e45f3adcf99babfb2a1ba77b8ac36a7",
                "reference": "dbb42a5a0e45f3adcf99babfb2a1ba77b8ac36a7",
                "shasum": ""
            },
            "require": {
                "php": ">=4.4.0"
            },
            "require-dev": {
                "phpunit/phpunit": "*"
            },
            "type": "class",
            "extra": {
                "branch-alias": {
                    "dev-master": "1.0.x-dev"
                }
            },
            "autoload": {
                "classmap": [
                    "PEAR/"
                ]
            },
            "notification-url": "https://packagist.org/downloads/",
            "include-path": [
                "."
            ],
            "license": [
                "BSD-2-Clause"
            ],
            "authors": [
                {
                    "name": "Helgi Thormar",
                    "email": "[email protected]"
                },
                {
                    "name": "Greg Beaver",
                    "email": "[email protected]"
                }
            ],
            "description": "The PEAR Exception base class.",
            "homepage": "https://github.com/pear/PEAR_Exception",
            "keywords": [
                "exception"
            ],
            "support": {
                "issues": "**http://pear.php.net/bugs/search.php?cmd=display&package_name[]=PEAR_Exception**",
                "source": "https://github.com/pear/PEAR_Exception"
            },
            "time": "2019-12-10T10:24:42+00:00"
        }

introduce QA tools

• test framework phpunit based on dist config file
• test tool psalm based on dist config file
• test tool ComposerRequireChecker
• test tool composer-unused
• test tool php-cs-fixer based on dist config file
• have all tests in composer command as a suite
• cs-fixer script as composer command
• all composer commands have a description
• explanation in README
• tools installed via composer, maintained by dependabot
• have all of these in the CI chain

CI: use composer caching

CI: test `highest` instead of `stable`

current CI tests run on lowest and stable
goal: test highest instead of stable

add creation time to meta data

current implementation lacks the creation time in the meta data

for reproducible boms it's required to

• either have a CLI flag/switch to not add the date
• or have a ENV var CDX_REPRODUCIBLE to not not add the date
• or have an option to determine the DateTIme

acceptance criteria

• have creation time in meta data for XML
• have creation time in meta data for JSON
• time format is converted to zulu time, so there is no revelation of the timezoe the creating system is in
• have an option for reproducible-results

IDEA: SBOM schema: use `https` instead of `http`

current implementation uses schema paths as htp://...
use https://... instead

Add support for JSON output

In preparation of v1.2 of the spec we need to support JSON output.

Update examples in repo CycloneDX/sbom-examples

target: https://github.com/CycloneDX/sbom-examples/tree/master/laravel-7.12.0

• create new PR with latest examples
• close CycloneDX/bom-examples#11

v3: test all specs in CI demo

• add CI/CT for all supported spec versions in the reproducible examples
• push example output to https://github.com/CycloneDX/sbom-examples
  done via CycloneDX/bom-examples#11

streamline demo with CycloneDX/sbom-examples

there is a repo https://github.com/CycloneDX/sbom-examples
it hosts example output of this project as https://github.com/CycloneDX/sbom-examples/tree/master/laravel-7.12.0

there s a demo project for cyclonedx-php-composer: https://github.com/CycloneDX/cyclonedx-php-composer/tree/master/demo

goal: stream line both of them:

• adjust cyclonedx-php-composer's demo to produce the results for https://github.com/CycloneDX/sbom-examples/tree/master/laravel-7.12.0
  • might not be done completely correct. see discussion in this issue below
• link with https://github.com/CycloneDX/sbom-examples/tree/master/laravel-7.12.0
• update https://github.com/CycloneDX/sbom-examples/tree/master/laravel-7.12.0
  • update XML
  • add JSON
  • cross-link cyclonedx-php-composer's demo with https://github.com/CycloneDX/sbom-examples/tree/master/laravel-7.12.0
  • 💯 PR: CycloneDX/bom-examples#8
• dependabot must ignore demo dir
• reproducible tests check that SBOM output for XML files did not change
• reproducible tests check that SBOM output for JSON files did not change

---

demo project and reproducible outcome is available here:
https://github.com/CycloneDX/cyclonedx-php-composer/tree/master/demo/laravel-7.12.0

better support for non-default/local/internal package sources

packages may come from local sources.
packages may come from alternative registries.

acc / crit

• local components are marked with relative: true, path: /path/to/pod
• the PURL should have a qualifier to indicate the non-default package registry
  • spec via a qualifier from https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst#known-qualifiers-keyvalue-pairs
  • caused package-url/packageurl-php#54
  • reminder: don't add "default" PURL qualifiers. (if such a thing exists)
• there must be a switch to have "short" PURLs - for reasons like CycloneDX/cyclonedx-node-npm#225
• the demo for "local" is updated

example source data

• in this case, the composer.lock file would look like this

  {
  "packages": [
  {
              "name": "cyclonedx-demo/local-demo-dependency",
              "version": "1.33.7",
              "dist": {
                  "type": "path",
                  "url": "packages/local-demo-dependency",
                  "reference": "some-hash"
              },
              "type": "library",
              "description": "a package that is hosted locally and required in a local demo",
              "transport-options": {
                  "relative": true
              }
          }
  ]
  }

• see the example from #324 which installs from an alternative registry.
  Unfortunately, composer does not give any evidence for non-standard package registries, so this is currently not detectable properly. Maybe with a later version of composer -- need to investigate further.

Add support for BOM metadata in v1.2 of the spec

The BOM metadata portion should, at a minimum, contain the tool and version of the tool used to create the BOM. In this case, it will be the PHP Composer implementation.

I don't think composer will give us much more of anything else to put into bom metadata. But at a minimum, we should support the tools element.

demo in CI: composer v1

continues from #29

• demo composer v2 on highest supported php version -- was done via #29
• demo composer v1 on lowest supported php version

⚠️
this is some kind of an issue, since composer1 cannot install a package into itself ...
so nesting and running the demo in its own is not working out of the box.

require `composer-plugin-api: ^2.3` (was `^2`)

currently supporting composer ^2.0.0
composer 2.2. will be the next LTS for php <7.3 ...

sinde the next version is not planned to support that low versions of PHP, we could just go to the 2.3 and use the latest features.

see https://github.com/composer/composer/releases/tag/2.3.0
see https://blog.packagist.com/composer-2-3/

demo in CI

have a demo in the CI

• use lowest supported composer version - continued in #50
• use latest supported composer version
• demo code is linguist-ignored
• demo files are not in dist-release

rework "normalizing" of composer versions

backgroud

in php/composer the v prefix in versions is understood by the ecosystem. it "heals" itself regarding a missing/existing v.
in the lock file the actual version is used; the v is added/removed to match the correct prefix of the actual version. (example)

I would prefer to keep the v if composer found that it is part of the actual version.
I would prefer not to modify the version, but keep the one that is idiomatic to the composer ecosystem.

but unfortunately this would be a change of the implementation since v1 that is actually kept until now(v3) since it seams to be there for a reason (, which drives me mad since the actual version sometimes has a v for real).

proposal

dont handle a leading v in any special way. just leave everything as is.
additionally: make it optional(opt-in) to strip the v in front of a version. (only if there is an actual need for this, dont write this feature unless it is required)

impact

this would be a breaking change, since current implementation strips the v per default.
Proposed change would remove this behavior per default.

acceptance criteria

• the v is not stripped, if composer tells that it exists.
• remove --no-version-normalization option and related capabilities
• remove the "normalizer" entirely

work packages

tbd

make SBOM without composer-plugin

current implementation is a composer plugin.
this has some flaws:

• cannot generate the SBOM for lock files outside of the current composerized project.
  can generate SBOM only based in current project.

  this is not an issue at the moment, since this plugin does not utilize any composer-requirements on its own.
  so current switches --exclude-dev or --exclude-plugins can exclude cyclonedx-php-composer at the moment.

  in the future it is planned to change, to incorporate package-url/packageurl-php.
  with this change, the plugin will ship an own dep, which is not excludable via the --exclude-dev switch at the moment.

---

IDEA: ship a "binary" that can generate SBOM based on a lock file, without leverage of composer-plugin

BENEFIT:

• generated SBOM can be built without requirements of cyclonedx-php-composer.

---

THOUGHTS:

• its planned to have a cyclonedx-php-core which holds all needed models, functionality ...
• why not ship a php script as "binary" with it, that can generate SBOM based on any lock file?

use ` package-url/packageurl-php`

instead of build the purl string by hand, use composer requirement package-url/packageurl-php

this requires php7.3 at the moment.
so to have this issue solved, cyclonedx-php-composer needs to raise its minimum requirements. (or packageurl-php lowers its own)

use `declare_strict`

use declare(strict_types=1); in all files.

see https://www.php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations
see https://www.php.net/manual/en/language.types.declarations.php#language.types.declarations.strict

---

this is not necessarily a breaking change, since strict types affect only the files, that declare it.
so only the files of this very package are affected.
BUT it seams to be a breaking change for this project, since type full hinting was not introduced into this project yet.
version 1.* and version 2.* of this did not have it per se.
SO it is a braking change!

move "CORE" to own package

see https://github.com/CycloneDX/cyclonedx-php-composer/milestone/5

impact

as long as all interfaces/namespaces stay untouched, this would not be a breaking change.

The new external package/library is a one-to-one copy of the original code from this project, which now is a dependency/required of this project. So usage/leverage of the original code is still possible without any changes for third parties.

benefit:

• core can evolve independently from the plugin: features/bugfixes are independent from plugin's release cycle

acc / crit:

• non-composer-plugin-namespaces are removed from psr4 autoloader - via #127
• non-composer-plugin-classes(all not in folder src/Composer ) are moved to an own package, that is required by the plugin - via #127

---

steps in order

1. create new repo see https://github.com/CycloneDX/cyclonedx-php-library
2. copy the code to new repo & test it
3. make repo a composer package
4. publsh at https://packagist.org
5. tag the new package
6. remove now "external"/duplicated files from plugin-repo - via #127
7. require the new package in the plugin package with an appropriate version range - via #127
8. have the usage as a lib merged to master

---

possible followups: / ideas for the extracketd package:

• rename namespace CycloneDX\Core\Serialize to CycloneDX\Core\Serialization -- moved to CycloneDX/cyclonedx-php-library#5
• rename namespace CycloneDX\Core\Validate to CycloneDX\Core\Validation -- moved to CycloneDX/cyclonedx-php-library#5
• Json normalizers returns object of stdClass instead of associative arrays -- see CycloneDX/cyclonedx-php-library#4
  • therefore revisit the serialisers in general and simplify them !

configuration file

benefit: have the config in a file, so no CLI parameters are needed

parameter defaults are read from the config-file, and may override system defaults.
parameters can still be overridden via CLI parameters

implementation details: use extra section of the composer file.
see https://getcomposer.org/doc/04-schema.md#extra

---

acc / crit

• config overrides system defaults (therefore config file settings = presets)
• CLI params override any defaults/presets
• parameter type checks are (still) in place
• parameter plausibility checks are still in place
• config possibility is documented
  (+ docs have hint, that this config can be used with the gh-action -- see CycloneDX/gh-php-composer-generate-sbom#1)

[2022-11-28] drop support of php<=7.4

---

on 2022-11-28 the support for php7.4 will end.

lets take this for a change to switch the min-version of this plugin to 8 .
see https://www.php.net/manual/en/migration80.php
so to use the new language features, a breaking change will happen:

• drop php7.4 from CI
• drop php7.4 from composer manifest (php: ^8)
• migrate to php8 via php-cs-fixer
• review the proposals below

related: CycloneDX/cyclonedx-php-library#114

---

on 2021-12-06 the support for php7.3 ended.

lets take this for a change to switch the min-version of this plugin to 7.4 .
see https://www.php.net/manual/en/migration74.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
• update ergebnis/composer-normalize to a version that does not need php7.3 - #174
• review the proposals below

related: CycloneDX/cyclonedx-php-library#6

---

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;
}

---