From 6b1fcc138b940ce86f8b76d34585f665588f6aa1 Mon Sep 17 00:00:00 2001 From: Damien Regad Date: Sat, 17 Feb 2024 00:15:32 +0100 Subject: [PATCH 1/5] PHPDoc --- api/soap/mc_project_api.php | 247 +++++++++++++++++++++--------------- 1 file changed, 146 insertions(+), 101 deletions(-) diff --git a/api/soap/mc_project_api.php b/api/soap/mc_project_api.php index 0b392b6f65..9fd137476b 100644 --- a/api/soap/mc_project_api.php +++ b/api/soap/mc_project_api.php @@ -28,19 +28,20 @@ /** * Use a standard filter to get issues associated with the specified user. * - * @param string $p_username Logged in user name. - * @param string $p_password Login password. - * @param integer $p_project_id Id of project to filter on, or ALL_PROJECTS. - * @param string $p_filter_type The name of the filter to apply - * "assigned" - target user specified - issues assigned to target user that are not resolved. - * "assigned" - target user 0 - unassigned issues that are not resolved. - * "reported" - target user specified - issues reported by user. - * "reported" - target user 0 - will throw. - * "monitored" - target user specified - issues monitored by user. - * "monitored" - target user 0 - issues not monitored. - * @param object $p_target_user AccountData for target user, can include id, name, or both. - * @param integer $p_page_number The page to return (1 based). - * @param integer $p_per_page Number of issues per page. + * @param string $p_username Logged in user name. + * @param string $p_password Login password. + * @param int $p_project_id Id of project to filter on, or ALL_PROJECTS. + * @param string $p_filter_type The name of the filter to apply + * "assigned" - target user specified - issues assigned to target user that are not resolved. + * "assigned" - target user 0 - unassigned issues that are not resolved. + * "reported" - target user specified - issues reported by user. + * "reported" - target user 0 - will throw. + * "monitored" - target user specified - issues monitored by user. + * "monitored" - target user 0 - issues not monitored. + * @param object $p_target_user AccountData for target user, can include id, name, or both. + * @param int $p_page_number The page to return (1 based). + * @param int $p_per_page Number of issues per page. + * * @return array|RestFault|SoapFault a page of matching issues or error. */ function mc_project_get_issues_for_user( $p_username, $p_password, $p_project_id, $p_filter_type, $p_target_user, $p_page_number, $p_per_page ) { @@ -107,13 +108,15 @@ function mc_project_get_issues_for_user( $p_username, $p_password, $p_project_id } /** - * Project Get Issues - * @param string $p_username Logged in user name. - * @param string $p_password Login password. - * @param integer $p_project_id Project Id. - * @param integer $p_page_number Page number. - * @param integer $p_per_page Per page. - * @return array + * Project Get Issues. + * + * @param string $p_username Logged in user name. + * @param string $p_password Login password. + * @param int $p_project_id Project Id. + * @param int $p_page_number Page number. + * @param int $p_per_page Per page. + * + * @return array|RestFault|SoapFault */ function mc_project_get_issues( $p_username, $p_password, $p_project_id, $p_page_number, $p_per_page ) { global $g_project_override; @@ -158,7 +161,9 @@ function mc_project_get_issues( $p_username, $p_password, $p_project_id, $p_page * * @param string $p_username The name of the user trying to access the project list. * @param string $p_password The password of the user. - * @return array suitable to be converted into a ProjectDataArray + * + * @return array|RestFault|SoapFault Array suitable to be converted into a ProjectDataArray + * @throws ClientException */ function mc_projects_get_user_accessible( $p_username, $p_password ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -194,10 +199,11 @@ function mc_projects_get_user_accessible( $p_username, $p_password ) { /** * Get all categories of a project. * - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @return array An array of category names + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * + * @return array|RestFault|SoapFault An array of category names */ function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -225,12 +231,14 @@ function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { } /** - * Add a new category to a project - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @param string $p_category_name The name of the new category to add. - * @return integer id of the new category + * Add a new category to a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project for which to add the category. + * @param string $p_category_name The name of the new category to add. + * + * @return int|RestFault|SoapFault Id of the new category */ function mc_project_add_category( $p_username, $p_password, $p_project_id, $p_category_name ) { global $g_project_override; @@ -253,12 +261,14 @@ function mc_project_add_category( $p_username, $p_password, $p_project_id, $p_ca } /** - * Delete a category of a project - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @param string $p_category_name The name of the category to delete. - * @return boolean returns true or false depending on the success of the delete action + * Delete a category of a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * @param string $p_category_name The name of the category to delete. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. */ function mc_project_delete_category ( $p_username, $p_password, $p_project_id, $p_category_name ) { global $g_project_override; @@ -294,14 +304,16 @@ function mc_project_delete_category ( $p_username, $p_password, $p_project_id, $ } /** - * Update a category of a project - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @param string $p_category_name The name of the category to rename. - * @param string $p_category_name_new The new name of the category to rename. - * @param integer $p_assigned_to User ID that category is assigned to. - * @return boolean returns true or false depending on the success of the update action + * Update a category of a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * @param string $p_category_name The name of the category to rename. + * @param string $p_category_name_new The new name of the category to rename. + * @param int $p_assigned_to User ID that category is assigned to. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the update action */ function mc_project_rename_category_by_name( $p_username, $p_password, $p_project_id, $p_category_name, $p_category_name_new, $p_assigned_to ) { global $g_project_override; @@ -335,10 +347,11 @@ function mc_project_rename_category_by_name( $p_username, $p_password, $p_projec /** * Get all versions of a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the versions for. - * @return array representing a ProjectVersionDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -368,10 +381,11 @@ function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { /** * Get all released versions of a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the versions for. - * @return array representing a ProjectVersionDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_released_versions( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -402,10 +416,11 @@ function mc_project_get_released_versions( $p_username, $p_password, $p_project_ /** * Get all unreleased (a.k.a. future) versions of a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the versions for. - * @return array representing a ProjectVersionDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_unreleased_versions( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -439,8 +454,11 @@ function mc_project_get_unreleased_versions( $p_username, $p_password, $p_projec * * @param string $p_username The name of the user trying to add the issue. * @param string $p_password The password of the user. - * @param stdClass $p_version A ProjectVersionData structure containing information about the new version. - * @return integer The id of the created version. + * @param stdClass $p_version A ProjectVersionData structure containing + * information about the new version. + * + * @return int|RestFault|SoapFault The id of the created version. + * @throws ClientException */ function mc_project_version_add( $p_username, $p_password, stdClass $p_version ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -481,9 +499,12 @@ function mc_project_version_add( $p_username, $p_password, stdClass $p_version ) * * @param string $p_username The name of the user trying to update the issue. * @param string $p_password The password of the user. - * @param integer $p_version_id A version's id. - * @param stdClass $p_version A ProjectVersionData structure containing information about the new version. - * @return boolean returns true or false depending on the success of the update action + * @param int $p_version_id A version's id. + * @param stdClass $p_version A ProjectVersionData structure containing + * information about the new version. + * + * @return bool|RestFault|SoapFault returns true or false depending on the success of the update action. + * @throws ClientException */ function mc_project_version_update( $p_username, $p_password, $p_version_id, stdClass $p_version ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -544,10 +565,12 @@ function mc_project_version_update( $p_username, $p_password, $p_version_id, std /** * Delete a version. * - * @param string $p_username The name of the user trying to delete the version. - * @param string $p_password The password of the user. - * @param integer $p_version_id A version's id. - * @return boolean returns true or false depending on the success of the delete action + * @param string $p_username The name of the user trying to delete the version. + * @param string $p_password The password of the user. + * @param int $p_version_id A version's id. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. + * @throws ClientException */ function mc_project_version_delete( $p_username, $p_password, $p_version_id ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -588,7 +611,8 @@ function mc_project_version_delete( $p_username, $p_password, $p_version_id ) { * * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the custom fields for. + * @param int $p_project_id The id of the project to retrieve the custom fields for. + * * @return array|RestFault|SoapFault representing a CustomFieldDefinitionDataArray structure. */ function mc_project_get_custom_fields( $p_username, $p_password, $p_project_id ) { @@ -608,10 +632,11 @@ function mc_project_get_custom_fields( $p_username, $p_password, $p_project_id ) /** * Validate custom fields before creating/updating issues. * - * @param integer $p_project_id The project id. - * @param array $p_custom_fields The custom fields, may be not set. - * @return bool|SoapFault|RestFault true or error. + * @param int $p_project_id The project id. + * @param array $p_custom_fields The custom fields (by reference). + * May be unset; if so, will be set to null. * + * @return bool true or error. * @throws ClientException */ function mci_project_custom_fields_validate( $p_project_id, &$p_custom_fields ) { @@ -710,7 +735,8 @@ function mci_project_custom_fields_validate( $p_project_id, &$p_custom_fields ) /** * Get the custom fields that belong to the specified project. * - * @param integer $p_project_id The id of the project to retrieve the custom fields for. + * @param int $p_project_id The id of the project to retrieve the custom fields for. + * * @return array|RestFault|SoapFault representing a CustomFieldDefinitionDataArray structure. */ function mci_project_get_custom_fields( $p_project_id ) { @@ -785,6 +811,7 @@ function mci_project_get_custom_fields( $p_project_id ) { * Get the custom field type name given its type id. * * @param int $p_type_id The custom field type id. + * * @return string The type name or id if an unknown type. */ function mci_custom_field_type_name( $p_type_id ) { @@ -816,7 +843,9 @@ function mci_custom_field_type_name( $p_type_id ) { /** * Get list of versions for a project. + * * @param int $p_project_id The project id + * * @return array The project versions. */ function mci_project_versions( $p_project_id ) { @@ -845,6 +874,7 @@ function mci_project_versions( $p_project_id ) { * Get projects for the specified project. * * @param int $p_project_id The project id + * * @return array The array of categories with their info. */ function mci_project_categories( $p_project_id ) { @@ -876,10 +906,11 @@ function mci_project_categories( $p_project_id ) { /** * Get the attachments that belong to the specified project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the attachments for. - * @return array representing a ProjectAttachmentDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the attachments for. + * + * @return array|RestFault|SoapFault Array representing a ProjectAttachmentDataArray structure. */ function mc_project_get_attachments( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -968,11 +999,13 @@ function mc_project_get_attachments( $p_username, $p_password, $p_project_id ) { } /** - * Get the list of subprojects for a given project - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the attachments for. - * @return array + * Get the list of subprojects for a given project. + * + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the attachments for. + * + * @return array|RestFault|SoapFault */ function mc_project_get_all_subprojects( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -999,7 +1032,8 @@ function mc_project_get_all_subprojects( $p_username, $p_password, $p_project_id /** * Get a project definition. * - * @param integer $p_project_id The id of the project to retrieve. + * @param int $p_project_id The id of the project to retrieve. + * * @return array an array containing the id and the name of the project. */ function mci_project_as_array_by_id( $p_project_id ) { @@ -1015,7 +1049,8 @@ function mci_project_as_array_by_id( $p_project_id ) { * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. * @param string $p_project_name The name of the project to retrieve. - * @return int The id of the project with the given name, 0 if there is no such project. + * + * @return int|RestFault|SoapFault The id of the project with the given name, 0 if there is no such project. */ function mc_project_get_id_from_name( $p_username, $p_password, $p_project_name ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1035,7 +1070,9 @@ function mc_project_get_id_from_name( $p_username, $p_password, $p_project_name * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. * @param stdClass $p_project A new ProjectData structure. - * @return int the new project's project_id + * + * @return int|RestFault|SoapFault The new project's project_id + * @throws ClientException */ function mc_project_add( $p_username, $p_password, stdClass $p_project ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1094,9 +1131,11 @@ function mc_project_add( $p_username, $p_password, stdClass $p_project ) { * * @param string $p_username The name of the user. * @param string $p_password The password of the user. - * @param integer $p_project_id A project's identifier. + * @param int $p_project_id A project's identifier. * @param stdClass $p_project A new ProjectData structure. - * @return boolean returns true or false depending on the success of the update action + * + * @return bool|RestFault|SoapFault True or false depending on the success of the update action. + * @throws ClientException */ function mc_project_update( $p_username, $p_password, $p_project_id, stdClass $p_project ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1152,10 +1191,12 @@ function mc_project_update( $p_username, $p_password, $p_project_id, stdClass $p /** * Delete a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id A project's identifier. - * @return boolean returns true or false depending on the success of the delete action + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id A project's identifier. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. + * @throws ClientException */ function mc_project_delete( $p_username, $p_password, $p_project_id ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1176,13 +1217,15 @@ function mc_project_delete( $p_username, $p_password, $p_project_id ) { } /** - * Get Issue Headers - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the attachments for. - * @param integer $p_page_number Page number. - * @param integer $p_per_page Per page. - * @return mixed + * Get Issue Headers. + * + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the attachments for. + * @param int $p_page_number Page number. + * @param int $p_per_page Per page. + * + * @return array|RestFault|SoapFault */ function mc_project_get_issue_headers( $p_username, $p_password, $p_project_id, $p_page_number, $p_per_page ) { global $g_project_override; @@ -1223,11 +1266,13 @@ function mc_project_get_issue_headers( $p_username, $p_password, $p_project_id, /** * Get appropriate users assigned to a project by access level. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the users for. - * @param integer $p_access Minimum access level. - * @return array representing a ProjectAttachmentDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the users for. + * @param int $p_access Minimum access level. + * + * @return array|RestFault|SoapFault Array representing a ProjectAttachmentDataArray structure. + * @throws ClientException */ function mc_project_get_users( $p_username, $p_password, $p_project_id, $p_access ) { global $g_project_override; From 3072c16700b2059245392536ef0487b857088bbf Mon Sep 17 00:00:00 2001 From: Damien Regad Date: Sat, 17 Feb 2024 00:13:52 +0100 Subject: [PATCH 2/5] Fix static analysis warnings --- api/soap/mc_project_api.php | 41 +++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/api/soap/mc_project_api.php b/api/soap/mc_project_api.php index 9fd137476b..750898bea7 100644 --- a/api/soap/mc_project_api.php +++ b/api/soap/mc_project_api.php @@ -21,6 +21,9 @@ * @copyright Copyright 2004 Victor Boctor - vboctor@users.sourceforge.net * @copyright Copyright 2005 MantisBT Team - mantisbt-dev@lists.sourceforge.net * @link http://www.mantisbt.org + * + * @noinspection PhpComposerExtensionStubsInspection + * @noinspection PhpUnused */ use Mantis\Exceptions\ClientException; @@ -60,11 +63,10 @@ function mc_project_get_issues_for_user( $p_username, $p_password, $p_project_id $t_lang = mci_get_user_lang( $t_user_id ); - $t_orig_page_number = $p_page_number < 1 ? 1 : $p_page_number; + $t_orig_page_number = max( $p_page_number, 1 ); $t_page_count = 0; $t_bug_count = 0; $t_target_user_id = mci_get_user_id( $p_target_user ); - $t_show_sticky = true; if( strcasecmp( $p_filter_type, 'assigned' ) == 0 ) { # If user is filtering on handlers, then they must have access to view handlers @@ -91,7 +93,7 @@ function mc_project_get_issues_for_user( $p_username, $p_password, $p_project_id $t_rows = filter_get_bug_rows( $p_page_number, $p_per_page, $t_page_count, $t_bug_count, $t_filter, - $p_project_id, $t_user_id, $t_show_sticky ); + $p_project_id, $t_user_id, true ); $t_result = array(); @@ -135,7 +137,7 @@ function mc_project_get_issues( $p_username, $p_password, $p_project_id, $p_page return mci_fault_access_denied( $t_user_id ); } - $t_orig_page_number = $p_page_number < 1 ? 1 : $p_page_number; + $t_orig_page_number = max( $p_page_number, 1 ); $t_page_count = 0; $t_bug_count = 0; $g_project_override = $p_project_id; @@ -300,7 +302,8 @@ function mc_project_delete_category ( $p_username, $p_password, $p_project_id, $ } # delete the category and link all the issues to the default category - return category_remove( $p_category_id, config_get( 'default_category_for_moves' ) ); + category_remove( $p_category_id, config_get( 'default_category_for_moves' ) ); + return true; } /** @@ -341,7 +344,8 @@ function mc_project_rename_category_by_name( $p_username, $p_password, $p_projec $p_category_id = category_get_id_by_name( $p_category_name, $p_project_id ); # update the category - return category_update( $p_category_id, $p_category_name_new, $p_assigned_to ); + category_update( $p_category_id, $p_category_name_new, $p_assigned_to ); + return true; } /** @@ -483,7 +487,7 @@ function mc_project_version_add( $p_username, $p_password, stdClass $p_version ) 'name' => $p_version['name'], 'description' => $p_version['description'], 'released' => $p_version['released'], - 'obsolete' => isset( $p_version['obsolete'] ) ? $p_version['obsolete'] : false, + 'obsolete' => $p_version['obsolete'] ?? false, 'timestamp' => $p_version['date_order'] ) ); @@ -528,7 +532,7 @@ function mc_project_version_update( $p_username, $p_password, $p_version_id, std $t_released = $p_version['released']; $t_description = $p_version['description']; $t_date_order = is_blank( $p_version['date_order'] ) ? null : $p_version['date_order']; - $t_obsolete = isset( $p_version['obsolete'] ) ? $p_version['obsolete'] : false; + $t_obsolete = $p_version['obsolete'] ?? false; if( is_blank( $t_project_id ) ) { return ApiObjectFactory::faultBadRequest( 'Mandatory field "project_id" was missing' ); @@ -636,8 +640,10 @@ function mc_project_get_custom_fields( $p_username, $p_password, $p_project_id ) * @param array $p_custom_fields The custom fields (by reference). * May be unset; if so, will be set to null. * - * @return bool true or error. + * @return void * @throws ClientException + * + * @noinspection PhpParameterByRefIsNotUsedAsReferenceInspection */ function mci_project_custom_fields_validate( $p_project_id, &$p_custom_fields ) { # Load custom field definitions for the specified project @@ -728,8 +734,6 @@ function mci_project_custom_fields_validate( $p_project_id, &$p_custom_fields ) ); } } - - return true; } /** @@ -936,8 +940,6 @@ function mc_project_get_attachments( $p_username, $p_password, $p_project_id ) { return mci_fault_access_denied( $t_user_id ); } - $t_pub = VS_PUBLIC; - $t_priv = VS_PRIVATE; $t_admin = config_get_global( 'admin_site_threshold' ); if( $p_project_id == ALL_PROJECTS ) { @@ -975,7 +977,7 @@ function mc_project_get_attachments( $p_username, $p_password, $p_project_id ) { ( ut.access_level = ' . db_param() . ' ) ) ORDER BY pt.name ASC, pft.title ASC'; - $t_result = db_query( $t_query, array( $t_user_id, $t_user_id, $t_pub, $t_user_id, $t_admin ) ); + $t_result = db_query( $t_query, array( $t_user_id, $t_user_id, VS_PUBLIC, $t_user_id, $t_admin ) ); $t_num_files = db_num_rows( $t_result ); $t_attachments = array(); @@ -1120,10 +1122,9 @@ function mc_project_add( $p_username, $p_password, stdClass $p_project ) { $t_command = new ProjectAddCommand( $t_data ); $t_result = $t_command->execute(); - $t_project_id = $t_result['id']; # project_create returns the new project's id, spit that out to web service caller - return $t_project_id; + return $t_result['id']; } /** @@ -1244,7 +1245,7 @@ function mc_project_get_issue_headers( $p_username, $p_password, $p_project_id, return mci_fault_access_denied( $t_user_id ); } - $t_orig_page_number = $p_page_number < 1 ? 1 : $p_page_number; + $t_orig_page_number = max( $p_page_number, 1 ); $t_page_count = 0; $t_bug_count = 0; @@ -1275,8 +1276,6 @@ function mc_project_get_issue_headers( $p_username, $p_password, $p_project_id, * @throws ClientException */ function mc_project_get_users( $p_username, $p_password, $p_project_id, $p_access ) { - global $g_project_override; - $t_user_id = mci_check_login( $p_username, $p_password ); if( $t_user_id === false ) { @@ -1295,7 +1294,5 @@ function mc_project_get_users( $p_username, $p_password, $p_project_id, $p_acces $t_command = new ProjectUsersGetCommand( $t_data ); $t_result = $t_command->execute(); - $t_result = $t_result['users']; - - return $t_result; + return $t_result['users']; } From ef8b79aa1830d404ce1310922bd10da04ef3f2d6 Mon Sep 17 00:00:00 2001 From: Damien Regad Date: Sat, 17 Feb 2024 00:24:08 +0100 Subject: [PATCH 3/5] New function mci_project_get_row() Avoid duplicated code in - mc_projects_get_user_accessible - mci_user_get_accessible_subprojects() --- api/soap/mc_api.php | 13 +------------ api/soap/mc_project_api.php | 39 +++++++++++++++++++++++++------------ 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/api/soap/mc_api.php b/api/soap/mc_api.php index 7f79b57773..afddb3e347 100644 --- a/api/soap/mc_api.php +++ b/api/soap/mc_api.php @@ -887,18 +887,7 @@ function mci_user_get_accessible_subprojects( $p_user_id, $p_parent_project_id, $t_result = array(); foreach( user_get_accessible_subprojects( $p_user_id, $p_parent_project_id ) as $t_subproject_id ) { - $t_subproject_row = project_cache_row( $t_subproject_id ); - $t_subproject = array(); - $t_subproject['id'] = $t_subproject_id; - $t_subproject['name'] = $t_subproject_row['name']; - $t_subproject['status'] = mci_enum_get_array_by_id( $t_subproject_row['status'], 'project_status', $t_lang ); - $t_subproject['enabled'] = $t_subproject_row['enabled']; - $t_subproject['view_state'] = mci_enum_get_array_by_id( $t_subproject_row['view_state'], 'project_view_state', $t_lang ); - $t_subproject['access_min'] = mci_enum_get_array_by_id( $t_subproject_row['access_min'], 'access_levels', $t_lang ); - $t_subproject['file_path'] = array_key_exists( 'file_path', $t_subproject_row ) ? $t_subproject_row['file_path'] : ''; - $t_subproject['description'] = array_key_exists( 'description', $t_subproject_row ) ? $t_subproject_row['description'] : ''; - $t_subproject['subprojects'] = mci_user_get_accessible_subprojects( $p_user_id, $t_subproject_id, $t_lang ); - $t_result[] = $t_subproject; + $t_result[] = mci_project_get_row( $t_subproject_id, $p_user_id, $t_lang ); } return $t_result; diff --git a/api/soap/mc_project_api.php b/api/soap/mc_project_api.php index 750898bea7..569418da21 100644 --- a/api/soap/mc_project_api.php +++ b/api/soap/mc_project_api.php @@ -181,23 +181,38 @@ function mc_projects_get_user_accessible( $p_username, $p_password ) { $t_result = array(); foreach( user_get_accessible_projects( $t_user_id ) as $t_project_id ) { - $t_project_row = project_cache_row( $t_project_id ); - $t_project = array(); - $t_project['id'] = $t_project_id; - $t_project['name'] = $t_project_row['name']; - $t_project['status'] = mci_enum_get_array_by_id( $t_project_row['status'], 'project_status', $t_lang ); - $t_project['enabled'] = $t_project_row['enabled']; - $t_project['view_state'] = mci_enum_get_array_by_id( $t_project_row['view_state'], 'project_view_state', $t_lang ); - $t_project['access_min'] = mci_enum_get_array_by_id( $t_project_row['access_min'], 'access_levels', $t_lang ); - $t_project['file_path'] = array_key_exists( 'file_path', $t_project_row ) ? $t_project_row['file_path'] : ''; - $t_project['description'] = array_key_exists( 'description', $t_project_row ) ? $t_project_row['description'] : ''; - $t_project['subprojects'] = mci_user_get_accessible_subprojects( $t_user_id, $t_project_id, $t_lang ); - $t_result[] = $t_project; + $t_result[] = mci_project_get_row( $t_project_id, $t_user_id, $t_lang ); } return $t_result; } +/** + * Retrieves project data. + * + * @param int $p_project_id + * @param int $p_user_id + * @param string $p_lang + * + * @return array + * @throws ClientException + */ +function mci_project_get_row( $p_project_id, $p_user_id, $p_lang ) { + $t_project = project_cache_row( $p_project_id ); + + return array( + 'id' => $p_project_id, + 'name' => $t_project['name'], + 'status' => mci_enum_get_array_by_id( $t_project['status'], 'project_status', $p_lang ), + 'enabled' => $t_project['enabled'], + 'view_state' => mci_enum_get_array_by_id( $t_project['view_state'], 'project_view_state', $p_lang ), + 'access_min' => mci_enum_get_array_by_id( $t_project['access_min'], 'access_levels', $p_lang ), + 'file_path' => array_key_exists( 'file_path', $t_project ) ? $t_project['file_path'] : '', + 'description' => array_key_exists( 'description', $t_project ) ? $t_project['description'] : '', + 'subprojects' => mci_user_get_accessible_subprojects( $p_user_id, $p_project_id, $p_lang ), + ); +} + /** * Get all categories of a project. * From 7ab9a6cf1cddde1d0ba440b22aaa067bb2ba540f Mon Sep 17 00:00:00 2001 From: Damien Regad Date: Sat, 17 Feb 2024 00:32:57 +0100 Subject: [PATCH 4/5] New function mci_project_get_versions() Avoid duplicated code in - mc_project_get_versions() - mc_project_get_released_versions() - mc_project_get_unreleased_versions() --- api/soap/mc_project_api.php | 84 ++++++++++--------------------------- 1 file changed, 21 insertions(+), 63 deletions(-) diff --git a/api/soap/mc_project_api.php b/api/soap/mc_project_api.php index 569418da21..c262c3bfbe 100644 --- a/api/soap/mc_project_api.php +++ b/api/soap/mc_project_api.php @@ -369,34 +369,37 @@ function mc_project_rename_category_by_name( $p_username, $p_password, $p_projec * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. * @param int $p_project_id The id of the project to retrieve the versions for. + * @param bool $p_released Released status (one of VERSION_* constants) * * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ -function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { - global $g_project_override; - $t_user_id = mci_check_login( $p_username, $p_password ); - - if( $t_user_id === false ) { - return mci_fault_login_failed(); - } - - if( !project_exists( $p_project_id ) ) { - return ApiObjectFactory::faultNotFound( 'Project \'' . $p_project_id . '\' does not exist.' ); - } - $g_project_override = $p_project_id; - - if( !mci_has_readonly_access( $t_user_id, $p_project_id ) ) { - return mci_fault_access_denied( $t_user_id ); +function mci_project_get_versions( $p_username, $p_password, $p_project_id, $p_released = VERSION_ALL ) { + $t_result = mci_project_initial_checks( $p_username, $p_password, $p_project_id, true ); + if( $t_result !== true ) { + return $t_result; } $t_result = array(); - foreach( version_get_all_rows( $p_project_id, VERSION_ALL ) as $t_version ) { + foreach( version_get_all_rows( $p_project_id, $p_released ) as $t_version ) { $t_result[] = mci_project_version_as_array( $t_version ); } return $t_result; } +/** + * Get all versions of a project. + * + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. + */ +function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { + return mci_project_get_versions( $p_username, $p_password, $p_project_id ); +} + /** * Get all released versions of a project. * @@ -407,29 +410,7 @@ function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_released_versions( $p_username, $p_password, $p_project_id ) { - global $g_project_override; - $t_user_id = mci_check_login( $p_username, $p_password ); - - if( $t_user_id === false ) { - return mci_fault_login_failed(); - } - - if( !project_exists( $p_project_id ) ) { - return ApiObjectFactory::faultNotFound( 'Project \'' . $p_project_id . '\' does not exist.' ); - } - - $g_project_override = $p_project_id; - if( !mci_has_readonly_access( $t_user_id, $p_project_id ) ) { - return mci_fault_access_denied( $t_user_id ); - } - - $t_result = array(); - - foreach( version_get_all_rows( $p_project_id, VERSION_RELEASED ) as $t_version ) { - $t_result[] = mci_project_version_as_array( $t_version ); - } - - return $t_result; + return mci_project_get_versions( $p_username, $p_password, $p_project_id, VERSION_RELEASED ); } /** @@ -442,30 +423,7 @@ function mc_project_get_released_versions( $p_username, $p_password, $p_project_ * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_unreleased_versions( $p_username, $p_password, $p_project_id ) { - global $g_project_override; - - $t_user_id = mci_check_login( $p_username, $p_password ); - - if( $t_user_id === false ) { - return mci_fault_login_failed(); - } - - if( !project_exists( $p_project_id ) ) { - return ApiObjectFactory::faultNotFound( 'Project \'' . $p_project_id . '\' does not exist.' ); - } - $g_project_override = $p_project_id; - - if( !mci_has_readonly_access( $t_user_id, $p_project_id ) ) { - return mci_fault_access_denied( $t_user_id ); - } - - $t_result = array(); - - foreach( version_get_all_rows( $p_project_id, VERSION_FUTURE ) as $t_version ) { - $t_result[] = mci_project_version_as_array( $t_version ); - } - - return $t_result; + return mci_project_get_versions( $p_username, $p_password, $p_project_id, VERSION_FUTURE ); } /** From 856b7c6dfe8de2df6761abcb96590e1c256f4354 Mon Sep 17 00:00:00 2001 From: Damien Regad Date: Sat, 17 Feb 2024 00:36:09 +0100 Subject: [PATCH 5/5] New function mci_project_initial_checks() Avoid duplicated code in - mc_project_get_categories() - mc_project_add_category() - mc_project_delete_category() --- api/soap/mc_project_api.php | 79 +++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/api/soap/mc_project_api.php b/api/soap/mc_project_api.php index c262c3bfbe..5be51511f6 100644 --- a/api/soap/mc_project_api.php +++ b/api/soap/mc_project_api.php @@ -214,29 +214,55 @@ function mci_project_get_row( $p_project_id, $p_user_id, $p_lang ) { } /** - * Get all categories of a project. + * Performs initial checks for Project Categories. * * @param string $p_username The name of the user trying to access the categories. * @param string $p_password The password of the user. - * @param int $p_project_id The id of the project to retrieve the categories for. + * @param int $p_project_id The id of the project for which to add the category. + * @param string $p_readonly Access: True for readonly, False for manage project * - * @return array|RestFault|SoapFault An array of category names + * @return RestFault|SoapFault|true True if caller can proceed */ -function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { +function mci_project_initial_checks( $p_username, $p_password, $p_project_id, $p_readonly ) { global $g_project_override; - $t_user_id = mci_check_login( $p_username, $p_password ); + $t_user_id = mci_check_login( $p_username, $p_password ); if( $t_user_id === false ) { - return mci_fault_login_failed(); + return mci_fault_access_denied(); } if( !project_exists( $p_project_id ) ) { return ApiObjectFactory::faultNotFound( 'Project \'' . $p_project_id . '\' does not exist.' ); } + $g_project_override = $p_project_id; - if( !mci_has_readonly_access( $t_user_id, $p_project_id ) ) { - return mci_fault_access_denied( $t_user_id ); + if( $p_readonly ) { + if( !mci_has_readonly_access( $t_user_id, $p_project_id ) ) { + return mci_fault_access_denied( $t_user_id ); + } + } else { + if( !mci_has_access( config_get( 'manage_project_threshold' ), $t_user_id, $p_project_id ) ) { + return mci_fault_access_denied(); + } + } + + return true; +} + +/** + * Get all categories of a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * + * @return array|RestFault|SoapFault An array of category names + */ +function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { + $t_result = mci_project_initial_checks( $p_username, $p_password, $p_project_id, true ); + if( $t_result !== true ) { + return $t_result; } $t_result = array(); @@ -258,20 +284,9 @@ function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { * @return int|RestFault|SoapFault Id of the new category */ function mc_project_add_category( $p_username, $p_password, $p_project_id, $p_category_name ) { - global $g_project_override; - $t_user_id = mci_check_login( $p_username, $p_password ); - - if( $t_user_id === false ) { - return mci_fault_access_denied(); - } - - if( !project_exists( $p_project_id ) ) { - return ApiObjectFactory::faultNotFound( 'Project \'' . $p_project_id . '\' does not exist.' ); - } - $g_project_override = $p_project_id; - - if( !mci_has_access( config_get( 'manage_project_threshold' ), $t_user_id, $p_project_id ) ) { - return mci_fault_access_denied(); + $t_result = mci_project_initial_checks( $p_username, $p_password, $p_project_id, false ); + if( $t_result !== true ) { + return $t_result; } return category_add( $p_project_id, $p_category_name ); @@ -287,22 +302,10 @@ function mc_project_add_category( $p_username, $p_password, $p_project_id, $p_ca * * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. */ -function mc_project_delete_category ( $p_username, $p_password, $p_project_id, $p_category_name ) { - global $g_project_override; - $t_user_id = mci_check_login( $p_username, $p_password ); - - if( $t_user_id === false ) { - return mci_fault_access_denied(); - } - - if( !project_exists( $p_project_id ) ) { - return ApiObjectFactory::faultNotFound( 'Project \'' . $p_project_id . '\' does not exist.' ); - } - - $g_project_override = $p_project_id; - - if( !mci_has_access( config_get( 'manage_project_threshold' ), $t_user_id, $p_project_id ) ) { - return mci_fault_access_denied(); +function mc_project_delete_category( $p_username, $p_password, $p_project_id, $p_category_name ) { + $t_result = mci_project_initial_checks( $p_username, $p_password, $p_project_id, false ); + if( $t_result !== true ) { + return $t_result; } # find the id of the category