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
145 changes: 145 additions & 0 deletions Tests/Package/LicensesTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
<?php

/**
* @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\Licenses;
use Joomla\Github\Tests\Stub\GitHubTestCase;
use Joomla\Http\Exception\UnexpectedResponseException;
use PHPUnit\Framework\Attributes\CoversClass;

/**
* Test class for Joomla\Github\Package\Licenses.
*
* @since __DEPLOY_VERSION__
*/
#[CoversClass(Licenses::class)]
class LicensesTest extends GitHubTestCase
{
/**
* @var Licenses Object under test.
* @since __DEPLOY_VERSION__
*/
protected $object;

/**
* Sets up the fixture.
*
* @return void
*/
protected function setUp(): void
{
parent::setUp();

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

/**
* Tests the getList method.
*
* @return void
*/
public function testGetList(): void
{
$this->client->expects($this->once())
->method('get')
->with('/licenses?page=2&per_page=10&featured=true', [], 0)
->willReturn($this->getResponseObject($this->sampleString, 200));

$this->assertEquals(
json_decode($this->sampleString),
$this->object->getList(['featured' => true], 2, 10)
);
}

/**
* Tests the getList method.
*
* @return void
*/
public function testGetListFailure(): void
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('get')
->with('/licenses?page=2&per_page=10&featured=true', [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->getList(['featured' => true], 2, 10);
}

/**
* Tests the get method.
*
* @return void
*/
public function testGet(): void
{
$this->client->expects($this->once())
->method('get')
->with('/licenses/mit', [], 0)
->willReturn($this->getResponseObject($this->sampleString, 200));

$this->assertEquals(
json_decode($this->sampleString),
$this->object->get('mit')
);
}

/**
* Tests the get method.
*
* @return void
*/
public function testGetFailure(): void
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('get')
->with('/licenses/mit', [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->get('mit');
}

/**
* Tests the getForRepo method.
*
* @return void
*/
public function testGetForRepo(): void
{
$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/license?ref=main', [], 0)
->willReturn($this->getResponseObject($this->sampleString, 200));

$this->assertEquals(
json_decode($this->sampleString),
$this->object->getForRepo('joomla', 'joomla-platform', ['ref' => 'main'])
);
}

/**
* Tests the getForRepo method.
*
* @return void
*/
public function testGetForRepoFailure(): void
{
$this->expectException(UnexpectedResponseException::class);

$this->client->expects($this->once())
->method('get')
->with('/repos/joomla/joomla-platform/license?ref=main', [], 0)
->willReturn($this->getResponseObject($this->errorString, 500));

$this->object->getForRepo('joomla', 'joomla-platform', ['ref' => 'main']);
}
}
23 changes: 23 additions & 0 deletions docs/licenses.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Licenses

The Licenses package covers the GitHub licenses REST API: the commonly used open source licenses, a single license and the license of a repository. It is reached as `$github->licenses`, for example `$github->licenses->get('mit')`.

```php
$github = new Joomla\Github\Github($options);

// Featured licenses only.
$licenses = $github->licenses->getList(['featured' => true]);

// The license of a repository.
$license = $github->licenses->getForRepo('joomla', 'joomla-cms');
```

## Licenses

`$github->licenses` - https://docs.github.com/rest/licenses/licenses

| Method | Endpoint |
| --- | --- |
| `getList($filters, $page, $limit)` | `GET /licenses` |
| `get($license)` | `GET /licenses/{license}` |
| `getForRepo($owner, $repo, $filters)` | `GET /repos/{owner}/{repo}/license` |
96 changes: 96 additions & 0 deletions src/Package/Licenses.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
<?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 Licenses class for the Joomla Framework.
*
* @link https://docs.github.com/rest/licenses/licenses
*
* @since __DEPLOY_VERSION__
*/
class Licenses extends AbstractPackage
{
/**
* Get all commonly used licenses.
*
* @param array $filters Optional query parameters: `featured`.
* @param int $page The page number from which to get items.
* @param int $limit The number of items on a page.
*
* @return object|array
*
* @link https://docs.github.com/rest/licenses/licenses#get-all-commonly-used-licenses
* @since __DEPLOY_VERSION__
*/
public function getList(array $filters = [], int $page = 0, int $limit = 0)
{
// Build the request path.
$path = '/licenses';

$uri = $this->fetchUrl($path, $page, $limit);

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

$uri->setVar($key, $value);
}

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

/**
* Get a license.
*
* @param string $license The license key, e.g. `mit`.
*
* @return object|array
*
* @link https://docs.github.com/rest/licenses/licenses#get-a-license
* @since __DEPLOY_VERSION__
*/
public function get(string $license)
{
// Build the request path.
$path = '/licenses/' . rawurlencode($license);

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

/**
* Get the license for a repository.
*
* @param string $owner The account owner of the repository.
* @param string $repo The name of the repository.
* @param array $filters Optional query parameters: `ref`.
*
* @return object|array
*
* @link https://docs.github.com/rest/licenses/licenses#get-the-license-for-a-repository
* @since __DEPLOY_VERSION__
*/
public function getForRepo(string $owner, string $repo, array $filters = [])
{
// Build the request path.
$path = '/repos/' . $owner . '/' . $repo . '/license';

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

foreach ($filters as $key => $value) {
$uri->setVar($key, $value);
}

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