stichoza/jira-webhooks-data

PHP classes for Atlassian Jira webhook data structures

v5.0.4 2023-07-24 23:10 UTC

Requires

• php: ^8.2
• ext-mbstring: *

Requires (Dev)

• fzaninotto/faker: ^1.9.1
• phpunit/phpunit: ^10.1

Unlicense

• Levan Velijanashvili
• Chewbacca

• reflection
• jira
• atlassian
• webhook

README

This is PHP library for processing and handling Atlassian Jira webhook data.

If you're looking for the Laravel package with events and routes, check out stichoza/jira-webhooks-laravel package that includes this package as data structures.

Note: This package was originally forked from kommuna/jirawebhook which is meant to be used with the kommuna/vicky and has support of League events and message converters. This package, on the other hand, is a separate package because the whole structure is rewritten to the point that it's no longer compatible with the original repo. Kudos to the developers of the original package!

Installation

Install this package via Composer:

composer require stichoza/jira-webhook-data

Usage

// Example payload received from Jira webhook
$data = [
    "timestamp" => 1629835026055,
    "webhookEvent" => "jira:issue_updated",
    // ... other webhook data ...
    "issue" => [
        // ... issue data ...
    ],
    "changelog" => [
        // ... changelog data ...
    ],
    // ... other data ...
];

Create an instance of JiraWebhookData:

use Stichoza\JiraWebhooksData\Models\JiraWebhookData;

$webhookData = new JiraWebhookData($data);

Now you can access the parsed data from the webhook:

$message = 'New comment by ' . $webhookData->comment->author->displayName
    . ' on issue ' . $webhookData->issue->key;
    . ': ' . $webhookData->comment->body;

More properties listed below:

$timestamp = $webhookData->timestamp;
$webhookEvent = $webhookData->webhookEvent;
$issueEvent = $webhookData->issueEvent;
$user = $webhookData->user; // JiraUser instance
$issue = $webhookData->issue; // JiraIssue instance
$changelog = $webhookData->changelog; // JiraChangelog instance
$worklog = $webhookData->worklog; // JiraWorklog instance

Access specific properties from the JiraIssue instance

$issueId = $issue->id;
$issueKey = $issue->key;
$issueTypeName = $issue->issueTypeName;
$priorityName = $issue->priorityName;

Access specific properties from the JiraUser instance

if ($user) {
    $userAccountId = $user->accountId;
    $userDisplayName = $user->displayName;
    // ... and other properties ...
}

Access specific properties from the JiraChangelog instance

$changelogId = $changelog->id;
$changelogItems = $changelog->items; // Array of JiraChangelogItem instances
// ... and other properties ...

You can also perform additional checks or operations based on the parsed data

if ($issue && $issue->isStatusResolved()) {
    // Do something for resolved issues
}

if ($user && $user->active) {
    // Do something for active users
}

Read more about properties and methods in the src/Models folder.

Error Handling

Object constructors will throw a Stichoza\JiraWebhooksData\Exceptions\JiraWebhookDataException exception when incorrect or insufficient data is provided. Make sure you wrap your code in try-catch block.

use Stichoza\JiraWebhooksData\Models\JiraWebhookData;
use Stichoza\JiraWebhooksData\Exceptions\JiraWebhookDataException;

try {
    $webhookData = new JiraWebhookData($data);
} catch (JiraWebhookDataException $e) {
    // Handle the error
}

Also keep in mind that certain properties will not be present in response depending on the Jira event. Make sure you check that objects/properties are not null.

$to = $webhookData->issue?->assignee?->email;

if ($to !== null) {
    // Do something
}