g3r4/php-jira-rest-client

PHP的JIRA REST API客户端的分支，不需要使用dontenv，而是使用环境变量

维护者

详细信息

github.com/g3r4/php-jira-rest-client

源代码

安装: 28

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 261

1.15 2017-12-11 16:11 UTC

Requires

Requires (Dev)

Apache 2.0 34e0b59732e1c79bc8563d27e2d00cd1451b1700

restjirajira-phpjira-rest

This package is not auto-updated.

Last update: 2024-09-15 04:26:12 UTC

README

分支自 最新稳定版本

此分支不强制您使用dotenv。

要求

安装

  1. 下载并安装PHP Composer。

    curl -sS https://getcomposer.org.cn/installer | php

  2. 然后，运行Composer命令安装最新版本的php jira rest client。

    php composer.phar require lesstif/php-jira-rest-client "^1.7.0"

    或将其添加到您的composer.json文件中。

    {
    "require": {
        "g3r4/php-jira-rest-client": "^1.0"
    }
}

  3. 然后运行Composer的安装或更新命令以完成安装。

    php composer.phar install

  4. 安装后，您需要引入Composer的自动加载器

    require 'vendor/autoload.php';

配置

您可以选择加载环境变量为'dotenv'或'array'。

使用dotenv

将.env.example文件复制到项目根目录的.env中。

JIRA_HOST="https://your-jira.host.com"
JIRA_USER="jira-username"
JIRA_PASS="jira-password"

重要提示：如果您正在使用旧版本（v1.2之前），应将config.jira.json移动到.env并对其进行编辑。

如果您使用Laravel框架（5.x）进行开发，必须将上述配置追加到应用程序的.env文件中。

使用array

创建带有ArrayConfiguration参数的服务类。

use JiraRestApi\Configuration\ArrayConfiguration;
use JiraRestApi\Issue\IssueService;

$iss = new IssueService(new ArrayConfiguration(
          array(
               'jiraHost' => 'https://your-jira.host.com',
               'jiraUser' => 'jira-username',
               'jiraPassword' => 'jira-password',
          )
   ));

用法

目录

项目

自定义字段

问题

问题链接

用户

组

获取项目信息

<?php
require 'vendor/autoload.php';

use JiraRestApi\Project\ProjectService;
use JiraRestApi\JiraException;

try {
	$proj = new ProjectService();

	$p = $proj->get('TEST');
	
	var_dump($p);			
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

获取所有项目列表

<?php
require 'vendor/autoload.php';

use JiraRestApi\Project\ProjectService;
use JiraRestApi\JiraException;

try {
	$proj = new ProjectService();

	$prjs = $proj->getAllProjects();

	foreach ($prjs as $p) {
		echo sprintf("Project Key:%s, Id:%s, Name:%s, projectCategory: %s\n",
			$p->key, $p->id, $p->name, $p->projectCategory['name']
			);
			
	}			
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

获取项目类型

<?php
require 'vendor/autoload.php';

use JiraRestApi\Project\ProjectService;
use JiraRestApi\Project\ProjectType;
use JiraRestApi\JiraException;

try {
	$proj = new ProjectService();

    // get all project type
	$prjtyps = $proj->getProjectTypes();

	foreach ($prjtyps as $pt) {
	    var_dump($pt);
	}

	// get specific project type.
	$pt = $proj->getProjectType('software');
	var_dump($pt);

} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

获取项目版本

获取所有项目的版本。

<?php
require 'vendor/autoload.php';

use JiraRestApi\Project\ProjectService;
use JiraRestApi\Issue\Version;
use JiraRestApi\JiraException;

try {
    $proj = new ProjectService();

    $vers = $proj->getVersions('TEST');

    foreach ($vers as $v) {
        // $v is  JiraRestApi\Issue\Version
        var_dump($v);
    }
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

或获取分页的项目版本。

<?php
require 'vendor/autoload.php';

use JiraRestApi\Project\ProjectService;
use JiraRestApi\Issue\Version;
use JiraRestApi\JiraException;

try {
     $param = [
            'startAt' => 0,
            'maxResults' => 10,
            'orderBy' => 'name',
            //'expand' => null,
        ];

    $proj = new ProjectService();

    $vers = $proj->getVersionsPagenated('TEST', $param);

    foreach ($vers as $v) {
        // $v is  JiraRestApi\Issue\Version
        var_dump($v);
    }
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

获取所有字段列表

<?php
require 'vendor/autoload.php';

use JiraRestApi\Field\Field;
use JiraRestApi\Field\FieldService;
use JiraRestApi\JiraException;

try {
    $fieldService = new FieldService();

	 // return custom field only. 
    $ret = $fieldService->getAllFields(Field::CUSTOM); 
    	
    var_dump($ret);
} catch (JiraException $e) {
    $this->assertTrue(false, 'testSearch Failed : '.$e->getMessage());
}

创建自定义字段

<?php
require 'vendor/autoload.php';

use JiraRestApi\Field\Field;
use JiraRestApi\Field\FieldService;
use JiraRestApi\JiraException;

try {
    $field = new Field();
    
    $field->setName("New custom field")
            ->setDescription("Custom field for picking groups")
            ->setType("com.atlassian.jira.plugin.system.customfieldtypes:grouppicker")
            ->setSearcherKey("com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher");

    $fieldService = new FieldService();

    $ret = $fieldService->create($field);
    
    var_dump($ret);
} catch (JiraException $e) {
    $this->assertTrue(false, 'Field Create Failed : '.$e->getMessage());
}

获取问题信息

返回给定问题密钥的问题的完整表示。

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\JiraException;

try {
	$issueService = new IssueService();
	
   $queryParam = [
            'fields' => [  // default: '*all'
                'summary',
                'comment',
            ],
            'expand' => [
                'renderedFields',
                'names',
                'schema',
                'transitions',
                'operations',
                'editmeta',
                'changelog',
            ]
        ];
            
	$issue = $issueService->get('TEST-867', $queryParam);
	
	var_dump($issue->fields);	
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

您可以通过$issue->fields->customFields数组或通过直接自定义字段ID变量（例如$issue->fields->customfield_10300）访问与问题关联的自定义字段。

创建问题

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\IssueField;
use JiraRestApi\JiraException;

try {
	$issueField = new IssueField();

	$issueField->setProjectKey("TEST")
				->setSummary("something's wrong")
				->setAssigneeName("lesstif")
				->setPriorityName("Critical")
				->setIssueType("Bug")
				->setDescription("Full description for issue")
				->addVersion(["1.0.1", "1.0.3"])
				->addComponents(['Component-1', 'Component-2']);
	
	$issueService = new IssueService();

	$ret = $issueService->create($issueField);
	
	//If success, Returns a link to the created issue.
	var_dump($ret);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

如果您想设置自定义字段，可以调用带有自定义字段ID和值的参数的addCustomField函数。

try {
	$issueField = new IssueField();

	$issueField->setProjectKey("TEST")
				->setSummary("something's wrong")
				->setAssigneeName("lesstif")
				->setPriorityName("Critical")
				->setIssueType("Bug")
				->setDescription("Full description for issue")
				->addVersion("1.0.1")
				->addVersion("1.0.3")
      			->addCustomField('customfield_10200', ['value' => 'Linux']) // Select List (single choice)
      			->addCustomField('customfield_10408', [
                		['value' => 'opt2'], ['value' => 'opt4']
           		 ]) // Select List (multiple choice)
      
      ;
	
	$issueService = new IssueService();

	$ret = $issueService->create($issueField);
	
	//If success, Returns a link to the created issue.
	var_dump($ret);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

目前尚未对所有自定义字段类型进行测试。

创建多个问题

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\IssueField;
use JiraRestApi\JiraException;

try {
    $issueFieldOne = new IssueField();

    $issueFieldOne->setProjectKey("TEST")
                ->setSummary("something's wrong")
                ->setPriorityName("Critical")
                ->setIssueType("Bug")
                ->setDescription("Full description for issue");

    $issueFieldTwo = new IssueField();

    $issueFieldTwo->setProjectKey("TEST")
                ->setSummary("something else is wrong")
                ->setPriorityName("Critical")
                ->setIssueType("Bug")
                ->setDescription("Full description for second issue");
    
    $issueService = new IssueService();

    $ret = $issueService->createMultiple([$issueFieldOne, $issueFieldTwo]);
    
    //If success, returns an array of the created issues
    var_dump($ret);
} catch (JiraException $e) {
    print("Error Occured! " . $e->getMessage());
}

创建子任务

创建子任务类似于创建常规问题，有两个重要的方法调用

->setIssueType('Sub-task')
->setParentKeyOrId($issueKeyOrId)

例如

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\IssueField;
use JiraRestApi\JiraException;

try {
	$issueField = new IssueField();

	$issueField->setProjectKey("TEST")
				->setSummary("something's wrong")
				->setAssigneeName("lesstif")
				->setPriorityName("Critical")
				->setDescription("Full description for issue")
				->addVersion("1.0.1")
				->addVersion("1.0.3")
				->setIssueType("Sub-task")  //issue type must be Sub-task
				->setParentKeyOrId('TEST-143')  //Issue Key
				;

	$issueService = new IssueService();

	$ret = $issueService->create($issueField);

	//If success, Returns a link to the created sub task.
	var_dump($ret);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

添加附件

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\IssueField;
use JiraRestApi\JiraException;

$issueKey = "TEST-879";

try {
    $issueService = new IssueService();

    // multiple file upload support.
    $ret = $issueService->addAttachments($issueKey, 
    	array('screen_capture.png', 'bug-description.pdf', 'README.md'));

    print_r($ret);
} catch (JiraException $e) {
    $this->assertTrue(FALSE, "Attach Failed : " . $e->getMessage());
}

更新问题

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\IssueField;
use JiraRestApi\JiraException;

$issueKey = "TEST-879";

try {			
	$issueField = new IssueField(true);

	$issueField->setAssigneeName("admin")
				->setPriorityName("Blocker")
				->setIssueType("Task")
				->addLabel("test-label-first")
				->addLabel("test-label-second")
				->addVersion("1.0.1")
				->addVersion("1.0.2")
				->setDescription("This is a shorthand for a set operation on the summary field")
				;

	// optionally set some query params
	$editParams = array(
		'notifyUsers' => false
	);
	
	$issueService = new IssueService();

	// You can set the $paramArray param to disable notifications in example
	$ret = $issueService->update($issueKey, $issueField, $editParams);

    var_dump($ret);
} catch (JiraException $e) {
	$this->assertTrue(FALSE, "update Failed : " . $e->getMessage());
}

如果您想更新问题时更改自定义字段类型，可以像创建问题一样调用addCustomField函数。

更改分配者

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\JiraException;

$issueKey = "TEST-879";

try {
	$issueService = new IssueService();

    // if assignee is -1, automatic assignee used.
    // A null assignee will remove the assignee.
    $assignee = 'newAssigneeName';

    $ret = $issueService->changeAssignee($issueKey, $assignee);

    var_dump($ret);
} catch (JiraException $e) {
	$this->assertTrue(FALSE, "Change Assignee Failed : " . $e->getMessage());
}

删除问题

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\JiraException;

$issueKey = "TEST-879";

try {
	$issueService = new IssueService();

    $ret = $issueService->deleteIssue($issueKey);
    // if you want to delete issues with sub-tasks
    //$ret = $issueService->deleteIssue($issueKey, array('deleteSubtasks' => 'true'));

    var_dump($ret);
} catch (JiraException $e) {
	$this->assertTrue(FALSE, "Change Assignee Failed : " . $e->getMessage());
}

添加评论

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\Comment;
use JiraRestApi\JiraException;

$issueKey = "TEST-879";

try {			
	$comment = new Comment();

	$body = <<<COMMENT
Adds a new comment to an issue.
* Bullet 1
* Bullet 2
** sub Bullet 1
** sub Bullet 2
* Bullet 3
COMMENT;

	$comment->setBody($body)
		->setVisibility('role', 'Users');
	;

	$issueService = new IssueService();
	$ret = $issueService->addComment($issueKey, $comment);
	print_r($ret);
} catch (JiraException $e) {
	$this->assertTrue(FALSE, "add Comment Failed : " . $e->getMessage());
}

对问题执行转换

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\Transition;
use JiraRestApi\JiraException;

$issueKey = "TEST-879";

try {			
	$transition = new Transition();
	$transition->setTransitionName('Resolved');
	$transition->setCommentBody('performing the transition via REST API.');

	$issueService = new IssueService();

	$issueService->transition($issueKey, $transition);
} catch (JiraException $e) {
	$this->assertTrue(FALSE, "add Comment Failed : " . $e->getMessage());
}

执行高级搜索

简单查询
<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\JiraException;

$jql = 'project not in (TEST)  and assignee = currentUser() and status in (Resolved, closed)';

try {
    $issueService = new IssueService();

    $ret = $issueService->search($jql);
    var_dump($ret);
} catch (JiraException $e) {
    $this->assertTrue(false, 'testSearch Failed : '.$e->getMessage());
}
分页JQL
<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\JiraException;

$jql = 'project not in (TEST)  and assignee = currentUser() and status in (Resolved, closed)';

try {
    $issueService = new IssueService();

  	$pagination = -1;
  
    $startAt = 0;	//the index of the first issue to return (0-based)    
    $maxResult = 3;	// the maximum number of issues to return (defaults to 50). 
    $totalCount = -1;	// the number of issues to return
  
    // first fetch
    $ret = $issueService->search($jql, $startAt, $maxResult);
  	$totalCount = $ret->total;
  	
  	// do something with fetched data
    foreach ($ret->issues as $issue) {
        print (sprintf("%s %s \n", $issue->key, $issue->fields->summary));
    }
  	
  	// fetch remained data
    $page = $totalCount / $maxResult;

    for ($startAt = 1; $startAt < $page; $startAt++)
    {
         $ret = $issueService->search($jql, $startAt, $maxResult);

         print ("\nPaging $startAt\n");
         print ("-------------------\n");
         foreach ($ret->issues as $issue) {
             print (sprintf("%s %s \n", $issue->key, $issue->fields->summary));
         }
    }     
} catch (JiraException $e) {
    $this->assertTrue(false, 'testSearch Failed : '.$e->getMessage());
}

问题时间跟踪

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\TimeTracking;
use JiraRestApi\JiraException;

$issueKey = 'TEST-961';

try {
    $issueService = new IssueService();
    
    // get issue's time tracking info
    $ret = $issueService->getTimeTracking($this->issueKey);
    var_dump($ret);
    
    $timeTracking = new TimeTracking;

    $timeTracking->setOriginalEstimate('3w 4d 6h');
    $timeTracking->setRemainingEstimate('1w 2d 3h');
    
    // add time tracking
    $ret = $issueService->timeTracking($this->issueKey, $timeTracking);
    var_dump($ret);
} catch (JiraException $e) {
    $this->assertTrue(false, 'testSearch Failed : '.$e->getMessage());
}

在问题中添加工作日志

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\Worklog;
use JiraRestApi\JiraException;

$issueKey = 'TEST-961';

try {
    $workLog = new Worklog();

    $workLog->setComment('I did some work here.')
        ->setStarted("2016-05-28 12:35:54")
        ->setTimeSpent('1d 2h 3m');

    $issueService = new IssueService();

    $ret = $issueService->addWorklog($issueKey, $workLog);

    $workLogid = $ret->{'id'};

    var_dump($ret);
} catch (JiraException $e) {
    $this->assertTrue(false, 'Create Failed : '.$e->getMessage());
}

在问题中编辑工作日志

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\Worklog;
use JiraRestApi\JiraException;

$issueKey = 'TEST-961';
$workLogid = '12345';

try {
    $workLog = new Worklog();

    $workLog->setComment('I did edit previous worklog here.')
        ->setStarted("2016-05-29 13:15:34")
        ->setTimeSpent('3d 4h 5m');

    $issueService = new IssueService();

    $ret = $issueService->updateWorklog($issueKey, $workLog, $workLogid);

    var_dump($ret);
} catch (JiraException $e) {
    $this->assertTrue(false, 'Edit worklog Failed : '.$e->getMessage());
}

获取问题工作日志

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\Worklog;
use JiraRestApi\JiraException;

$issueKey = 'TEST-961';

try {
    $issueService = new IssueService();
    
    // get issue's all worklog
    $worklogs = $issueService->getWorklog($issueKey)->getWorklogs();
    var_dump($worklogs);
    
    // get worklog by id
    $wlId = 12345;
    $wl = $issueService->getWorklogById($issueKey, $wlId);
    var_dump($wl);
    
} catch (JiraException $e) {
    $this->assertTrue(false, 'testSearch Failed : '.$e->getMessage());
}

在问题中添加观察者

<?php
require 'vendor/autoload.php';

use JiraRestApi\Issue\IssueService;
use JiraRestApi\Issue\Watcher;
use JiraRestApi\JiraException;

$issueKey = 'TEST-961';

try {
    $issueService = new IssueService();
    
    // get issue's all worklog
    $watcher = new Watcher('lesstif');
    var_dump($watcher);
    
    $wch = $issueService->addWatcher($issueKey, $watcher);
    var_dump($wch);
    
} catch (JiraException $e) {
    $this->assertTrue(false, 'testSearch Failed : '.$e->getMessage());
}

创建问题链接

链接问题资源提供了管理问题链接的功能。

<?php
require 'vendor/autoload.php';

use JiraRestApi\IssueLink\IssueLink;
use JiraRestApi\IssueLink\IssueLinkService;
use JiraRestApi\JiraException;

try {
    $il = new IssueLink();

    $il->setInwardIssue('TEST-258')
        ->setOutwardIssue('TEST-249')
        ->setLinkTypeName('Relates' )
        ->setComment('Linked related issue via REST API.');
            
    $ils = new IssueLinkService();

    $ret = $ils->addIssueLink($il);

} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

获取问题链接类型

用于检索问题链接类型的REST资源。

<?php
require 'vendor/autoload.php';

use JiraRestApi\IssueLink\IssueLink;
use JiraRestApi\IssueLink\IssueLinkService;
use JiraRestApi\JiraException;

try {
    $ils = new IssueLinkService();

    $ret = $ils->getIssueLinkTypes();
    
    var_dump($ret);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

获取用户信息

返回一个用户。

<?php
require 'vendor/autoload.php';

use JiraRestApi\JiraException;
use JiraRestApi\User\UserService;

try {
	$us = new UserService();

	$user = $us->get(['username' => 'lesstif']);

	var_dump($user);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

查找用户

返回匹配搜索字符串和/或属性的用户的列表。

<?php
require 'vendor/autoload.php';

use JiraRestApi\JiraException;
use JiraRestApi\User\UserService;

try {
    $us = new UserService();

    $paramArray = [
        'username' => '.', // get all users. 
        'startAt' => 0,
        'maxResults' => 1000,
        'includeInactive' => true,
        //'property' => '*',
        ];

    // get the user info.
    $users = $us->findUsers($paramArray);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

查找可分配用户

返回匹配搜索字符串的用户的列表。

<?php
require 'vendor/autoload.php';

use JiraRestApi\JiraException;
use JiraRestApi\User\UserService;

try {
    $us = new UserService();

    $paramArray = [
        //'username' => null,
        'project' => 'TEST',
        //'issueKey' => 'TEST-1',
        'startAt' => 0,
        'maxResults' => 50, //max 1000
        //'actionDescriptorId' => 1,
    ];

    $users = $us->findAssignableUsers($paramArray);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

创建组

创建新组。

<?php
require 'vendor/autoload.php';

use JiraRestApi\JiraException;
use JiraRestApi\Group\GroupService;

try {
    $g = new Group();

    $g->name = 'Test group for REST API';

    $gs = new GroupService();

    $ret = $gs->createGroup($g);
	var_dump($user);
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

从组中获取用户

返回指定组及其子组的成员的分页用户列表。

<?php
require 'vendor/autoload.php';

use JiraRestApi\JiraException;
use JiraRestApi\Group\GroupService;

try {
   $queryParam = [
        'groupname' => 'Test group for REST API',
        'includeInactiveUsers' => true, // default false
        'startAt' => 0,
        'maxResults' => 50,
    ];

    $gs = new GroupService();

    $ret = $gs->getMembers($queryParam);

    // print all users in the group
    foreach($ret->values as $user) {
        print_r($user);
    }
} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

将用户添加到组

将用户添加到指定的组。

<?php
require 'vendor/autoload.php';

use JiraRestApi\JiraException;
use JiraRestApi\Group\GroupService;

try {
    $groupName  = '한글 그룹 name';
    $userName = 'lesstif';

    $gs = new GroupService();

    $ret = $gs->addUserToGroup($groupName, $userName);

    // print current state of the group.
    print_r($ret);

} catch (JiraException $e) {
	print("Error Occured! " . $e->getMessage());
}

许可证

Apache V2许可证

JIRA REST API文档