Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 215 additions & 0 deletions Tests/Package/DependencyGraphTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
<?php

/**
* Part of the Joomla Framework Github Package
*
* @copyright Copyright (C) 2005 - 2026 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE
*/

namespace Joomla\Github\Tests\Package;

use Joomla\Github\Package\DependencyGraph;
use Joomla\Github\Tests\Stub\GitHubTestCase;
use Joomla\Http\Exception\UnexpectedResponseException;
use PHPUnit\Framework\Attributes\CoversClass;

/**
* Test class for DependencyGraph.
*
* @since __DEPLOY_VERSION__
*/
#[CoversClass(DependencyGraph::class)]
class DependencyGraphTest extends GitHubTestCase
{
/**
* @var DependencyGraph Object under test.
* @since __DEPLOY_VERSION__
*/
protected $object;

/**
* Sets up the fixture, for example, opens a network connection.
* This method is called before a test is executed.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
protected function setUp(): void
{
parent::setUp();

$this->object = new DependencyGraph($this->options, $this->client);
}

/**
* Tests the compare method.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testCompare()
{
$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/compare/main...feature%2Fx?name=composer.json', [], 0)
->willReturn($this->getResponseObject($this->sampleString, 200));

$this->assertEquals(
json_decode($this->sampleString),
$this->object->compare('joomla', 'joomla-platform', 'main', 'feature/x', ['name' => 'composer.json'])
);
}

/**
* Tests the compare method - failure.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testCompareFailure()
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/compare/main...feature%2Fx', [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->compare('joomla', 'joomla-platform', 'main', 'feature/x');
}

/**
* Tests the createSnapshot method.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testCreateSnapshot()
{
$this->client->expects($this->once())
->method('post')
->with('/repos/joomla/joomla-platform/dependency-graph/snapshots', json_encode(['manifests' => ['composer.lock' => ['name' => 'composer.lock']], 'version' => 0, 'job' => ['correlator' => 'build', 'id' => '42'], 'sha' => 'ddc951f4b1293222421f2c8df679786153acf689', 'ref' => 'refs/heads/main', 'detector' => ['name' => 'composer-detector', 'version' => '1.0.0', 'url' => 'https://example.com'], 'scanned' => '2026-11-12T10:00:00Z']), [], 0)
->willReturn($this->getResponseObject($this->sampleString, 201));

$this->assertEquals(
json_decode($this->sampleString),
$this->object->createSnapshot('joomla', 'joomla-platform', 0, ['correlator' => 'build', 'id' => '42'], 'ddc951f4b1293222421f2c8df679786153acf689', 'refs/heads/main', ['name' => 'composer-detector', 'version' => '1.0.0', 'url' => 'https://example.com'], '2026-11-12T10:00:00Z', ['manifests' => ['composer.lock' => ['name' => 'composer.lock']]])
);
}

/**
* Tests the createSnapshot method - failure.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testCreateSnapshotFailure()
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('post')
->with('/repos/joomla/joomla-platform/dependency-graph/snapshots', json_encode(['version' => 0, 'job' => ['correlator' => 'build', 'id' => '42'], 'sha' => 'ddc951f4b1293222421f2c8df679786153acf689', 'ref' => 'refs/heads/main', 'detector' => ['name' => 'composer-detector', 'version' => '1.0.0', 'url' => 'https://example.com'], 'scanned' => '2026-11-12T10:00:00Z']), [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->createSnapshot('joomla', 'joomla-platform', 0, ['correlator' => 'build', 'id' => '42'], 'ddc951f4b1293222421f2c8df679786153acf689', 'refs/heads/main', ['name' => 'composer-detector', 'version' => '1.0.0', 'url' => 'https://example.com'], '2026-11-12T10:00:00Z');
}

/**
* Tests the generateSbomReport method.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testGenerateSbomReport()
{
$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/sbom/generate-report', [], 0)
->willReturn($this->getResponseObject($this->sampleString, 201));

$this->assertEquals(
json_decode($this->sampleString),
$this->object->generateSbomReport('joomla', 'joomla-platform')
);
}

/**
* Tests the generateSbomReport method - failure.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testGenerateSbomReportFailure()
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/sbom/generate-report', [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->generateSbomReport('joomla', 'joomla-platform');
}

/**
* Tests the fetchSbomReport method.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testFetchSbomReport()
{
$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/sbom/fetch-report/a1b2c3d4', [], 0)
->willReturn($this->getResponseObject('', 302, ['Location' => 'https://example.com/download']));

$this->assertSame('https://example.com/download', $this->object->fetchSbomReport('joomla', 'joomla-platform', 'a1b2c3d4'));
}

/**
* Tests the fetchSbomReport method while the report is still being generated.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testFetchSbomReportPending()
{
$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/sbom/fetch-report/a1b2c3d4', [], 0)
->willReturn($this->getResponseObject('', 202));

$this->assertSame('', $this->object->fetchSbomReport('joomla', 'joomla-platform', 'a1b2c3d4'));
}

/**
* Tests the fetchSbomReport method - failure.
*
* @return void
*
* @since __DEPLOY_VERSION__
*/
public function testFetchSbomReportFailure()
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/dependency-graph/sbom/fetch-report/a1b2c3d4', [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->fetchSbomReport('joomla', 'joomla-platform', 'a1b2c3d4');
}
}
35 changes: 35 additions & 0 deletions docs/dependency-graph.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Dependency Graph

The Dependency Graph package covers the GitHub REST API for the dependency graph: the dependency review diff between two commits, the submission of dependency snapshots and the SBOM report export. It is reached as `$github->dependencyGraph`, e.g. `$github->dependencyGraph->compare('joomla', 'joomla-cms', '5.3-dev', '6.0-dev')`.

```php
use Joomla\Github\Github;
use Joomla\Registry\Registry;

$github = new Github(new Registry(['gh.token' => 'your-token']));

// Dependency changes between two branches (requests GET .../compare/5.3-dev...6.0-dev)
$diff = $github->dependencyGraph->compare('joomla', 'joomla-cms', '5.3-dev', '6.0-dev');

// Request an SBOM and poll until the download URL is available
$report = $github->dependencyGraph->generateSbomReport('joomla', 'joomla-cms');
$uuid = basename($report->sbom_url);

while (($url = $github->dependencyGraph->fetchSbomReport('joomla', 'joomla-cms', $uuid)) === '') {
sleep(5);
}
```

## DependencyGraph (`$github->dependencyGraph`)

| Method | Endpoint |
| --- | --- |
| compare($owner, $repo, $base, $head, $filters) | GET /repos/{owner}/{repo}/dependency-graph/compare/{basehead} |
| createSnapshot($owner, $repo, $version, $job, $sha, $ref, $detector, $scanned, $options) | POST /repos/{owner}/{repo}/dependency-graph/snapshots |
| generateSbomReport($owner, $repo) | GET /repos/{owner}/{repo}/dependency-graph/sbom/generate-report |
| fetchSbomReport($owner, $repo, $sbomUuid) | GET /repos/{owner}/{repo}/dependency-graph/sbom/fetch-report/{sbom_uuid} |

## Notes

- `compare()` takes the base and head refs as two arguments; each is URL-encoded on its own and they are joined with `...`, as the `{basehead}` path segment requires.
- The deprecated `GET /repos/{owner}/{repo}/dependency-graph/sbom` (`dependency-graph/export-sbom`) is not covered; use `generateSbomReport()` and `fetchSbomReport()` instead.
144 changes: 144 additions & 0 deletions src/Package/DependencyGraph.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
<?php

/**
* Part of the Joomla Framework Github Package
*
* @copyright Copyright (C) 2005 - 2026 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE
*/

namespace Joomla\Github\Package;

use Joomla\Github\AbstractPackage;

/**
* GitHub API Dependency Graph class for the Joomla Framework.
*
* @link https://docs.github.com/rest/dependency-graph
*
* @since __DEPLOY_VERSION__
*/
class DependencyGraph extends AbstractPackage
{
/**
* Get a diff of the dependencies between commits.
*
* Both refs are encoded separately and joined with `...`.
*
* @param string $owner The account owner of the repository.
* @param string $repo The name of the repository.
* @param string $base The base ref or commit of the comparison.
* @param string $head The head ref or commit of the comparison.
* @param array $filters Optional query parameters: `name`.
*
* @return array
*
* @link https://docs.github.com/rest/dependency-graph/dependency-review#get-a-diff-of-the-dependencies-between-commits
* @since __DEPLOY_VERSION__
*/
public function compare(string $owner, string $repo, string $base, string $head, array $filters = [])
{
// Build the request path.
$path = '/repos/' . $owner . '/' . $repo . '/dependency-graph/compare/' . rawurlencode($base) . '...' . rawurlencode($head);

$uri = $this->fetchUrl($path);

foreach ($filters as $key => $value) {
$uri->setVar($key, \is_bool($value) ? ($value ? 'true' : 'false') : $value);
}

return $this->processResponse(
$this->client->get($uri),
200
);
}

/**
* Create a snapshot of dependencies for a repository.
*
* @param string $owner The account owner of the repository.
* @param string $repo The name of the repository.
* @param integer $version The version of the repository snapshot submission.
* @param array $job The job that created the snapshot (`correlator`, `id`, optional `html_url`).
* @param string $sha The commit SHA associated with this dependency snapshot.
* @param string $ref The repository branch that triggered this snapshot, e.g. `refs/heads/main`.
* @param array $detector The detector used (`name`, `version`, `url`).
* @param string $scanned The time the snapshot was scanned (ISO 8601).
* @param array $options Optional body fields: `metadata`, `manifests`.
*
* @return object
*
* @link https://docs.github.com/rest/dependency-graph/dependency-submission#create-a-snapshot-of-dependencies-for-a-repository
* @since __DEPLOY_VERSION__
*/
public function createSnapshot(string $owner, string $repo, int $version, array $job, string $sha, string $ref, array $detector, string $scanned, array $options = [])
{
// Build the request path.
$path = '/repos/' . $owner . '/' . $repo . '/dependency-graph/snapshots';

$data = array_merge($options, ['version' => $version, 'job' => $job, 'sha' => $sha, 'ref' => $ref, 'detector' => $detector, 'scanned' => $scanned]);

return $this->processResponse(
$this->client->post($this->fetchUrl($path), json_encode($data)),
201
);
}

/**
* Request generation of a software bill of materials (SBOM) for a repository.
*
* The returned `sbom_url` contains the UUID to pass to `fetchSbomReport()`.
*
* @param string $owner The account owner of the repository.
* @param string $repo The name of the repository.
*
* @return object
*
* @link https://docs.github.com/rest/dependency-graph/sboms#request-generation-of-a-software-bill-of-materials-sbom-for-a-repository
* @since __DEPLOY_VERSION__
*/
public function generateSbomReport(string $owner, string $repo)
{
// Build the request path.
$path = '/repos/' . $owner . '/' . $repo . '/dependency-graph/sbom/generate-report';

return $this->processResponse(
$this->client->get($this->fetchUrl($path)),
201
);
}

/**
* Fetch a software bill of materials (SBOM) for a repository.
*
* Returns the temporary download URL (`Location` header of the 302 response), or an empty
* string while the report is still being generated (202).
*
* @param string $owner The account owner of the repository.
* @param string $repo The name of the repository.
* @param string $sbomUuid The unique identifier of the SBOM export.
*
* @return string
*
* @link https://docs.github.com/rest/dependency-graph/sboms#fetch-a-software-bill-of-materials-sbom-for-a-repository
* @since __DEPLOY_VERSION__
*/
public function fetchSbomReport(string $owner, string $repo, string $sbomUuid)
{
// Build the request path.
$path = '/repos/' . $owner . '/' . $repo . '/dependency-graph/sbom/fetch-report/' . rawurlencode($sbomUuid);

$response = $this->client->get($this->fetchUrl($path));

// The SBOM is still being generated.
if ($response->getStatusCode() === 202) {
return '';
}

if ($response->getStatusCode() !== 302) {
$this->processResponse($response, 302);
}

return $response->getHeaderLine('Location');
}
}