CLOSE #24761 Add REST API to retrieve regions

htdocs/api/class/api_setup.class.php

@@ -25,6 +25,7 @@ use Luracast\Restler\RestException;
 
 require_once DOL_DOCUMENT_ROOT.'/main.inc.php';
 require_once DOL_DOCUMENT_ROOT.'/core/class/cstate.class.php';
+require_once DOL_DOCUMENT_ROOT.'/core/class/cregion.class.php';
 require_once DOL_DOCUMENT_ROOT.'/core/class/ccountry.class.php';
 require_once DOL_DOCUMENT_ROOT.'/hrm/class/establishment.class.php';
 
@@ -236,6 +237,107 @@ class Setup extends DolibarrApi
 
 		return $list;
 	}
+	/**
+	 * Get the list of regions.
+	 *
+	 * The returned list is sorted by region ID.
+	 *
+	 * @param string    $sortfield  Sort field
+	 * @param string    $sortorder  Sort order
+	 * @param int       $limit      Number of items per page
+	 * @param int       $page       Page number (starting from zero)
+	 * @param int       $country    To filter on country
+	 * @param string    $filter     To filter the regions by name
+	 * @param string    $sqlfilters Other criteria to filter answers separated by a comma. Syntax example "(t.code:like:'A%') and (t.active:>=:0)"
+	 * @return array                List of regions
+	 *
+	 * @url     GET dictionary/regions
+	 *
+	 * @throws RestException
+	 */
+	public function getListOfRegions($sortfield = "code_region", $sortorder = 'ASC', $limit = 100, $page = 0, $country = 0, $filter = '', $sqlfilters = '')
+	{
+		$list = array();
+
+		// Note: The filter is not applied in the SQL request because it must
+		// be applied to the translated names, not to the names in database.
+		$sql = "SELECT t.rowid FROM ".MAIN_DB_PREFIX."c_regions as t";
+		$sql .= " WHERE 1 = 1";
+		if ($country) {
+			$sql .= " AND t.fk_pays = ".((int) $country);
+		}
+		// Add sql filters
+		if ($sqlfilters) {
+			$errormessage = '';
+			if (!DolibarrApi::_checkFilters($sqlfilters, $errormessage)) {
+				throw new RestException(400, 'Error when validating parameter sqlfilters -> '.$errormessage);
+			}
+			$regexstring = '\(([^:\'\(\)]+:[^:\'\(\)]+:[^\(\)]+)\)';
+			$sql .= " AND (".preg_replace_callback('/'.$regexstring.'/', 'DolibarrApi::_forge_criteria_callback', $sqlfilters).")";
+		}
+
+		$sql .= $this->db->order($sortfield, $sortorder);
+
+		if ($limit) {
+			if ($page < 0) {
+				$page = 0;
+			}
+			$offset = $limit * $page;
+
+			$sql .= $this->db->plimit($limit, $offset);
+		}
+
+		$result = $this->db->query($sql);
+
+		if ($result) {
+			$num = $this->db->num_rows($result);
+			$min = min($num, ($limit <= 0 ? $num : $limit));
+			for ($i = 0; $i < $min; $i++) {
+				$obj = $this->db->fetch_object($result);
+				$region = new Cregion($this->db);
+				if ($region->fetch($obj->rowid) > 0) {
+					if (empty($filter) || stripos($region->name, $filter) !== false) {
+						$list[] = $this->_cleanObjectDatas($region);
+					}
+				}
+			}
+		} else {
+			throw new RestException(503, 'Error when retrieving list of regions');
+		}
+
+		return $list;
+	}
+
+	/**
+	 * Get region by ID.
+	 *
+	 * @param int       $id        ID of region
+	 * @return array    		   Array of cleaned object properties
+	 *
+	 * @url     GET dictionary/regions/{id}
+	 *
+	 * @throws RestException
+	 */
+	public function getRegionByID($id)
+	{
+		return $this->_fetchCregion($id, '');
+	}
+
+	/**
+	 * Get region by Code.
+	 *
+	 * @param string    $code      Code of region
+	 * @return array 			   Array of cleaned object properties
+	 *
+	 * @url     GET dictionary/regions/byCode/{code}
+	 *
+	 * @throws RestException
+	 */
+	public function getRegionByCode($code)
+	{
+		return $this->_fetchCregion('', $code);
+	}
+
 	/**
 	 * Get the list of states/provinces.
 	 *
@@ -464,6 +566,29 @@ class Setup extends DolibarrApi
 		return $this->_fetchCcountry('', '', $iso, $lang);
 	}
 
+	/**
+	 * Get region.
+	 *
+	 * @param int       $id        ID of region
+	 * @param string    $code      Code of region
+	 * @return array 			   Array of cleaned object properties
+	 *
+	 * @throws RestException
+	 */
+	private function _fetchCregion($id, $code = '')
+	{
+		$region = new Cregion($this->db);
+
+		$result = $region->fetch($id, $code);
+		if ($result < 0) {
+			throw new RestException(503, 'Error when retrieving region : '.$region->error);
+		} elseif ($result == 0) {
+			throw new RestException(404, 'Region not found');
+		}
+
+		return $this->_cleanObjectDatas($region);
+	}
+
 	/**
 	 * Get state.
 	 *