README.md

Laravel YouTrack SDK

Introduction

Laravel wrapper for the PHP YouTrack SDK library provides set of tools to interact with JetBrains YouTrack Issue Tracking and Project Management software.

Contents

• Features
• Requirements
• Installation
• Configuration
  • YouTrack URL
  • Authorization methods
• Usage
  • Initialize API client
  • API requests
  • API responses
• Changelog
• Contributing
• Testing
• Security
• Contributors
• Alternatives
• License
• About CyberCog

Features

• Using contracts to keep high customization capabilities.
• Multiple authorization strategies: Token, Cookie.
• Following PHP Standard Recommendations:
  • PSR-1 (Basic Coding Standard).
  • PSR-2 (Coding Style Guide).
  • PSR-4 (Autoloading Standard).
  • PSR-7 (HTTP Message Interface).
• Covered with unit tests.

Requirements

• YouTrack >= 3.0 with REST-API enabled (always enabled, by default)
• PHP >= 8.1
• Guzzle HTTP Client >= 7.0
• Laravel >= 5.1.20

Installation

The preferred method is via composer. Follow the installation instructions if you do not already have composer installed.

Once composer is installed, execute the following command in your project root to install this library:

composer require cybercog/laravel-youtrack-sdk

Configuration

Laravel YouTrack SDK designed to work with default config, but it always could be modified. First of all publish it:

php artisan vendor:publish --tag="youtrack-config"

This will create a config/youtrack.php file in your app that you can modify to set your configuration. Also, make sure you check for changes to the original config file in this package between releases.

YouTrack URL

YouTrack instance location could be defined in .env file:

YOUTRACK_BASE_URI=https://youtrack.custom.domain

Authorization methods

Starting with YouTrack 2017.1 release authorization based on permanent tokens is recommended as the main approach for the authorization in your REST API calls.

By default Token authorization will be used. You could redefine it in .env file:

Token authorization

YOUTRACK_AUTH=token
YOUTRACK_TOKEN=your-permanents-token

Cookie authorization

YOUTRACK_AUTH=cookie
YOUTRACK_USERNAME=username
YOUTRACK_PASSWORD=secret

Usage

Initialize API client

$youtrack = app(\Cog\Contracts\YouTrack\Rest\Client\Client::class);

As result instantiated \Cog\YouTrack\Rest\Client\YouTrackClient class should be returned.

API requests

HTTP request

$method = 'POST'; // GET, POST, PUT, DELETE, PATCH or any custom ones
$response = $youtrack->request($method, '/issue', [
    'project' => 'TEST',
    'summary' => 'New test issue',
    'description' => 'Test description',
]);

You can customize requests created and transferred by a client using request options. Request options control various aspects of a request including, headers, query string parameters, timeout settings, the body of a request, and much more.

$options = [
    'debug' => true,
    'sink' => '/path/to/dump/file',
];
$response = $youtrack->request('POST', '/issue', [
    'project' => 'TEST',
    'summary' => 'New test issue',
    'description' => 'Test description',
], $options);

HTTP GET request

$response = $youtrack->get('/issue/TEST-1');

HTTP POST request

$response = $youtrack->post('/issue', [
    'project' => 'TEST',
    'summary' => 'New test issue',
    'description' => 'Test description',
]);

HTTP PUT request

$response = $youtrack->put('/issue/TEST-1', [
    'summary' => 'Updated summary',
    'description' => 'Updated description',
]);

HTTP DELETE request

$response = $youtrack->delete('/issue/TEST-1');

API responses

Each successful request to the API returns instance of \Cog\Contracts\YouTrack\Rest\Response\Response contract. By default it's \Cog\YouTrack\Rest\Response\YouTrackResponse class.

Get PSR HTTP response

PSR HTTP response could be accessed by calling httpResponse method on API Response.

$youtrackResponse = $youtrack->get('/issue/TEST-1');
$psrResponse = $youtrackResponse->httpResponse();

Get response Cookie

Returns Set-Cookie headers as string from the HTTP response.

$apiResponse = $youtrack->get('/issue/TEST-1');
$cookieString = $apiResponse->cookie();

Get response Location

Returns Location header from the HTTP response.

$apiResponse = $youtrack->get('/issue/TEST-1');
$location = $apiResponse->location();

Transform response to array

$apiResponse = $youtrack->get('/issue/TEST-1');
$location = $apiResponse->toArray();

Get HTTP response status code

$apiResponse = $youtrack->get('/issue/TEST-1');
$location = $apiResponse->statusCode();

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Testing

Run the tests with:

vendor/bin/phpunit

Security

If you discover any security related issues, please email open@cybercog.su instead of using the issue tracker.

Contributors

Anton Komarev	sergiy-petrov

Laravel YouTrack SDK contributors list

Alternatives

Alternatives not found.

Feel free to add more alternatives as Pull Request.

License

• Laravel YouTrack SDK package is open-sourced software licensed under the MIT License by Anton Komarev.

About CyberCog

CyberCog is a Social Unity of enthusiasts. Research best solutions in product & software development is our passion.

• Follow us on Twitter
• Read our articles on Medium