masterarrow / laravel-jira-rest-client
The aim of the package is to make it easier to communicate with the Jira
Requires
- php: >=5.6.4
- ext-json: *
- guzzlehttp/guzzle: ^6.0|^7.0
- laravel/framework: *
- mrjoops/oauth2-jira: ^0.3.0
Suggests
- salsify/json-streaming-parser: Require this when you want to parse the response in blocks
This package is auto-updated.
Last update: 2025-03-02 08:24:39 UTC
README
Perform various operations of Jira APIs with Laravel 5.4+
The aim of the package is to make it easier to communicate with the API. By default the response from the request is not altered in any way. By creating your own implementation or by using the simple helpers provided with the package you are able to integrate Jira the way you like.
Installation
To get the latest version of laravel-jira-rest-client
, run the following command
composer require masterarrow/laravel-jira-rest-client
Do note that not all methods have been implemented yet.
Laravel 5.5 uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider.
Laravel 5.4:
If you don't use auto-discovery, add the ServiceProvider to the providers array in config/app.php
<?php 'providers' => [ // ... Atlassian\JiraRest\JiraRestServiceProvider::class, ],
Also locate the Aliases
key in your config/app.php
file and register the Facade:
<?php 'aliases' => [ // ... 'Jira' => Atlassian\JiraRest\Facades\Jira::class, ],
Copy the package config to your local config with the publish command:
php artisan vendor:publish --provider="Atlassian\JiraRest\JiraRestServiceProvider"
Update the .env with your proper credentials using JIRA variables from config/atlassian/jira.php
.
Usage
The core of this package is a direct reflection of the Jira API mean that all request classes don't format the response you get from the API. This desicion was made so the package is more versitile allowing users to handle the response of the requests to their own wishes.
For example, to fetch a specific issue you could do the following
<?php $request = new \Atlassian\JiraRest\Requests\Issue\IssueRequest; $response = $request->get('ISSUE-3'); // Array
Parameters
Sending parameter with requests is possible via two ways
- Using an array
- Creating a class that implements
\Illuminate\Contracts\Support\Arrayable
When using an array you can create a request like so:
<?php use Atlassian\JiraRest\Requests\Project; /** @var \Atlassian\JiraRest\Requests\Project\ProjectRequest $request */ $request = app(Project\ProjectRequest::class); $response = $request->search([ 'maxResults' => 10, 'startAt' => 0 ]); $output = \json_decode($response->getBody()->getContents(), true);
You can opt for creating a class implementing \Illuminate\Contracts\Support\Arrayable
, the toArray
method will return the parameters for the request.
Or you could extend \Atlassian\JiraRest\Requests\AbstractParameters
so you can 'fill' or 'override' the parameters set within the class.
Using a class can be usefull when doing requests in multiple places to make sure the same values are requests every time.
Authentication
So Jira allows for multiple ways of authentication. By default this is basic auth.
Basic Auth
To use basic auth, you need to add the following to your .env
JIRA_USER=
JIRA_PASS=
Where the credentials are the same as the user you are logging in.
If you wish have each user be identified by their own credentials you need to set these in the config on runtime
<?php config('atlassian.jira.auth.basic.username', 'info@example.com'); config('atlassian.jira.auth.basic.password', 'secret');
Session
Another implementation is session, but that is not (yet) implemented by this package.
OAuth
_To use OAuth 2.0 you need to add to your .env file:
JIRA_HOST=https://api.atlassian.com/ex/jira/
JIRA_AUTHENTICATION=oauth2
To authenticate user:
$url = 'https://yuor-web-site/callback-url';
$scopes = ['read:jira-user', 'read:jira-work', ...];
// $clientId and $secret you can get from .env file
$auth = new OAuthHandler($clientId, $secret, $url, $user-unique-identifier, $scopes);
$auth->authenticate();
After that user user will be automaticaly redirected to Jira for authentication.
In you callback-url
route:
$params = $request->only('state', 'code');
$data = $this->authHandler->getAccessTokens($params);
// $data['cloudId']);
// $data['accessToken']);
// $data['refreshToken']);
// $data['expires']);
Get issue with OAuth 2.0:
$response = $auth->issue()->->get('ISSUE-3');
Refresh access token:
$data = $auth->refreshAccessTokens($clientId, $secret, $refreshToken);
// $data['accessToken']);
// $data['refreshToken']);
// $data['expires']);
Helpers (deprecated)
Now because for the most part you don't want to spend time writing the requests yourself there are some useful helpers to get you communicating with the api.
To fetch a single issue you can use the following code:
$issue = jira()->issue('ISSUE-3')->get();
Or use the facade if you prefer:
$issue = \Jira::issue('ISSUE-3')->get();
deprecating most helpers because writing helpers for all classes is too much maintenance
Middleware
To alter the Guzzle Client used for requests you can add 'middleware' to alter the options.
There are multiple ways to add middleware.
Using the config
You can set one or more middleware using the client_options
array in the config config/atlassian/jira.php
For example:
<?php 'client_options' => [ 'auth' => \App\Services\Jira\Middleware\LogRequestMiddleware::class, ],
These can be named or just a value
Using the addMiddleware
method
When you have an AbstractRequest
instance you can add multiple middleware by calling addMiddlware
like so:
<?php use Atlassian\JiraRest\Requests; /** @var \Atlassian\JiraRest\Requests\ServerInfoRequest $request */ $request = app(Requests\ServerInfoRequest::class); $request->addMiddleware(\App\Services\Jira\Middleware\LogRequestMiddleware::class);
Impersonation
To impersonate a user through Jira requests you must set JIRA_IMPERSONATE=true
in your .env file.
Once impersonation is enabled, Laravel will use the authentificated users' name
by default.
However, it's also possible to impersonate a user manually by sending a user's name to constructor of the middleware. To do this you would need to manually register the middleware and pass the user.