4006-8899-23 0532-86893032

禅道PHP-SDK帮助手册-第二章 分享链接

作者：雷勇 最后编辑：刘振华 于 2023-12-22 10:36:13 浏览量：2114
摘要：本篇将介绍如何在PHP编程语言中集成与使用此SDK，只需要简单的进行配置和引用便可使用。本篇内容是第一章的续章。

本篇目录

public function addBug()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'product'        => 1,
        'module'         => 2,
        'project'        => 1,
       'openedBuild'    => array('trunk', 3, 2),
        'openedBuild[1]' => 'trunk',
        'assignedTo'     => 'lisi',
        'deadline'       => '2019-11-21',
        'type'           => 'codeerror',
        'os'             => 'windows',
        'browser'        => 'ie11',
        'title'          => '添加bug测试四',
        'color'          => '#2dbdb2',
        'severity'       => 2,
        'pri'            => 1,
        'steps'          => '重现步骤描述添加bug测试四',
        'story'          => 0,
        'task'           => 0,
        'mailto[1]'      => 'lisi',
        'keywords'       => 'bug4'
    );    // 请求参数
    $result = $zentao->addBug($params);
    return $result;
}

 4.15完成单个任务可选信息

方法说明

请求此方法，可以获取该任务的所属项目详情、任务详情、任务操作记录，同时获取用于指派完成的用户列表。
使用示例
 
public function getTaskFinishParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('taskID' => 1);    // 请求参数
    $extraFields = array('title', 'users', 'task', 'project', 'actions');    // 自定义返回字段
    $result      = $zentao->getTaskFinishParams($params, $extraFields);
    return $result;
}
请求方式
 GET
方法名称
 getTaskFinishParams
请求参数
参数名称
 参数类型
 是否必填
 参数描述
taskID
 int 必填参数 任务ID
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
         //当前禅道项目导航位置
        "title": "禅道系统 PHP-SDK 开发-完成",
        //可用指派用户列表
        "users": {
            "_empty_": "",
            "admin": "A:admin",
            "lisi": "L:李四",
            "niuqi": "N:牛七",
            "wangwu": "W:王五",
            "zhangsan": "Z:张三",
            "zhapliu": "Z:赵六"
        },
        //任务详情信息
        "task": {
            "id": "1",
            "parent": "0",
            "project": "1",
            "module": "1",
            "story": "1",
            "storyVersion": "1",
            "fromBug": "0",
            "name": "确认禅道PHP-SDK需求，创建PHP-SDK文件 ",
            "type": "design",
            "pri": "1",
            "estimate": "4",
            "consumed": "6",//之前消耗时长【小时】
            "left": "0",
            "deadline": "2019-11-11",
            "status": "done",
            "subStatus": "",
            "color": "",
            "mailto": "",
            "desc": "创建 zentao.sdk.class 文件，做好基本的用户认证，分析需求，开始进行功能开发。",
            "openedBy": "admin",
            "openedDate": "2019-11-11 15:29:27",
            "assignedTo": "admin",
            "assignedDate": "2019-11-20 15:30:15",
            "estStarted": "2019-11-11",
            "realStarted": "2019-11-11",
            "finishedBy": "admin",
            "finishedDate": "2019-11-20 15:30:15",
            "finishedList": "",
            "canceledBy": "",
            "canceledDate": "",
            "closedBy": "",
            "closedDate": "",
            "closedReason": "",
            "lastEditedBy": "admin",
            "lastEditedDate": "2019-11-20 15:30:15",
            "deleted": "0",
            "storyID": "1",
            "storyTitle": "确认禅道PHP-SDK需求，创建PHP-SDK文件",
            "latestStoryVersion": "1",
            "storyStatus": "active",
            "assignedToRealName": "admin",
            "children": [],
            "team": [],
            "files": [],
            "cases": [],
            "needConfirm": false,
            "progress": 100,
            "nextBy": "admin"
        },
        //所属项目详情信息
        "project": {
            "id": "1",
            "isCat": "0",
            "catID": "0",
            "type": "sprint",
            "parent": "0",
            "name": "禅道系统 PHP-SDK 开发",
            "code": "002",
            "begin": "2019-11-11",
            "end": "2019-11-23",
            "days": "10",
            "status": "doing",
            "subStatus": "",
            "statge": "1",
            "pri": "1",
            "desc": "开发禅道项目管理系统 PHP-SDK 的开发，用于 PHPer 高效便捷的进行项目管理。",
            "openedBy": "admin",
            "openedDate": "2019-11-11 15:24:14",
            "openedVersion": "11.6.4",
            "closedBy": "",
            "closedDate": "0000-00-00 00:00:00",
            "canceledBy": "",
            "canceledDate": "0000-00-00 00:00:00",
            "PO": "lisi",
            "PM": "lisi",
            "QD": "lisi",
            "RD": "lisi",
            "team": "雷勇开发",
            "acl": "custom",
            "whitelist": "1,2",
            "order": "5",
            "deleted": "0",
            "totalHours": "420.0",
            "totalEstimate": 28,
            "totalConsumed": 33,
            "totalLeft": 5
        },
        //操作记录详情列表
        "actions": {
            "14": {
                "id": "14",
                "objectType": "task",
                "objectID": "1",
                "product": ",1,",
                "project": "1",
                "actor": "wangwu",
                "action": "started",
                "date": "2019-11-11 15:30:33",
                "comment": "",
                "extra": "",
                "read": "0",
                "history": [
                    {
                        "id": "2",
                        "action": "14",
                        "field": "realStarted",
                        "old": "0000-00-00",
                        "new": "2019-11-11",
                        "diff": ""
                    },
                    {
                        "id": "3",
                        "action": "14",
                        "field": "consumed",
                        "old": "0",
                        "new": "3",
                        "diff": ""
                    },
                    {
                        "id": "4",
                        "action": "14",
                        "field": "status",
                        "old": "wait",
                        "new": "doing",
                        "diff": ""
                    }
                ]
            }
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.16完成单个任务

方法说明

请求此方法，用于确认某一个任务完成，可指派完成任务的用户、消耗时间等信息。
使用示例
 
public function addTaskFinish()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'taskID'          => 16,
        'currentConsumed' => 1,
        'consumed'        => 19,
        'assignedTo'      => 'lisi',
        'finishedDate'    => '2019-11-12',
        'comment'         => '完成任务描述'
    );    // 请求参数
    $result = $zentao->addTaskFinish($params);
    return $result;
}
请求方式
 POST
方法名称
 addTaskFinish
请求参数
参数名称
 参数类型
 是否必填
 参数描述
taskID
 int 必填参数
 任务ID
currentConsumed
 int
 必填参数
 本次消耗【小时】
consumed
 int 必填参数
 之前消耗【小时,可从 完成单个任务可选信息 方法响应结果 task->consumed 获取】
assignedTo
 string
 必填参数
 指派完成用户【示例：admin】
finishedDate
 string
 必填参数
 实际完成时间【格式：2019-12-12】
comment
 string
 选填参数 完成备注
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": []
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.17获取Bug列表

方法说明

请求此方法，可以根据不同产品下的不同状态获取该产品 Bug 列表。
使用示例
 
public function getBugList()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('productID' => 1, 'branch' => 0, 'browseType' => 'unresolved');    // 请求参数
    $extraFields = array('title', 'products', 'productID', 'productName', 'product', 'moduleName', 'modules', 'browseType', 'bugs');    // 自定义返回字段
    $result      = $zentao->getBugList($params, $extraFields);
    return $result;
}
请求方式
 GET
方法名称

getBugList
请求参数
参数名称
 参数类型
 是否必填
 参数描述
productID
 int 必填参数 产品ID
branch
 int 必填参数 分支ID【默认为0】
browseType
 string
 选填参数 选填参数|Bug状态【all所有|unclosed未关闭|openedbyme由我创建|assigntome指派给我|resolvedbyme由我解决|toclosed待关闭|unresolved未解决|unconfirmed未确认|longlifebugs久未处理|postponedbugs被延期|overduebugs过期BUG|needconfirm需求变动】
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "禅道项目管理系统-PHP-SDK-Bug",
        //已有产品名称列表
        "products": {
            "1": "禅道项目管理系统-PHP-SDK",
            "2": "产品二",
            "3": "产品三",
            "4": "产品四",
            "5": "产品五",
            "6": "产品六",
            "9": "产品100"
        },
        //当前产品ID
        "productID": 1,
        //当前产品名称
        "productName": "禅道项目管理系统-PHP-SDK",
        //当前产品详情
        "product": {
            "id": "1",
            "name": "禅道项目管理系统-PHP-SDK",
            "code": "001",
            "line": "0",
            "type": "normal",
            "status": "normal",
            "subStatus": "",
            "desc": "开发禅道PHP开发语言的SDK，以方便开发人员能快速来创建和使用禅道系统所提供的服务，同时减少开发者的学习成本和时间。",
            "PO": "admin",
            "QD": "admin",
            "RD": "admin",
            "acl": "open",
            "whitelist": "",
            "createdBy": "admin",
            "createdDate": "2019-11-11 12:22:29",
            "createdVersion": "11.6.4",
            "order": "5",
            "deleted": "0"
        },
        //当前产品模块
        "moduleName": "所有模块",
        //当前产品模块列表
        "modules": [
            "/",
            "/设计",
            "/开发",
            "/变更",
            "/测试"
        ],
        //当前 BUG 状态
        "browseType": "unclosed",
        //当前状态下的 BUG 列表
        "bugs": [
            {
                "id": "7",//BUG ID
                "product": "1",//所属产品ID
                "branch": "0",//所属分支ID
                "module": "2",//所属模块ID
                "project": "1",//所属项目ID
                "plan": "0",//j所属计划ID
                "story": "0",
                "storyVersion": "1",
                "task": "0",
                "toTask": "0",
                "toStory": "0",
                "title": "添加bug测试三",//BUG 标题
                "keywords": "修改bug",//BUG 关键词
                "severity": "2",//严重程度
                "pri": "1",//优先程度
                "type": "codeerror",//BUG 类型
                "os": "windows",//操作系统
                "browser": "ie11",//浏览器
                "hardware": "",
                "found": "",
                "steps": "重现步骤描述添加bug测试三",//重现步骤描述
                "status": "active",//BUG 状态【active激活|resolved已解决|closed已关闭】
                "subStatus": "",
                "color": "#2dbdb2",//BUG颜色
                "confirmed": "0",//是否确认
                "activatedCount": "0",
                "activatedDate": "0000-00-00 00:00:00",
                "mailto": "zhangsan",
                "openedBy": "admin",
                "openedDate": "2019-11-21 16:45:58",
                "openedBuild": "主干",
                "assignedTo": "zhangsan",
                "assignedDate": "2019-11-21 16:45:58",
                "deadline": "2019-11-21",
                "resolvedBy": "",
                "resolution": "",
                "resolvedBuild": "",
                "resolvedDate": "0000-00-00 00:00:00",
                "closedBy": "",
                "closedDate": "0000-00-00 00:00:00",
                "duplicateBug": "0",
                "linkBug": "",
                "case": "0",
                "caseVersion": "1",
                "result": "0",
                "testtask": "0",
                "lastEditedBy": "",
                "lastEditedDate": "0000-00-00 00:00:00",
                "deleted": "0",
                "delay": 1,
                "needconfirm": false
            }
        ]
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.18添加单个Bug可选信息

方法说明

请求此方法，用于为指定产品添加 Bug 之前，获取添加 Bug 时可能需要用到的一些相关信息。
使用示例
 
public function getBugCreateParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('productID' => 1);    // 请求参数
    $extraFields = array('title', 'productID', 'productName', 'projects', 'moduleOptionMenu', 'users', 'stories', 'builds');    // 自定义返回字段
    $result      = $zentao->getBugCreateParams($params, $extraFields);
    return $result;
}
请求方式
 GET
方法名称
 getBugCreateParams
请求参数
参数名称
 参数类型
 是否必填
 参数描述
productID
 int 必填参数 所属产品ID
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
        //当前禅道项目导航位置
        "title": "禅道项目管理系统-PHP-SDK-提Bug",
        //当前产品ID
        "productID": 1, 
        //当前产品名称
        "productName": "禅道项目管理系统-PHP-SDK",
        //当前产品下的项目列表
        "projects": {
            "1": "禅道系统 PHP-SDK 开发",
            "_empty_": ""
        },
        //当前产品的模块列表
        "moduleOptionMenu": [
            "/",
            "/设计",
            "/开发",
            "/变更",
            "/测试"
        ],
        //可指派用户列表
        "users": {
            "_empty_": "",
            "lisi": "L:李四",
            "wangwu": "W:王五",
            "zhapliu": "Z:赵六",
            "admin": "A:admin",
            "niuqi": "N:牛七",
            "zhangsan": "Z:张三"
        },
        //当前产品需求列表
        "stories": {
            "1": "1:确认禅道PHP-SDK需求，创建PHP-SDK文件 (优先级:1,预计工时:4)",
            "2": "2:开发禅道SDK功能接口 (优先级:1,预计工时:24)",
            "_empty_": ""
        },
        //当前产品影响版本列表
        "builds": {
            "trunk": "主干"
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.19添加单个Bug

方法说明

请求此方法，用于新增 Bug 反馈，新增 Bug 时可以绑定所属产品、项目、优先级等相关设置，并指派给某个用户。
使用示例
 
public function addBug()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'product'        => 1,
        'module'         => 2,
        'project'        => 1,
        'openedBuild'    => array('trunk', 3, 2),
        'assignedTo'     => 'lisi',
        'deadline'       => '2019-11-21',
        'type'           => 'codeerror',
        'os'             => 'windows',
        'browser'        => 'ie11',
        'title'          => '添加bug测试四',
        'color'          => '#2dbdb2',
        'severity'       => 2,
        'pri'            => 1,
        'steps'          => '重现步骤描述添加bug测试四',
        'story'          => 0,
        'task'           => 0,
        'mailto'         => array('lisi', '张三'),
        'keywords'       => 'bug4'
    );    // 请求参数
    $result = $zentao->addBug($params);
    return $result;
}
请求方式
 POST
方法名称
 addBug
请求参数
参数名称
 参数类型
 是否必填
 参数描述
product
 int 必填参数
 所属产品ID
module
 int
 选填参数
 所属模块ID
project
 int
 选填参数
 所属项目ID
openedBuild
 array 选填参数
 影响版本ID【添加单个 Bug 可选信息结果中 builds 记录的 key 值】
assignedTo
 string 选填参数
 当前指派【用户账号】
deadline
 string
 选填参数
 截止日期【格式示例：2019-11-11】
type
 string
 选填参数
 BUG类型【codeerror代码错误|config配置相关|install安装部署|security安全相关|performance性能问题|standard标准规范|automation测试脚本|designdefect设计缺陷|others其他】
os string
 选填参数
 选填参数|操作系统【all-全部|windows-Windows|win10-Windows 10|win8-Windows 8|win7-Windows 7|vista-Windows Vista|winxp-Windows XP|win2012-Windows 2012|win2008-Windows 2008|win2003-Windows 2003|win2000-Windows 2000|android-Android|ios-IOS|wp8-WP8|wp7-WP7|symbian-Symbian|linux-Linux|freebsd-FreeBSD|osx-OS X|unix-Unix|others-其他】
browser
 string
 选填参数
 选填参数|浏览器【all-全部|ie-IE系列|ie11-IE11|ie10-IE10|ie9-IE9|ie8-IE8|ie7-IE7|ie6-IE6|chrome-Chrome|firefox-firefox系列|firefox4-firefox4|firefox3-firefox3|firefox2-firefox2|opera-opera系列|oprea11-oprea11|oprea10-opera10|opera9-opera9|safari-safari|maxthon-傲游|us-UC|other-其他】
title
 string
 必填参数
 BUG标题
browser
 string
 选填参数
 BUG颜色【示例：#2dbdb2】
severity
 int
 选填参数
 严重程度【1~4】
pri
 int
 选填参数
 优先级【1~4】
steps
 string
 选填参数
 重现步骤描述
story
 int
 选填参数
 相关需求ID
task
 int
 选填参数
 相关任务ID
keywords
 string
 选填参数
 BUG关键词
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": "保存成功"
}
 
{
    "status": 0,
    "msg": "error",
    "result": {
        "title": [
            "『Bug标题』不能为空。"
        ]
    }
}

 4.20解决单个Bug可选信息

方法说明

请求此方法，可以获取当前 Bug 详细信息以及确认 Bug 解决时可能用到的信息。
使用示例
 
public function getBugResolveParams()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao      = new \zentao();
    $params      = array('bugID' => 14);    // 请求参数
    $extraFields = array('title', 'products', 'bug', 'users', 'builds', 'actions');    // 自定义返回字段
    $result      = $zentao->getBugResolveParams($params, $extraFields);
    return $result;
}
请求方式
 GET
方法名称

getBugResolveParams
请求参数
参数名称
 参数类型
 是否必填
 参数描述
bugID
 int 必填参数 Bug ID
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": {
         //当前禅道项目导航位置
        "title": "禅道项目管理系统-PHP-SDK-解决",
        //已存在产品列表
        "products": {
            "1": "禅道项目管理系统-PHP-SDK"
        },
        //BUG详情【相关描述可参考 2.12 获取 BUG 列表】
        "bug": {
            "id": "5",
            "product": "1",
            "branch": "0",
            "module": "2",
            "project": "1",
            "plan": "0",
            "story": "0",
            "storyVersion": "1",
            "task": "0",
            "toTask": "0",
            "toStory": "0",
            "title": "添加bug测试二",
            "keywords": "修改bug",
            "severity": "2",
            "pri": "1",
            "type": "codeerror",
            "os": "windows",
            "browser": "ie11",
            "hardware": "",
            "found": "",
            "steps": "重现步骤描述添加bug测试二",
            "status": "active",
            "subStatus": "",
            "color": "#2dbdb2",
            "confirmed": "1",
            "activatedCount": "0",
            "activatedDate": "",
            "mailto": "lisi",
            "openedBy": "admin",
            "openedDate": "2019-11-21 16:45:13",
            "openedBuild": "trunk",
            "assignedTo": "lisi",
            "assignedDate": "2019-11-22 15:22:21",
            "deadline": "2019-11-21",
            "resolvedBy": "",
            "resolution": "",
            "resolvedBuild": "",
            "resolvedDate": "",
            "closedBy": "",
            "closedDate": "",
            "duplicateBug": "0",
            "linkBug": "",
            "case": "0",
            "caseVersion": "1",
            "result": "0",
            "testtask": "0",
            "lastEditedBy": "admin",
            "lastEditedDate": "2019-11-22 15:22:21",
            "deleted": "0",
            "projectName": "禅道系统 PHP-SDK 开发",
            "storyTitle": null,
            "storyStatus": null,
            "latestStoryVersion": null,
            "taskName": null,
            "planName": null,
            "toCases": [],
            "files": [],
            "delay": 1
        },
        //可用用户列表【用于指派】
        "users": {
            "_empty_": "",
            "admin": "A:admin",
            "lisi": "L:李四",
            "niuqi": "N:牛七",
            "wangwu": "W:王五",
            "zhangsan": "Z:张三",
            "zhapliu": "Z:赵六"
        },
        //当前可用版本【用于解决版本】
        "builds": {
            "_empty_": "",
            "trunk": "主干"
        },
        //当前 BUG 的操作记录
        "actions": {
            "791": {
                "id": "791",
                "objectType": "bug",
                "objectID": "5",
                "product": ",1,",
                "project": "1",
                "actor": "admin",
                "action": "bugconfirmed",
                "date": "2019-11-22 15:22:21",
                "comment": "",
                "extra": "",
                "read": "0",
                "history": [
                    {
                        "id": "216",
                        "action": "791",
                        "field": "confirmed",
                        "old": "0",
                        "new": "1",
                        "diff": ""
                    }
                ]
            }
        }
    }
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

 4.21解决单个Bug

方法说明

请求此方法，用于确认一个 Bug 已解决，同时为其绑定解决方案、解决版本、解决日期等相关信息。

  • 注意点一：如果需要新增所属版本，需要额外添加三个参数，示例：'buildProject' => 1，'buildName' => '版本7.2.4', createBuild' => 1，分别代表选择哪个项目（ 项目ID ）、新增版本名称、确认创建。
  • 注意点二：如果解决方案是【 duplicate 重复 Bug 】 时，需要输入重复 Bug 的 ID,额外添加参数，示例：'duplicateBug' => 5，代表和 ID 等于 5 的 Bug 重复。
使用示例
 
public function addBugResolve()
{
    include_once('../vendor/zentao/zentao.php');
    $zentao = new \zentao();
    $params = array(
        'bugID'         => 9,
        'resolution'    => 'duplicate',
        'resolvedBuild' => '2',
        'resolvedDate'  => '2019-11-22',
        'assignedTo'    => 'lisi',
        'comment'       => '解决bug描述',
        'buildProject'  => 1,
        'buildName'     => '版本7.2.5',
        'createBuild'   => 1,
        'duplicateBug'  => 2
    );    // 请求参数
    $result = $zentao->addBugResolve($params);
    return $result;
}
请求方式
 POST
方法名称

addBugResolve
请求参数
参数名称
 参数类型
 是否必填
 参数描述
bugID
 int 必填参数 Bug ID
resolution
 string
 必填参数
 解决方案【bydesign设计如此|duplicate重复Bug|external外部原因|fixed已解决|notrepro无法重现|postponed延期处理|willnotfix不予解决】
resolvedBuild
 string
 选填参数
 解决版本【如需新增版本，参考注意点一】
resolvedDate
 string
 选填参数
 解决日期【格式：2019-11-11】
assignedTo
 string
 选填参数
 指派用户【用户账号】
comment
 string
 选填参数
 备注描述
buildProject int 选填参数
 新增版本所属项目ID
buildName string 选填参数
 新增版本名称

createBuild

 int
 选填参数
 是否创建【1是0否】

duplicateBug

 int
 选填参数
 重复Bug的ID
响应结果
 success error 
{
    "status": 1,
    "msg": "success",
    "result": []
}
 
{
    "status": 0,
    "msg": "error",
    "result": []
}

五、常见问题？

 5.1调用禅道 SDK 类中方法，出现错误提示 "Trying to get property of non-object" ?

通常由以下情况造成，开发者可以打印输出 SDK 中请求结果 $result 查看返回信息以此查看原因。

  • 第一种情况，需要修改密码。解决方案： 登录后台管理系统，找到 后台->安全->密码安全设置 关闭密码检查、关闭强制修改弱密码、关闭强制首次登录修改密码
<html><meta charset='utf-8'/>
<style>body{background:white}</style>
<script>self.location='/index.php?m=my&f=changepassword&t=json';</script>
  • 第二种情况，没有操作权限。解决方案： 登录后台管理系统，给该账号设置相关权限。
<html><meta charset='utf-8'/>
<style>body{background:white}</style>
<script>self.location='/index.php?m=user&f=deny&t=json&module=dept&method=browse';</script>
  • 第三种情况，缺失参数。解决方案： 在 API 列表 中找到对应方法，检查所传参数是否与文档列表中的参数相符。