README

This package provides a very basic, convenient, and unified wrapper for Microsoft Azure DevOps.

Table of Contents

• Installation
• Usage
• Examples
• Tests
• Changelog
• Contributing
• Credits
• License

Installation

To install the client you need to require the package using composer:

$ composer require testmonitor/devops-client

Use composer's autoload:

require __DIR__.'/../vendor/autoload.php';

You're all set up now!

Usage

This client only supports oAuth authentication. You'll need an Microsoft Entra ID OAuth app to proceed. If you haven't done so, please read up with the Azure DevOps authentication docs on how to create an application and set the correct permissions.

When your OAuth app is up and running, start with the oAuth authorization:

$oauth = [
    'clientId' => '12345',
    'clientSecret' => 'abcdef',
    'appId' => '12345',
    'redirectUrl' => 'https://redirect.myapp.com/',
];

$devops = new \TestMonitor\DevOps\Client($oauth);

header('Location: ' . $devops->authorizationUrl());
exit();

This will redirect the user to a page asking confirmation for your app getting access to Azure DevOps. Make sure your redirectUrl points back to your app. This URL should point to the following code:

$oauth = [
    'clientId' => '12345',
    'clientSecret' => 'abcdef',
    'appId' => '12345',
    'redirectUrl' => 'https://redirect.myapp.com/',
];

$devops = new \TestMonitor\DevOps\Client($oauth);

$token = $devops->fetchToken($_REQUEST['code']);

When everything went ok, you should have an access token (available through Token object). It will be valid for one hour. After that, you'll have to refresh the token to regain access:

$oauth = ['clientId' => '12345', 'clientSecret' => 'abcdef', 'appId' => '12345', 'redirectUrl' => 'https://redirect.myapp.com/'];
$token = new \TestMonitor\DevOps\AccessToken('eyJ0...', '0/34ccc...', 1574601877); // the token you got last time
$organization = 'MyOrg';

$devops = new \TestMonitor\DevOps\Client($oauth, $organization, $token);

if ($token->expired()) {
    $newToken = $devops->refreshToken();
}

The new token will be valid again for the next hour.

Examples

Retrieve a list of Azure DevOps accounts:

$accounts = $devops->accounts();

Retrieve a paginated list of work items for a project:

$workItems = $devops->workitems('12345');

foreach ($workItems->items() as $workItem) {
    echo $workItem->title;
}

echo $workItems->total() . ' work items found';

Note: total() is capped by $wiqlLimit (default: 1000). Raise it if you expect more results.

Use a WIQL query to filter results, and control pagination and the number of results fetched:

$query = (new \TestMonitor\DevOps\Builders\WIQL\WIQL)
    ->where(\TestMonitor\DevOps\Builders\WIQL\Field::STATE, \TestMonitor\DevOps\Builders\WIQL\Operator::EQUALS, 'New');

$workItems = $devops->workitems(
    projectId: '12345',
    query: $query,
    limit: 25,
    offset: 50,
    wiqlLimit: 5000
);

Create a work item using a work item type 'Bug' and example project with id 12345:

$workItem = $devops->createWorkItem(new \TestMonitor\DevOps\Resources\WorkItem([
    'title' => 'Summary of the item',
    'description' => 'Some description',
    'workItemType' => 'Bug',
    'stepsToReproduce' => 'Repro steps',
]), '12345');

Tests

The package contains integration tests. You can run them using PHPUnit.

$ vendor/bin/phpunit

Changelog

Refer to CHANGELOG for more information.

Contributing

Refer to CONTRIBUTING for contributing details.

Credits

• Thijs Kok - Lead developer - ThijsKok
• Stephan Grootveld - Developer - Stefanius
• Frank Keulen - Developer - FrankIsGek
• Muriel Nooder - Developer - ThaNoodle

License

The MIT License (MIT). Refer to the License for more information.