feat/ci methods

.horde.yml

@@ -40,3 +40,4 @@ quality:
   phpstan:
     level: 5
 vendor: horde
+keywords: []

bin/demo-client.php

@@ -22,6 +22,7 @@
 use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\RequestFactoryInterface;
 use Psr\Http\Message\StreamFactoryInterface;
+use Exception;
 
 // Bootstrap the injector
 $strGithubApiToken = (string) getenv('GITHUB_TOKEN');
@@ -181,7 +182,7 @@
             echo "  ✓ Reopened PR #{$reopenedPr->number}, state: {$reopenedPr->state}\n";
         }
 
-    } catch (\Exception $e) {
+    } catch (Exception $e) {
         echo "  ✗ Error: {$e->getMessage()}\n";
         echo "  Note: Make sure the head branch exists and differs from base branch\n";
     }

bin/demo-token-info.php

@@ -19,6 +19,7 @@
 use Horde\Http\ResponseFactory;
 use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\RequestFactoryInterface;
+use Exception;
 
 // Check for GitHub token
 $strGithubApiToken = (string) getenv('GITHUB_TOKEN');
@@ -60,7 +61,7 @@
     }
 
     echo "\n";
-} catch (\Exception $e) {
+} catch (Exception $e) {
     echo "  └─ ✗ Error: " . $e->getMessage() . "\n\n";
 }
 
@@ -89,7 +90,7 @@
     }
 
     echo "\n";
-} catch (\Exception $e) {
+} catch (Exception $e) {
     echo "  └─ ✗ Error: " . $e->getMessage() . "\n\n";
 }
 

src/Auth/PrivateKey.php

@@ -17,6 +17,7 @@
 namespace Horde\GithubApiClient\Auth;
 
 use InvalidArgumentException;
+use OpenSSLAsymmetricKey;
 
 class PrivateKey
 {
@@ -57,9 +58,9 @@ public static function fromFile(string $filePath): self
     }
 
     /**
-     * @return \OpenSSLAsymmetricKey
+     * @return OpenSSLAsymmetricKey
      */
-    public function getResource(): \OpenSSLAsymmetricKey
+    public function getResource(): OpenSSLAsymmetricKey
     {
         $resource = openssl_pkey_get_private($this->content);
         if ($resource === false) {

src/CreateCheckRunParams.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\GithubApiClient;
+
+use DateTimeImmutable;
+
+/**
+ * Data transfer object for creating a Check Run
+ *
+ * Copyright 2026 The Horde Project (http://www.horde.org/)
+ *
+ * See the enclosed file LICENSE for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @category Horde
+ * @package  GithubApiClient
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ */
+class CreateCheckRunParams
+{
+    /**
+     * @param string $name Display name of the check (required)
+     * @param string $headSha SHA of the commit being checked (required)
+     * @param string $status One of queued, in_progress, completed (default: completed)
+     * @param string $conclusion One of success, failure, neutral, cancelled, skipped, timed_out, action_required. Required by GitHub when status === 'completed'; only emitted when non-empty
+     * @param DateTimeImmutable|null $startedAt When the check started; emitted as ISO 8601 in started_at
+     * @param DateTimeImmutable|null $completedAt When the check completed; emitted as ISO 8601 in completed_at
+     * @param string $detailsUrl URL the user lands on when clicking the check (default: empty, omitted)
+     * @param string $externalId External reference id (default: empty, omitted)
+     * @param array<string, mixed>|null $output Output payload: {title, summary, text?, annotations?, images?}; passed verbatim when set
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly string $headSha,
+        public readonly string $status = 'completed',
+        public readonly string $conclusion = '',
+        public readonly ?DateTimeImmutable $startedAt = null,
+        public readonly ?DateTimeImmutable $completedAt = null,
+        public readonly string $detailsUrl = '',
+        public readonly string $externalId = '',
+        public readonly ?array $output = null,
+    ) {}
+
+    /**
+     * Convert to array for API request body.
+     *
+     * Required fields always emit. Optional fields drop out when at their
+     * default (empty string / null).
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        $data = [
+            'name' => $this->name,
+            'head_sha' => $this->headSha,
+            'status' => $this->status,
+        ];
+
+        if ($this->conclusion !== '') {
+            $data['conclusion'] = $this->conclusion;
+        }
+
+        if ($this->startedAt !== null) {
+            $data['started_at'] = $this->startedAt->format(DATE_ATOM);
+        }
+
+        if ($this->completedAt !== null) {
+            $data['completed_at'] = $this->completedAt->format(DATE_ATOM);
+        }
+
+        if ($this->detailsUrl !== '') {
+            $data['details_url'] = $this->detailsUrl;
+        }
+
+        if ($this->externalId !== '') {
+            $data['external_id'] = $this->externalId;
+        }
+
+        if ($this->output !== null) {
+            $data['output'] = $this->output;
+        }
+
+        return $data;
+    }
+}

src/CreateCheckRunRequestFactory.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\GithubApiClient;
+
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\StreamFactoryInterface;
+
+/**
+ * Factory for creating requests to create a Check Run
+ *
+ * Copyright 2026 The Horde Project (http://www.horde.org/)
+ *
+ * See the enclosed file LICENSE for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @category Horde
+ * @package  GithubApiClient
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ */
+class CreateCheckRunRequestFactory
+{
+    public function __construct(
+        private readonly RequestFactoryInterface $requestFactory,
+        private readonly StreamFactoryInterface $streamFactory,
+        private readonly GithubApiConfig $config,
+        private readonly GithubRepository $repo,
+        private readonly CreateCheckRunParams $params
+    ) {}
+
+    /**
+     * Create HTTP request to create a Check Run
+     *
+     * @return RequestInterface
+     */
+    public function create(): RequestInterface
+    {
+        $url = sprintf(
+            'https://api.github.com/repos/%s/%s/check-runs',
+            $this->repo->owner,
+            $this->repo->name
+        );
+
+        $jsonBody = json_encode($this->params->toArray(), JSON_THROW_ON_ERROR);
+        $stream = $this->streamFactory->createStream($jsonBody);
+
+        $request = $this->requestFactory->createRequest('POST', $url);
+        if ($this->config->accessToken !== '') {
+            $request = $request->withHeader('Authorization', 'token ' . $this->config->accessToken);
+        }
+        $request = $request->withHeader('Accept', 'application/vnd.github.v3+json');
+        $request = $request->withHeader('Content-Type', 'application/json');
+        $request = $request->withBody($stream);
+
+        return $request;
+    }
+}

src/CreateLabelParams.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\GithubApiClient;
+
+/**
+ * Data transfer object for creating a repository-level label definition
+ *
+ * Copyright 2026 The Horde Project (http://www.horde.org/)
+ *
+ * See the enclosed file LICENSE for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @category Horde
+ * @package  GithubApiClient
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ */
+class CreateLabelParams
+{
+    /**
+     * @param string $name Label name (required)
+     * @param string $color 6-hex color without leading '#' (required). Not validated here; GitHub rejects malformed values
+     * @param string $description Optional description; emitted only when non-empty
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly string $color,
+        public readonly string $description = ''
+    ) {}
+
+    /**
+     * Convert to array for API request body.
+     *
+     * @return array<string, string>
+     */
+    public function toArray(): array
+    {
+        $data = [
+            'name' => $this->name,
+            'color' => $this->color,
+        ];
+
+        if ($this->description !== '') {
+            $data['description'] = $this->description;
+        }
+
+        return $data;
+    }
+}

src/CreateLabelRequestFactory.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Horde\GithubApiClient;
+
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\StreamFactoryInterface;
+
+/**
+ * Factory for creating requests to create a repository-level label definition
+ *
+ * Copyright 2026 The Horde Project (http://www.horde.org/)
+ *
+ * See the enclosed file LICENSE for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @category Horde
+ * @package  GithubApiClient
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ */
+class CreateLabelRequestFactory
+{
+    public function __construct(
+        private readonly RequestFactoryInterface $requestFactory,
+        private readonly StreamFactoryInterface $streamFactory,
+        private readonly GithubApiConfig $config,
+        private readonly GithubRepository $repo,
+        private readonly CreateLabelParams $params
+    ) {}
+
+    public function create(): RequestInterface
+    {
+        $url = sprintf(
+            'https://api.github.com/repos/%s/%s/labels',
+            $this->repo->owner,
+            $this->repo->name
+        );
+
+        $jsonBody = json_encode($this->params->toArray(), JSON_THROW_ON_ERROR);
+        $stream = $this->streamFactory->createStream($jsonBody);
+
+        $request = $this->requestFactory->createRequest('POST', $url);
+        if ($this->config->accessToken !== '') {
+            $request = $request->withHeader('Authorization', 'token ' . $this->config->accessToken);
+        }
+        $request = $request->withHeader('Accept', 'application/vnd.github.v3+json');
+        $request = $request->withHeader('Content-Type', 'application/json');
+        $request = $request->withBody($stream);
+
+        return $request;
+    }
+}