Looking to hire Laravel developers? Try LaraJobs

laravel-youtrack maintained by e98

Description
Laravel wrapper for the JetBrains YouTrack REST API: create issues, read status and details, comment, search.
Last update
2026/11/18 22:31 (dev-main)
License
Links
Downloads
0

Comments
comments powered by Disqus

e98/laravel-youtrack

Laravel wrapper for the JetBrains YouTrack REST API. Create issues, read their status and details, comment, change state, search and attach files from inside a Laravel application.

  • PHP ^8.2, Laravel 11, 12 and 13
  • Built on Laravel's Http client, so Http::fake() works in your own tests
  • Works with YouTrack Cloud and self-hosted instances (permanent token auth)

Installation

composer require e98/laravel-youtrack

Laravel auto-discovers the service provider and the YouTrack facade.

Local development against a project

Point a project at your working copy instead of the repository (Composer symlinks it):

"repositories": [
    { "type": "path", "url": "../laravel-youtrack" }
]

Configuration

YOUTRACK_BASE_URL=https://youtrack.example.com
YOUTRACK_TOKEN=perm:xxxxxxxx
YOUTRACK_PROJECT=SUP

Create the token in YouTrack under Profile > Account Security > New token. The token's user needs the Create Issue and Read Issue permissions in the target project (plus Update Issue / Add Comment for those calls).

Optional settings (publish the file with php artisan vendor:publish --tag=youtrack-config):

Variable Default Meaning
YOUTRACK_PROJECT none Default project (short name or id) for create()
YOUTRACK_STATE_FIELD State Name of the status field
YOUTRACK_TIMEOUT 15 Seconds
YOUTRACK_RETRIES / YOUTRACK_RETRY_DELAY 2 / 300 GET retries on connection errors and 429/502/503/504. Writes are never retried
YOUTRACK_VERIFY_SSL true Disable only for internal test setups
YOUTRACK_CACHE_TTL 3600 Cache for project short name to id lookups (0 disables)

Check the setup:

php artisan youtrack:ping

Usage

use E98\YouTrack\CustomField;
use E98\YouTrack\Facades\YouTrack;

// Create
$issue = YouTrack::issues()->create(
    summary: 'Checkout fails with 500',
    description: "Steps:\n1. ...",
    project: 'SUP',                       // optional, falls back to YOUTRACK_PROJECT
    customFields: [
        CustomField::enum('Priority', 'Critical'),
        CustomField::enum('Type', 'Bug'),
        CustomField::user('Assignee', 'anna'),
    ],
);

$issue->key;    // "SUP-123"
$issue->url;    // "https://youtrack.example.com/issue/SUP-123"

// Read
$issue = YouTrack::issues()->get('SUP-123');
$issue->state;          // "Open"
$issue->isResolved();   // false
$issue->assignee();     // "anna"
$issue->field('Priority');
$issue->reporter?->login;
$issue->created;        // CarbonImmutable

YouTrack::issues()->state('SUP-123');   // only the status

// Search (YouTrack query language)
$open = YouTrack::issues()->search('project: SUP #Unresolved', limit: 50);

// Change
YouTrack::issues()->changeState('SUP-123', 'In Progress');
YouTrack::issues()->update('SUP-123', ['summary' => 'New title']);
YouTrack::issues()->command('SUP-123', 'for anna State Fixed', comment: 'Done');

// Comments and files
YouTrack::issues()->comment('SUP-123', 'Reproduced on staging.');
YouTrack::issues()->comments('SUP-123');
YouTrack::issues()->attach('SUP-123', storage_path('logs/laravel.log'));

// Projects
YouTrack::projects()->all();
YouTrack::projects()->find('SUP');

YouTrack::issues()->delete('SUP-123');

Notes on command():

  • Prefer changeState() for plain state changes; it sends a typed field value and does not depend on the command parser.
  • Multi-word values are written without braces ('State In Progress'). On a YouTrack with a Hungarian UI the brace form ('State {In Progress}') was rejected with HTTP 400.
  • The command is parsed in the language of the token's user, so error messages may be localized.

You can also inject E98\YouTrack\YouTrackClient instead of using the facade.

Custom fields

YouTrack needs a type for each custom field in a write request. CustomField provides enum, multiEnum, state, user, owned, version, text and simple. Field names and values must match your project's configuration exactly (case included), otherwise YouTrack answers with HTTP 400.

Errors

All exceptions extend E98\YouTrack\Exceptions\YouTrackException:

Exception When
ConfigurationException Missing base URL, token or project
AuthenticationException HTTP 401, invalid or expired token
ForbiddenException HTTP 403, missing permission
NotFoundException HTTP 404, unknown issue or project
ApiException Any other HTTP error (->statusCode, ->body)
YouTrackException Connection failures and other transport errors

The message is taken from YouTrack's error_description when present.

Testing your own code

YouTrack::fake() replaces the client with an in-memory recording fake: nothing is sent over HTTP, no URL or token has to be configured, and the code under test gets the same Issue and Comment objects as in production. It swaps the facade and the container binding, so classes that inject YouTrackClient are covered too.

use E98\YouTrack\Facades\YouTrack;

public function test_a_failed_payment_opens_a_ticket(): void
{
    $fake = YouTrack::fake();

    // ... run the code under test ...

    $fake->assertIssueCreated([
        'summary' => 'Payment failed',
        'project' => 'SUP',
        'fields' => ['Priority' => 'Critical'],
    ]);
    $fake->assertCommented('SUP-12', 'Retried the payment');
    $fake->assertStateChanged('SUP-12', 'In Progress');
}

Issues created through the fake are numbered per project (SUP-1, SUP-2, ...) and start in the state Submitted. Seed issues that already exist in YouTrack, for example the ids your database stores:

YouTrack::fake()
    ->withIssue('SUP-12', ['summary' => 'Old problem', 'state' => 'Open'])
    ->withComment('SUP-12', 'Earlier comment', 'anna')
    ->withProject('SUP', 'Support');

Assertions: assertIssueCreated() (array or closure), assertIssueCreatedTimes(), assertNoIssueCreated(), assertCommented(), assertNothingCommented(), assertStateChanged(), assertUpdated(), assertCommandSent(), assertAttached(), assertDeleted() and assertNothingSent() (reads count as well). recorded('comment') returns the raw calls if you need your own checks.

What the fake does not do:

  • search() is a plain, case-insensitive text match on id, summary and description; YouTrack's query language is not interpreted. Use searchUsing(fn (string $query, int $limit, int $skip) => [...]) to answer a specific query.
  • command() is recorded but has no effect on the stored issue.
  • Reading or changing an issue that was neither created nor seeded throws NotFoundException, with a hint to seed it.
  • The raw client methods (get, post, request, upload) throw, so a test cannot reach a real server by accident.
  • The fake is no substitute for the live check: field names, state values and permissions are only validated by a real YouTrack.

If you prefer to fake the HTTP layer instead, Http::fake() works as well, since all requests go through Laravel's HTTP client:

Http::fake([
    'youtrack.example.com/api/issues*' => Http::response([
        'id' => '2-45', 'idReadable' => 'SUP-1', 'summary' => 'x',
    ]),
]);

Development

composer install
composer test

Tests use Orchestra Testbench and Http::fake(), so no YouTrack instance is needed.

Release

git tag v0.1.1
git push origin v0.1.1

Composer resolves versions from git tags (semantic versioning). Packagist picks up new tags through the GitHub webhook; consumers then run composer update e98/laravel-youtrack.

License

MIT. See LICENSE.