13678007438

Committed 05 Mar 2025 02:15PM UTC coverage: 2.081% (+0.01%) from 2.067%

Build # 13678007438

Build Type

push

github

Committed by

tylernathanreed

Commit Message

Merge branch 'master' of github.com:tylernathanreed/jira-client-php

Run Details

141 of 6775 relevant lines covered (2.08%)

0.03 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/src/Operations/ProjectRoles.php

<?php

namespace Jira\Client\Operations;

use Jira\Client\Client;
use Jira\Client\Schema;

/** @phpstan-require-extends Client */
trait ProjectRoles
{
    /**
     * Returns a list of "project roles" for the project returning the name and self URL for each role
     * 
     * Note that all project roles are shared with all projects in Jira Cloud.
     * See "Get all project roles" for more information
     * 
     * This operation can be accessed anonymously
     * 
     * **"Permissions" required:** *Administer Projects* "project permission" for any project on the site or *Administer Jira* "global permission".
     * 
     * @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/
     * @link https://confluence.atlassian.com/x/yodKLg
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @param string $projectIdOrKey The project ID or project key (case sensitive).
     */
    public function getProjectRoles(
        string $projectIdOrKey,
    ): true {
        return $this->call(
            uri: '/rest/api/3/project/{projectIdOrKey}/role',
            method: 'get',
            path: compact('projectIdOrKey'),
            success: 200,
            schema: true,
        );
    }

    /**
     * Returns a project role's details and actors associated with the project.
     * The list of actors is sorted by display name
     * 
     * To check whether a user belongs to a role based on their group memberships, use "Get user" with the `groups` expand parameter selected.
     * Then check whether the user keys and groups match with the actors returned for the project
     * 
     * This operation can be accessed anonymously
     * 
     * **"Permissions" required:** *Administer Projects* "project permission" for the project or *Administer Jira* "global permission".
     * 
     * @link https://confluence.atlassian.com/x/yodKLg
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @param string $projectIdOrKey The project ID or project key (case sensitive).
     * @param int $id The ID of the project role.
     *                Use "Get all project roles" to get a list of project role IDs.
     * @param bool $excludeInactiveUsers Exclude inactive users.
     */
    public function getProjectRole(
        string $projectIdOrKey,
        int $id,
        ?bool $excludeInactiveUsers = false,
    ): Schema\ProjectRole {
        return $this->call(
            uri: '/rest/api/3/project/{projectIdOrKey}/role/{id}',
            method: 'get',
            query: compact('excludeInactiveUsers'),
            path: compact('projectIdOrKey', 'id'),
            success: 200,
            schema: Schema\ProjectRole::class,
        );
    }

    /**
     * Returns all "project roles" and the details for each role.
     * Note that the list of project roles is common to all projects
     * 
     * This operation can be accessed anonymously
     * 
     * **"Permissions" required:** *Administer Jira* "global permission" or *Administer projects* "project permission" for the project.
     * 
     * @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/
     * @link https://confluence.atlassian.com/x/x4dKLg
     * @link https://confluence.atlassian.com/x/yodKLg
     * 
     * @param string $projectIdOrKey The project ID or project key (case sensitive).
     * @param bool $currentMember Whether the roles should be filtered to include only those the user is assigned to.
     * @param bool $excludeConnectAddons 
     * 
     * @return list<Schema\ProjectRoleDetails>
     */
    public function getProjectRoleDetails(
        string $projectIdOrKey,
        ?bool $currentMember = false,
        ?bool $excludeConnectAddons = false,
    ): array {
        return $this->call(
            uri: '/rest/api/3/project/{projectIdOrKey}/roledetails',
            method: 'get',
            query: compact('currentMember', 'excludeConnectAddons'),
            path: compact('projectIdOrKey'),
            success: 200,
            schema: [Schema\ProjectRoleDetails::class],
        );
    }

    /**
     * Gets a list of all project roles, complete with project role details and default actors
     * 
     * ### About project roles ###
     * 
     * "Project roles" are a flexible way to to associate users and groups with projects.
     * In Jira Cloud, the list of project roles is shared globally with all projects, but each project can have a different set of actors associated with it (unlike groups, which have the same membership throughout all Jira applications)
     * 
     * Project roles are used in "permission schemes", "email notification schemes", "issue security levels", "comment visibility", and workflow conditions
     * 
     * #### Members and actors ####
     * 
     * In the Jira REST API, a member of a project role is called an *actor*.
     * An *actor* is a group or user associated with a project role
     * 
     * Actors may be set as "default members" of the project role or set at the project level:
     * 
     *  - Default actors: Users and groups that are assigned to the project role for all newly created projects.
     * The default actors can be removed at the project level later if desired
     *  - Actors: Users and groups that are associated with a project role for a project, which may differ from the default actors.
     * This enables you to assign a user to different roles in different projects
     * 
     * **"Permissions" required:** *Administer Jira* "global permission".
     * 
     * @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/
     * @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/#Specifying-'default-members'-for-a-project-role
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @return list<Schema\ProjectRole>
     */
    public function getAllProjectRoles(): array
    {
        return $this->call(
            uri: '/rest/api/3/role',
            method: 'get',
            success: 200,
            schema: [Schema\ProjectRole::class],
        );
    }

    /**
     * Creates a new project role with no "default actors".
     * You can use the "Add default actors to project role" operation to add default actors to the project role after creating it
     * 
     * *Note that although a new project role is available to all projects upon creation, any default actors that are associated with the project role are not added to projects that existed prior to the role being created.*<
     * 
     * **"Permissions" required:** *Administer Jira* "global permission".
     * 
     * @link https://confluence.atlassian.com/x/x4dKLg
     */
    public function createProjectRole(
        Schema\CreateUpdateRoleRequestBean $request,
    ): Schema\ProjectRole {
        return $this->call(
            uri: '/rest/api/3/role',
            method: 'post',
            body: $request,
            success: 200,
            schema: Schema\ProjectRole::class,
        );
    }

    /**
     * Gets the project role details and the default actors associated with the role.
     * The list of default actors is sorted by display name
     * 
     * **"Permissions" required:** *Administer Jira* "global permission".
     * 
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @param int $id The ID of the project role.
     *                Use "Get all project roles" to get a list of project role IDs.
     */
    public function getProjectRoleById(
        int $id,
    ): Schema\ProjectRole {
        return $this->call(
            uri: '/rest/api/3/role/{id}',
            method: 'get',
            path: compact('id'),
            success: 200,
            schema: Schema\ProjectRole::class,
        );
    }

    /**
     * Updates the project role's name and description.
     * You must include both a name and a description in the request
     * 
     * **"Permissions" required:** *Administer Jira* "global permission".
     * 
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @param int $id The ID of the project role.
     *                Use "Get all project roles" to get a list of project role IDs.
     */
    public function fullyUpdateProjectRole(
        Schema\CreateUpdateRoleRequestBean $request,
        int $id,
    ): Schema\ProjectRole {
        return $this->call(
            uri: '/rest/api/3/role/{id}',
            method: 'put',
            body: $request,
            path: compact('id'),
            success: 200,
            schema: Schema\ProjectRole::class,
        );
    }

    /**
     * Updates either the project role's name or its description
     * 
     * You cannot update both the name and description at the same time using this operation.
     * If you send a request with a name and a description only the name is updated
     * 
     * **"Permissions" required:** *Administer Jira* "global permission".
     * 
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @param int $id The ID of the project role.
     *                Use "Get all project roles" to get a list of project role IDs.
     */
    public function partialUpdateProjectRole(
        Schema\CreateUpdateRoleRequestBean $request,
        int $id,
    ): Schema\ProjectRole {
        return $this->call(
            uri: '/rest/api/3/role/{id}',
            method: 'post',
            body: $request,
            path: compact('id'),
            success: 200,
            schema: Schema\ProjectRole::class,
        );
    }

    /**
     * Deletes a project role.
     * You must specify a replacement project role if you wish to delete a project role that is in use
     * 
     * **"Permissions" required:** *Administer Jira* "global permission".
     * 
     * @link https://confluence.atlassian.com/x/x4dKLg
     * 
     * @param int $id The ID of the project role to delete.
     *                Use "Get all project roles" to get a list of project role IDs.
     * @param int $swap The ID of the project role that will replace the one being deleted.
     *                  The swap will attempt to swap the role in schemes (notifications, permissions, issue security), workflows, worklogs and comments.
     */
    public function deleteProjectRole(
        int $id,
        ?int $swap = null,
    ): true {
        return $this->call(
            uri: '/rest/api/3/role/{id}',
            method: 'delete',
            query: compact('swap'),
            path: compact('id'),
            success: 204,
            schema: true,
        );
    }
}

1	<?php
2
3	namespace Jira\Client\Operations;
4
5	use Jira\Client\Client;
6	use Jira\Client\Schema;
7
8	/** @phpstan-require-extends Client */
9	trait ProjectRoles
10	{
11	/**
12	* Returns a list of "project roles" for the project returning the name and self URL for each role
13	*
14	* Note that all project roles are shared with all projects in Jira Cloud.
15	* See "Get all project roles" for more information
16	*
17	* This operation can be accessed anonymously
18	*
19	* "Permissions" required: Administer Projects "project permission" for any project on the site or Administer Jira "global permission".
20	*
21	* @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/
22	* @link https://confluence.atlassian.com/x/yodKLg
23	* @link https://confluence.atlassian.com/x/x4dKLg
24	*
25	* @param string $projectIdOrKey The project ID or project key (case sensitive).
26	*/
27	public function getProjectRoles(	×
28	string $projectIdOrKey,
29	): true {
30	return $this->call(	×
31	uri: '/rest/api/3/project/{projectIdOrKey}/role',	×
32	method: 'get',	×
33	path: compact('projectIdOrKey'),	×
34	success: 200,	×
35	schema: true,	×
36	);	×
37	}
38
39	/**
40	* Returns a project role's details and actors associated with the project.
41	* The list of actors is sorted by display name
42	*
43	* To check whether a user belongs to a role based on their group memberships, use "Get user" with the `groups` expand parameter selected.
44	* Then check whether the user keys and groups match with the actors returned for the project
45	*
46	* This operation can be accessed anonymously
47	*
48	* "Permissions" required: Administer Projects "project permission" for the project or Administer Jira "global permission".
49	*
50	* @link https://confluence.atlassian.com/x/yodKLg
51	* @link https://confluence.atlassian.com/x/x4dKLg
52	*
53	* @param string $projectIdOrKey The project ID or project key (case sensitive).
54	* @param int $id The ID of the project role.
55	* Use "Get all project roles" to get a list of project role IDs.
56	* @param bool $excludeInactiveUsers Exclude inactive users.
57	*/
58	public function getProjectRole(	×
59	string $projectIdOrKey,
60	int $id,
61	?bool $excludeInactiveUsers = false,
62	): Schema\ProjectRole {
63	return $this->call(	×
64	uri: '/rest/api/3/project/{projectIdOrKey}/role/{id}',	×
65	method: 'get',	×
66	query: compact('excludeInactiveUsers'),	×
67	path: compact('projectIdOrKey', 'id'),	×
68	success: 200,	×
69	schema: Schema\ProjectRole::class,	×
70	);	×
71	}
72
73	/**
74	* Returns all "project roles" and the details for each role.
75	* Note that the list of project roles is common to all projects
76	*
77	* This operation can be accessed anonymously
78	*
79	* "Permissions" required: Administer Jira "global permission" or Administer projects "project permission" for the project.
80	*
81	* @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/
82	* @link https://confluence.atlassian.com/x/x4dKLg
83	* @link https://confluence.atlassian.com/x/yodKLg
84	*
85	* @param string $projectIdOrKey The project ID or project key (case sensitive).
86	* @param bool $currentMember Whether the roles should be filtered to include only those the user is assigned to.
87	* @param bool $excludeConnectAddons
88	*
89	* @return list<Schema\ProjectRoleDetails>
90	*/
91	public function getProjectRoleDetails(	×
92	string $projectIdOrKey,
93	?bool $currentMember = false,
94	?bool $excludeConnectAddons = false,
95	): array {
96	return $this->call(	×
97	uri: '/rest/api/3/project/{projectIdOrKey}/roledetails',	×
98	method: 'get',	×
99	query: compact('currentMember', 'excludeConnectAddons'),	×
100	path: compact('projectIdOrKey'),	×
101	success: 200,	×
102	schema: [Schema\ProjectRoleDetails::class],	×
103	);	×
104	}
105
106	/**
107	* Gets a list of all project roles, complete with project role details and default actors
108	*
109	* ### About project roles ###
110	*
111	* "Project roles" are a flexible way to to associate users and groups with projects.
112	* In Jira Cloud, the list of project roles is shared globally with all projects, but each project can have a different set of actors associated with it (unlike groups, which have the same membership throughout all Jira applications)
113	*
114	* Project roles are used in "permission schemes", "email notification schemes", "issue security levels", "comment visibility", and workflow conditions
115	*
116	* #### Members and actors ####
117	*
118	* In the Jira REST API, a member of a project role is called an actor.
119	* An actor is a group or user associated with a project role
120	*
121	* Actors may be set as "default members" of the project role or set at the project level:
122	*
123	* - Default actors: Users and groups that are assigned to the project role for all newly created projects.
124	* The default actors can be removed at the project level later if desired
125	* - Actors: Users and groups that are associated with a project role for a project, which may differ from the default actors.
126	* This enables you to assign a user to different roles in different projects
127	*
128	* "Permissions" required: Administer Jira "global permission".
129	*
130	* @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/
131	* @link https://support.atlassian.com/jira-cloud-administration/docs/manage-project-roles/#Specifying-'default-members'-for-a-project-role
132	* @link https://confluence.atlassian.com/x/x4dKLg
133	*
134	* @return list<Schema\ProjectRole>
135	*/
136	public function getAllProjectRoles(): array	×
137	{
138	return $this->call(	×
139	uri: '/rest/api/3/role',	×
140	method: 'get',	×
141	success: 200,	×
142	schema: [Schema\ProjectRole::class],	×
143	);	×
144	}
145
146	/**
147	* Creates a new project role with no "default actors".
148	* You can use the "Add default actors to project role" operation to add default actors to the project role after creating it
149	*
150	* Note that although a new project role is available to all projects upon creation, any default actors that are associated with the project role are not added to projects that existed prior to the role being created.<
151	*
152	* "Permissions" required: Administer Jira "global permission".
153	*
154	* @link https://confluence.atlassian.com/x/x4dKLg
155	*/
156	public function createProjectRole(	×
157	Schema\CreateUpdateRoleRequestBean $request,
158	): Schema\ProjectRole {
159	return $this->call(	×
160	uri: '/rest/api/3/role',	×
161	method: 'post',	×
162	body: $request,	×
163	success: 200,	×
164	schema: Schema\ProjectRole::class,	×
165	);	×
166	}
167
168	/**
169	* Gets the project role details and the default actors associated with the role.
170	* The list of default actors is sorted by display name
171	*
172	* "Permissions" required: Administer Jira "global permission".
173	*
174	* @link https://confluence.atlassian.com/x/x4dKLg
175	*
176	* @param int $id The ID of the project role.
177	* Use "Get all project roles" to get a list of project role IDs.
178	*/
179	public function getProjectRoleById(	×
180	int $id,
181	): Schema\ProjectRole {
182	return $this->call(	×
183	uri: '/rest/api/3/role/{id}',	×
184	method: 'get',	×
185	path: compact('id'),	×
186	success: 200,	×
187	schema: Schema\ProjectRole::class,	×
188	);	×
189	}
190
191	/**
192	* Updates the project role's name and description.
193	* You must include both a name and a description in the request
194	*
195	* "Permissions" required: Administer Jira "global permission".
196	*
197	* @link https://confluence.atlassian.com/x/x4dKLg
198	*
199	* @param int $id The ID of the project role.
200	* Use "Get all project roles" to get a list of project role IDs.
201	*/
202	public function fullyUpdateProjectRole(	×
203	Schema\CreateUpdateRoleRequestBean $request,
204	int $id,
205	): Schema\ProjectRole {
206	return $this->call(	×
207	uri: '/rest/api/3/role/{id}',	×
208	method: 'put',	×
209	body: $request,	×
210	path: compact('id'),	×
211	success: 200,	×
212	schema: Schema\ProjectRole::class,	×
213	);	×
214	}
215
216	/**
217	* Updates either the project role's name or its description
218	*
219	* You cannot update both the name and description at the same time using this operation.
220	* If you send a request with a name and a description only the name is updated
221	*
222	* "Permissions" required: Administer Jira "global permission".
223	*
224	* @link https://confluence.atlassian.com/x/x4dKLg
225	*
226	* @param int $id The ID of the project role.
227	* Use "Get all project roles" to get a list of project role IDs.
228	*/
229	public function partialUpdateProjectRole(	×
230	Schema\CreateUpdateRoleRequestBean $request,
231	int $id,
232	): Schema\ProjectRole {
233	return $this->call(	×
234	uri: '/rest/api/3/role/{id}',	×
235	method: 'post',	×
236	body: $request,	×
237	path: compact('id'),	×
238	success: 200,	×
239	schema: Schema\ProjectRole::class,	×
240	);	×
241	}
242
243	/**
244	* Deletes a project role.
245	* You must specify a replacement project role if you wish to delete a project role that is in use
246	*
247	* "Permissions" required: Administer Jira "global permission".
248	*
249	* @link https://confluence.atlassian.com/x/x4dKLg
250	*
251	* @param int $id The ID of the project role to delete.
252	* Use "Get all project roles" to get a list of project role IDs.
253	* @param int $swap The ID of the project role that will replace the one being deleted.
254	* The swap will attempt to swap the role in schemes (notifications, permissions, issue security), workflows, worklogs and comments.
255	*/
256	public function deleteProjectRole(	×
257	int $id,
258	?int $swap = null,
259	): true {
260	return $this->call(	×
261	uri: '/rest/api/3/role/{id}',	×
262	method: 'delete',	×
263	query: compact('swap'),	×
264	path: compact('id'),	×
265	success: 204,	×
266	schema: true,	×
267	);	×
268	}
269	}

tylernathanreed / jira-client-php / 13678007438

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous