From 4af1ed0d3c921bcacd7df891852f550ce2663a5a Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Thu, 12 Nov 2026 23:49:12 +0100 Subject: [PATCH] Add Orgs\Hooks::editHook() and stop edit() from creating hooks Orgs\Hooks::edit() posted to /orgs/{org}/hooks, the create endpoint, and has no parameter for the hook ID, so every call created another webhook. Add editHook($org, $id, ...), which patches /orgs/{org}/hooks/{id} with a JSON body that contains only the given values. Deprecate edit() and make it throw instead of creating a duplicate hook. Co-Authored-By: Claude Opus 5.5 --- Tests/Package/Orgs/HooksTest.php | 66 ++++++++++++++++++++------- composer.json | 3 +- docs/overview.md | 12 +++++ src/Package/Orgs/Hooks.php | 77 ++++++++++++++++++++++++++------ 4 files changed, 128 insertions(+), 30 deletions(-) diff --git a/Tests/Package/Orgs/HooksTest.php b/Tests/Package/Orgs/HooksTest.php index 57a2b3a2..87f55ca2 100644 --- a/Tests/Package/Orgs/HooksTest.php +++ b/Tests/Package/Orgs/HooksTest.php @@ -9,6 +9,7 @@ use Joomla\Github\Package\Orgs\Hooks; use Joomla\Github\Tests\Stub\GitHubTestCase; +use PHPUnit\Framework\Attributes\IgnoreDeprecations; /** * Test class. @@ -132,53 +133,86 @@ public function testCreateInvalidEvent() } /** - * Test method. - * - * @covers \Joomla\Github\Package\Orgs\Hooks::edit() + * Tests that edit() no longer creates a hook * * @return void */ + #[IgnoreDeprecations] public function testEdit() { - $this->response = $this->getResponseObject($this->sampleString, 201); + $this->expectUserDeprecationMessageMatches('/' . preg_quote('Hooks::edit() is deprecated and will be removed in 5.0', '/') . '/'); + $this->expectException(\BadMethodCallException::class); + + $this->client->expects($this->never()) + ->method('post'); + + $this->object->edit('{org}', '{url}', 'json', '{secret}', 1, ['create'], true); + } + + /** + * Tests that editHook() patches the given hook and sends only the given values as JSON + * + * @return void + */ + public function testEditHook() + { + $this->client->expects($this->never()) + ->method('post'); $this->client->expects($this->once()) - ->method('post') - ->with('/orgs/{org}/hooks') + ->method('patch') + ->with( + '/orgs/{org}/hooks/42', + '{"config":{"url":"{url}","content_type":"json","insecure_ssl":1,"secret":"{secret}"},"active":true,"events":["create"]}' + ) ->willReturn($this->response); $this->assertThat( - $this->object->edit('{org}', '{url}', 'json', '{secret}', 1, ['create'], true), + $this->object->editHook('{org}', 42, '{url}', 'json', '{secret}', true, ['create'], true), $this->equalTo(json_decode($this->sampleString)) ); } /** - * Test method. + * Tests that editHook() leaves out the values that are not given * - * @covers \Joomla\Github\Package\Orgs\Hooks::edit() + * @return void + */ + public function testEditHookPartial() + { + $this->client->expects($this->once()) + ->method('patch') + ->with('/orgs/{org}/hooks/42', '{"active":false}') + ->willReturn($this->response); + + $this->assertThat( + $this->object->editHook('{org}', 42, active: false), + $this->equalTo(json_decode($this->sampleString)) + ); + } + + /** + * Tests editHook() with an invalid content type * * @return void */ - public function testEditFailure() + public function testEditHookFailure() { $this->expectException(\UnexpectedValueException::class); - $this->object->edit('{org}', '{url}', '{invalid}'); + $this->object->editHook('{org}', 42, '{url}', '{invalid}'); } /** - * Test method. - * - * @covers \Joomla\Github\Package\Orgs\Hooks::edit() + * Tests editHook() with an invalid event * * @return void */ - public function testEditFailure2() + public function testEditHookInvalidEvent() { $this->expectException(\RuntimeException::class); - $this->object->edit('{org}', '{url}', 'json', '{secret}', 1, ['{invalid}']); + $this->object->editHook('{org}', 42, '{url}', 'json', '{secret}', true, ['{invalid}']); } /** diff --git a/composer.json b/composer.json index 49ad2e0a..d44c9b57 100644 --- a/composer.json +++ b/composer.json @@ -9,7 +9,8 @@ "php": "^8.3.0", "joomla/http": "^4.0", "joomla/registry": "^4.0", - "joomla/uri": "^4.0" + "joomla/uri": "^4.0", + "symfony/deprecation-contracts": "^2|^3" }, "require-dev": { "phpunit/phpunit": "^12.2.7", diff --git a/docs/overview.md b/docs/overview.md index cfd53634..de86dfcc 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,3 +1,15 @@ # Github API package TODO + +## Organization webhooks + +`$github->orgs->hooks->editHook($org, $id, ...)` edits an organization webhook (`PATCH /orgs/{org}/hooks/{hook_id}`) +and sends only the values that are given: + +```php +$github->orgs->hooks->editHook('joomla', 12345, active: false); +``` + +`$github->orgs->hooks->edit()` is deprecated and throws a `BadMethodCallException`. It has no hook ID parameter and +used to send the request to the create endpoint, so every call created another webhook. diff --git a/src/Package/Orgs/Hooks.php b/src/Package/Orgs/Hooks.php index 23dc959d..ec0dd825 100644 --- a/src/Package/Orgs/Hooks.php +++ b/src/Package/Orgs/Hooks.php @@ -126,6 +126,9 @@ public function create($org, $url, $contentType = 'form', $secret = null, $insec /** * Edit a hook. * + * This method never edited a hook: it sent the request to the endpoint that creates one, and it has no parameter + * for the hook ID. It now throws an exception instead of creating a duplicate hook. + * * @param string $org The name of the organization. * @param string $url The URL to which the payloads will be delivered. * @param string $contentType The media type used to serialize the payloads. Supported values include "json" and "form". @@ -140,18 +143,65 @@ public function create($org, $url, $contentType = 'form', $secret = null, $insec * @return object * * @since 1.4.0 - * @throws \UnexpectedValueException + * @throws \BadMethodCallException + * @deprecated 5.0 Use editHook() instead. */ public function edit($org, $url, $contentType = null, $secret = null, $insecureSsl = null, array $events = [], $active = null) { + trigger_deprecation( + 'joomla/github', + '__DEPLOY_VERSION__', + '%s() is deprecated and will be removed in 5.0, use %s::editHook() instead.', + __METHOD__, + self::class + ); + + throw new \BadMethodCallException( + sprintf('%s() cannot edit a hook because it has no hook ID; use %s::editHook() instead.', __METHOD__, self::class) + ); + } + + /** + * Edit a hook. + * + * Only the given values are changed. + * + * @param string $org The name of the organization. + * @param integer $id The hook ID. + * @param string|null $url The URL to which the payloads will be delivered. + * @param string|null $contentType The media type used to serialize the payloads. Supported values are "json" and "form". + * @param string|null $secret If provided, payloads will be delivered with an X-Hub-Signature header. + * @param boolean|null $insecureSsl Determines whether the SSL certificate of the host for url will be verified when + * delivering payloads. If false, verification is performed. If true, it is not. + * @param array $events Determines what events the hook is triggered for. Empty to leave them unchanged. + * @param boolean|null $active Determines whether the hook is actually triggered. + * + * @return object + * + * @since __DEPLOY_VERSION__ + * @throws \UnexpectedValueException + * @throws \RuntimeException + */ + public function editHook( + string $org, + int $id, + ?string $url = null, + ?string $contentType = null, + ?string $secret = null, + ?bool $insecureSsl = null, + array $events = [], + ?bool $active = null + ) { // Build the request path. - $path = "/orgs/$org/hooks"; + $path = "/orgs/$org/hooks/" . $id; - $config = [ - 'url' => $url, - ]; + $config = []; - if ($contentType) { + if ($url !== null) { + $config['url'] = $url; + } + + if ($contentType !== null) { if (\in_array($contentType, ['form', 'json']) == false) { throw new \UnexpectedValueException('Content type must be either "form" or "json".'); } @@ -163,16 +213,18 @@ public function edit($org, $url, $contentType = null, $secret = null, $insecureS $config['insecure_ssl'] = (int) $insecureSsl; } - if ($secret) { + if ($secret !== null) { $config['secret'] = $secret; } - $data = [ - 'config' => (object) $config, - ]; + $data = []; + + if ($config) { + $data['config'] = $config; + } if ($active !== null) { - $data['active'] = (bool) $active; + $data['active'] = $active; } if (!empty($events)) { @@ -187,8 +239,7 @@ public function edit($org, $url, $contentType = null, $secret = null, $insecureS } return $this->processResponse( - $this->client->post($this->fetchUrl($path), $data), - 201 + $this->client->patch($this->fetchUrl($path), json_encode($data)) ); }