CycloneDX’s PHP Library documentation
OWASP CycloneDX is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction.
This PHP library provides data models, validators and more, to help you create/render CycloneDX documents.
Install
Install via composer:
composer require cyclonedx/cyclonedx-library
Examples
1<?php
2
3declare(strict_types=1);
4
5/*
6 * This file is part of CycloneDX PHP Library.
7 *
8 * Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
19 *
20 * SPDX-License-Identifier: Apache-2.0
21 * Copyright (c) OWASP Foundation. All Rights Reserved.
22 */
23
24namespace CycloneDX\Examples;
25
26require_once __DIR__.'/../vendor/autoload.php';
27
28// Example how to serialize a Bom to JSON / XML.
29
30$lFac = new \CycloneDX\Core\Factories\LicenseFactory();
31
32// region build the BOM
33
34$bom = new \CycloneDX\Core\Models\Bom();
35$bom->getMetadata()->setComponent(
36 $rootComponent = new \CycloneDX\Core\Models\Component(
37 \CycloneDX\Core\Enums\ComponentType::Application,
38 'myApp'
39 )
40);
41$rootComponent->getBomRef()->setValue('myApp');
42$rootComponent->getLicenses()->addItems($lFac->makeFromString('MIT OR Apache-2.0'));
43
44$component = new \CycloneDX\Core\Models\Component(
45 \CycloneDX\Core\Enums\ComponentType::Library,
46 'myComponent'
47);
48$component->getLicenses()->addItems($lFac->makeFromString('MIT'));
49$bom->getComponents()->addItems($component);
50
51$rootComponent->getDependencies()->addItems($component->getBomRef());
52
53// endregion build the BOM
54
55$spec = \CycloneDX\Core\Spec\SpecFactory::make1dot6();
56
57$prettyPrint = false;
58
59$serializedJSON = (new \CycloneDX\Core\Serialization\JsonSerializer(
60 new \CycloneDX\Core\Serialization\JSON\NormalizerFactory($spec)
61))->serialize($bom, $prettyPrint);
62echo $serializedJSON, \PHP_EOL;
63$jsonValidationErrors = (new \CycloneDX\Core\Validation\Validators\JsonValidator($spec))->validateString($serializedJSON);
64if (null === $jsonValidationErrors) {
65 echo 'JSON valid', \PHP_EOL;
66} else {
67 fwrite(\STDERR, \PHP_EOL.'JSON ValidationError:'.\PHP_EOL);
68 fwrite(\STDERR, print_r($jsonValidationErrors, true));
69 exit(1);
70}
71
72$serializedXML = (new \CycloneDX\Core\Serialization\XmlSerializer(
73 new \CycloneDX\Core\Serialization\DOM\NormalizerFactory($spec)
74))->serialize($bom, $prettyPrint);
75echo $serializedXML, \PHP_EOL;
76$xmlValidationErrors = (new \CycloneDX\Core\Validation\Validators\XmlValidator($spec))->validateString($serializedXML);
77if (null === $xmlValidationErrors) {
78 echo 'XML valid', \PHP_EOL;
79} else {
80 fwrite(\STDERR, \PHP_EOL.'XML ValidationError:'.\PHP_EOL);
81 fwrite(\STDERR, print_r($xmlValidationErrors, true));
82 exit(2);
83}
API Reference
See the rendered PhpDoc
Contributing
Pull requests are welcome. But please read the CycloneDX contributing guidelines first.
Setup
The development-setup requires PHP >= 7.4, even though the project might support PHP 7.3 on runtime.
To start developing simply run composer run-script dev-setup
to install dev-dependencies and tools.
Tests
Make sure
to run
composer run-script cs-fix
to have the coding standards applied.to run
composer run-script test
and pass all tests.
Sign off your commits
Please sign off your commits, to show that you agree to publish your changes under the current terms and licenses of the project , and to indicate agreement with Developer Certificate of Origin (DCO).
git commit --signed-off ...
Changelog
All notable changes to this project will be documented in this file.
unreleased
3.3.1 - 2024-05-06
3.3.0 - 2024-04-26
Changed
Added
Namespace
\CycloneDX\Core\Enums
Namespace
\CycloneDX\Core\Models\License
3.2.0 - 2024-04-10
Added basic support for *CycloneDX* Specification-1.6.
Changed
Method
\CycloneDX\Core\Spec\SpecFactory::makeForVersion()
supports CycloneDX Specification-1.6 now (#421 via #422)Classes
\CycloneDX\Core\Serialization\{DOM,JSON}\Normalizers\*
support CycloneDX Specification-1.6 now (#421 via #422)Classes
\CycloneDX\Core\Validation\Validators\*
support CycloneDX Specification-1.6 now (#421 via #422)
Added
Style
Applied latest PHP Coding Standards (via #415)
3.1.2 - 2024-03-18
Documentation
Rendered (API) docs are hosted on readthedocs (#8 via #414)
3.1.1 - 2024-02-05
3.1.0 - 2023-12-02
Added
Migration/fixup of URL(
iri-reference
) when normalizing to JSON (via #380)
3.0.2 - 2023-11-27
3.0.1 - 2023-09-16
Fixed
fixed a possible JSON schema validation issue regarding “version” property (via #352)
3.0.0 - 2023-08-27
BREAKING
Style
Applied latest PHP Coding Standards (via #341)
2.3.0 - 2023-06-27
Added support for *CycloneDX* Specification-1.5.
Changed
Method
\CycloneDX\Core\Spec\SpecFactory::makeForVersion()
supports CycloneDX Specification-1.5 now (#193 via #255)Classes
\CycloneDX\Core\Serialization\{DOM,JSON}\Normalizers\*
support CycloneDX Specification-1.5 now (#193 via #255)Classes
\CycloneDX\Core\Validation\Validators\*
support CycloneDX Specification-1.5 now (#193 via #255)
Added
Namespace
\CycloneDX\Core\Enums
Enum
ComponentType
got new cases (#193 via #255)
New:Data
,DeviceDriver
,MachineLearningModel
,Platform
Enum
ExternalReferenceType
got new cases (#193 via #255)
New:AdversaryModel
,Attestation
,CertificationReport
,CodifiedInfrastructure
,ComponentAnalysisReport
,Configuration
,DistributionIntake
,DynamicAnalysisReport
,Evidence
,ExploitabilityStatement
,Formulation
,Log
,MaturityReport
,ModelCard
,POAM
,PentestReport
,QualityMetrics
,RiskAssessment
,RuntimeAnalysisReport
,SecurityContact
,StaticAnalysisReport
,ThreatModel
,VulnerabilityAssertion
Namespace
\CycloneDX\Core\Spec
Misc
2.2.0 - 2023-06-02
Changed
Class
\CycloneDX\Core\Serialization\JsonSerializer
Class
\CycloneDX\Core\Serialization\XmlSerializer
Style
2.1.2 - 2023-04-05
Fixed
Docs
Fixed link to CycloneDX-specification in README (via #288)
2.1.1 - 2023-03-28
2.1.0 - 2023-03-24
Fixed
Changed
Added
Published generator for BOM’s SerialNumber:
\CycloneDX\Core\Utils\BomUtility::randomSerialNumber()
(#277 via #278)
The code was donated from cyclonedx-php-composer.
2.0.0 - 2023-03-20
BREAKING
Removed support for PHP v8.0 (via #204)
Changed models’ aggregation properties to be no longer optional (#66 via #131)
Streamlined repository data structures to follow a common method naming scheme (via #131)
Enumeration-like classes were converted to native PHP Enumerations (#140, #256 via #204, #257)
Added
Misc
API changes v2 - the details
Overall
BREAKING: enforced the use of concrete UnionTypes instead of protocols/interfaces/abstracts (#114 via #125)
Affected the usages of no longer public\CycloneDX\Core\Models\License\AbstractDisjunctiveLicense
and methods that used license-related classes. This was possible due to PHP8’s UnionType language feature.Changed some methods to no longer throw
\InvalidArgumentException
(via #125)
PhpDoc annotations were updated, so that code analysis tools should pick up. This was possible by enforcing correct typing on PHP8 language level.BREAKING: every occurrence of
{M,m}etaData
with a capital “D” was renamed to{M,m}etadata
with a small “d” (#133 via #131, #149)
This affects class names, method names, variable names, property names, file names, documentation - everything.
\CycloneDX\Core\Collections
namespace\CycloneDX\Core\Enum
namespaceClassification
classExternalReferenceType
classHashAlgorithm
class
CycloneDX\Core\Factories
namespaceLicenseFactory
classBREAKING: check whether something is a valid SPDX Expression is now complete, was best effort implementation (#247 via #249)
This affects all methods that potentially would createLicenseExpression
models.
Utilizes ``composer/spdx-licenses` <https://packagist.org/packages/composer/spdx-licenses>`_.BREAKING: changed constructor method
__construct()
(via #249)BREAKING: removed method
makeDisjunctiveFromExpression()
(#163 vial #166)BREAKING: removed method
setSpdxLicenseValidator()
(via #249)BREAKING: renamed method
getSpdxLicenseValidator()
->getLicenseIdentifiers()
(via #249)BREAKING: renamed method
makeDisjunctiveWithId()
->makeSpdxLicense()
(#164 vial #168)BREAKING: renamed method
makeDisjunctiveWithName()
->makeNamedLicense()
(#164 vial #168)Added new method
getSpdxLicenses()
(via #249)
\CycloneDX\Core\Models
namespaceBom
classBREAKING: changed constructor to no longer accept components (#187 via #188)
BREAKING: renamed methods
{get,set}ComponentRepository()
->{get,set}Components()
(#133 via #131)BREAKING: renamed methods
{get,set}ExternalReferenceRepository()
->{get,set}ExternalReferences()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)BREAKING: renamed methods
{get,set}MetaData()
->{get,set}Metadata()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)Added new methods
{get,set}SerialNumber()
(via #186)
Component
classBREAKING: renamed methods
{get,set}DependenciesBomRefRepository()
->{get,set}Dependencies()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)BREAKING: renamed methods
{get,set}ExternalReferenceRepository()
->{get,set}ExternalReferences()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)BREAKING: renamed methods
{get,set}HashRepository()
->{get,set}Hashes()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)BREAKING: renamed methods
{get,set}License()
->{get,set}Licenses()
(via #131)
Also changed it work with classLicenseRepository
only, was working with variousModels\License\*
types (#66 via #131)BREAKING: changed class property
version
to be optional, to reflect CycloneDX v1.4 (#27 via #118, #131)
This affects constructor arguments, and affects methods{get,set}Version()
.BREAKING: changed property
type
to be of type\CycloneDX\Core\Enum\ComponentType
(#140 via #204)
This affects constructor arguments, and affects methods{get,set}Type()
.Added new methods
{get,set}Author()
([#184] via #185)
ExternalReference
classBREAKING: renamed methods
{get,set}HashRepository()
->{get,set}Hashes()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)BREAKING: changed property
type
to be of type\CycloneDX\Core\Enum\ExternalReferenceType
(#140 via #204)
This affects constructor arguments, and affects methods{get,set}Type()
.
Licenses
namespaceAbstractDisjunctiveLicense
DisjunctiveLicenseWithName
classDisjunctiveLicenseWithId
classLicenseExpression
class
MetaData
classBREAKING: renamed class to
Metadata
(#133 via #131)
Even though PHP is case-insensitive with class names, autoloaders may be case-sensitive. Therefore, this is considered a breaking change.BREAKING: changed methods
{get,set}Tools()
so that their parameter & return type is non-nullable, was nullable (#66 via #131)
Tool
classBREAKING: renamed methods
{get,set}ExternalReferenceRepository()
->{get,set}ExternalReferences()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)BREAKING: renamed methods
{get,set}HashRepository()
->{get,set}Hashes()
(#133 via #131)
Also changed parameter & return type to non-nullable, was nullable (#66 via #131)
\CycloneDX\Core\Repositories
namespaceOverall:
DisjunctiveLicenseRepository
classBREAKING: renamed the class to
\CycloneDX\Core\Collections\LicenseRepository
(via #131)BREAKING: added the capability to also aggregate instances of class
Models\LicenseExpression
(via #131)
Therefore, various getters and setters and the constructor changed their signatures, was usage of\CycloneDX\Core\Models\License\AbstractDisjunctiveLicense
only.
HashRepository
classBREAKING: renamed to
\CycloneDX\Core\Collections\HashDictionary
(#133 via #131)BREAKING: renamed all methods and changed all method signatures to match the overall streamlined scheme (#133 via #131)
BREAKING: changed all method signatures to enable handling of native PHP Enumeration type
\CycloneDX\Core\Enum\HashAlgorithm
(#140 via #204)
\CycloneDX\Core\Serialize
namespaceOverall
SerializerInterface
interfaceBaseSerializer
abstract classBREAKING: complete redesign (via #155)
{Json,Xml}Serializer
classBREAKING: complete redesign (via #155)
{DOM,JSON}\NormalizerFactory
classesBREAKING: removed method
makeForLicenseExpression()
(via #131)BREAKING: removed method
makeForDisjunctiveLicense()
(via #131)BREAKING: removed method
makeForDisjunctiveLicenseRepository()
(via #131)BREAKING: removed method
makeForHashRepositonary()
- usemakeForHashDictionary()
instead (#133 via #131)BREAKING: removed method
setSpec()
(via #131)Added new method
makeForLicense()
(via #131)Added new method
makeForLicenseRepository()
(via #131)
{DOM,JSON}\Normalizers
namespacesBREAKING: removed classes
DisjunctiveLicenseNormalizer
- useLicenseNormalizer
instead (via #131)BREAKING: removed classes
LicenseExpressionNormalizer
- useLicenseNormalizer
instead (via #131)BREAKING: removed classes
DisjunctiveLicenseRepositoryNormalizer
(via #131)BREAKING: renamed classes
HashRepositoryNormalizer
->HashDictionaryNormalizer
(#133 via #131)
Also changed signatures to acceptModels\HashDictionary
instead ofModels\HashRepository
BREAKING: changed signatures of class
HashNormalizer
to accept native PHP Enumeration type\CycloneDX\Core\Enum\HashAlgorithm
(#140 via #204)Added new classes
ComponentEvidenceNormalizer
that can normalizeComponentEvidence
(#238 via #241)Added new classes
LicenseNormalizer
that can normalize every existing license model (via #131)Added new classes
LicenseRepositoryNormalizer
that can normalizeLicenseRepository
(via #131)ExternalReferenceNormalizer
classesChanged the method
normalize()
to actually throw\DomainException
when\ExternalReference
‘s type was not supported by the spec (via #65)
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
JSON\Normalizers\BomNormalizer
classChanged: method
normalize()
‘s result data may contain the$schema
string (via #155)
JSON\Normalizers\ExternalReferenceNormalizer
classBREAKING: method
normalize()
may throw\UnexpectedValueException
when the url is invalid to format “ini-reference” (via #151)
\CycloneDX\Core\Spdx
namespaceBREAKING: renamed the class
License
->LicenseIdentifiers
(#133 via #143, #249)BREAKING: renamed method
getLicense()
->fixLicense()
(via #249)BREAKING: renamed method
getLicenses()
->getKnownLicenses()
, and removed keys from return value (via #249)BREAKING: renamed method
validate()
->isKnownLicense()
(via #249)
\CycloneDX\Core\Spec
namespace\CycloneDX\Core\Validation
namespaceBaseValidator
classBREAKING: removed deprecated method
setSpec()
(via #144)
ValidatorInterface
interfaceValidators\{Json,JsonStrict,Xml}Validator
classesValidators\{Json,JsonStrict}Validator
classes
1.6.3 - 2022-09-15
Maintenance Release.
Legal:
Transferred copyright to OWASP Foundation. (via #121)
1.6.2 - 2022-09-12
Maintenance release.
Docs:
Added “Responsibilities”, “Capabilities” and “Usage” sections to README. (via #115)
1.6.1 - 2022-08-16
Maintenance release.
1.6.0 - 2022-08-03
Changed
Use version 9b04a94 of CycloneDX specification for XML and JSON schema validation. (via #105)
Use SPDX license enumeration from version 9b04a94 of CycloneDX specification. (via #105)
Style
Fixe some whitespaces. (via #82)
1.5.0 - 2022-03-08
Changed
Use version 82bf9e3 of CycloneDX specification for XML and JSON schema validation. (via #79)
Use SPDX license enumeration from version 82bf9e3 of CycloneDX specification. (via #79)
1.4.2 - 2022-02-05
Fixed
Return type of
CycloneDX\Core\Serialize\SerializerInterface::serialize()
and implementations/usage are documented asnon-empty-string
, were undocumentedstring
before. (via #70)
1.4.1 - 2022-01-31
Fixed
CycloneDX\Core\Validation\ValidatorInterface::validateString()
and implementations are documented asnon-empty-string
, were undocumentedstring
before. (via #63)
1.4.0 - 2021-12-20
1.3.1 - 2021-12-03
Fixed
XML serializer & DOM normalizer no longer generate invalid
XML::anyURI
. (via #34)
1.3.0 - 2021-12-01
Changed
JSON result does no longer have slashes escaped in strings. (via #33)
Old:"http:\/\/exampe.com"
New:"http://exampe.com"
1.2.0 - 2021-11-29
Added
Prevention of information-loss on metadata-component’s ExternalReferences, when normalizing to a specification that does not support
bom.metadata
(via #26)
1.1.0 - 2021-11-25
Added
Support for ExternalReferences in BOM and Component (via #17)
1.0.3 - 2021-11-15
Fixed
CycloneDX\Core\Models\License\AbstractDisjunctiveLicense::setUrl()
no longer restricts the argument to be a valid URL.
Per schema definitionlicenseType.url
should be a URI, not a URL. See #18
Changed
CycloneDX\Core\Models\License\AbstractDisjunctiveLicense::setUrl()
no longer throwsInvalidArgumentException
if the argument is not a URL (via #19)
1.0.2 - 2021-10-30
Fixed
Psalm-annotation of
CycloneDX\Core\Enums\Classification::isValidValue()
(via #10)
1.0.1 - 2021-10-23
Removed composer’s conflict
constraint.
This was done to enable some workflows with package forks/mirrors that don’t have proper version detection.
See #9
1.0.0 - 2021-10-07
Initial release.
Split the library from
`/src/Core`` of cyclonedx-php-composer (346e6200fb2f5086061b15c2ee44f540893ce97d) <https://github.com/CycloneDX/cyclonedx-php-composer/tree/346e6200fb2f5086061b15c2ee44f540893ce97d/src/Core>`_