Added API method to get a single goal (#10305)

* added method to get a goal

* always fetch goal directly to not having to iterate over all goals

* added new changelog entry for devs

4 files changed, 78 insertions, 6 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cace52ee3c..322877da61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ The Product Changelog at **[piwik.org/changelog](http://piwik.org/changelog)** l
 ### New APIs
  * Multiple JavaScript trackers can now be created easily via `_paq.push(['addTracker', piwikUrl, piwikSiteId])`. All tracking requests will be then sent to all added Piwik trackers. [Learn more.](http://developer.piwik.org/guides/tracking-javascript-guide#multiple-piwik-trackers)
  * It is possible to get an asynchronously created tracker instance (`addTracker`) via the method `Piwik.getAsyncTracker(optionalPiwikUrl, optionalPiwikSiteId)`. This allows you to get the tracker instance and to send different tracking requests to this Piwik instance and to configure it differently than other tracker instances.
+ * Added a new API method `Goals.getGoal($idSite, $idGoal)` to fetch a single goal.
 
 ### Internal change
  * `piwik.js`, if you call the method `setDomains` note that that the behavior has slightly changed. The current page domain (hostname) will now be added automatically if none of the given host alias passed as a parameter to `setDomains` contain a path and if no host alias is already given for the current host alias. 
diff --git a/plugins/Goals/API.php b/plugins/Goals/API.php
index 9b24a59c76..1272661543 100644
--- a/plugins/Goals/API.php
+++ b/plugins/Goals/API.php
@@ -53,6 +53,24 @@ class API extends \Piwik\Plugin\API
     const AVG_PRICE_VIEWED = 'avg_price_viewed';
 
     /**
+     * Return a single goal.
+     *
+     * @param int $idSite
+     * @param int $idGoal
+     * @return array An array of goal attributes.
+     */
+    public function getGoal($idSite, $idGoal)
+    {
+        Piwik::checkUserHasViewAccess($idSite);
+        
+        $goal = $this->getModel()->getActiveGoal($idSite, $idGoal);
+
+        if (!empty($goal)) {
+            return $this->formatGoal($goal);
+        }
+    }
+
+    /**
      * Returns all Goals for a given website, or list of websites
      *
      * @param string|array $idSite Array or Comma separated list of website IDs to request the goals for
@@ -75,12 +93,7 @@ class API extends \Piwik\Plugin\API
 
             $cleanedGoals = array();
             foreach ($goals as &$goal) {
-                if ($goal['match_attribute'] == 'manually') {
-                    unset($goal['pattern']);
-                    unset($goal['pattern_type']);
-                    unset($goal['case_sensitive']);
-                }
-                $cleanedGoals[$goal['idgoal']] = $goal;
+                $cleanedGoals[$goal['idgoal']] = $this->formatGoal($goal);
             }
 
             $cache->save($cacheId, $cleanedGoals);
@@ -89,6 +102,17 @@ class API extends \Piwik\Plugin\API
         return $cache->fetch($cacheId);
     }
 
+    private function formatGoal($goal)
+    {
+        if ($goal['match_attribute'] == 'manually') {
+            unset($goal['pattern']);
+            unset($goal['pattern_type']);
+            unset($goal['case_sensitive']);
+        }
+
+        return $goal;
+    }
+
     /**
      * Creates a Goal for a given website.
      *
diff --git a/plugins/Goals/Model.php b/plugins/Goals/Model.php
index 2b35f7947d..66f0d91fea 100644
--- a/plugins/Goals/Model.php
+++ b/plugins/Goals/Model.php
@@ -64,6 +64,17 @@ class Model
         Db::deleteAllRows($table, "WHERE idgoal = ? AND idsite = ?", "idvisit", 100000, array($idGoal, $idSite));
     }
 
+    public function getActiveGoal($idSite, $idGoal)
+    {
+        $idSite = (int) $idSite;
+        $idGoal = (int) $idGoal;
+        $goals  = Db::fetchRow("SELECT * FROM " . $this->table . "
+                                WHERE idsite = $idSite AND idgoal = $idGoal
+                                      AND deleted = 0 LIMIT 1");
+
+        return $goals;
+    }
+
     public function getActiveGoals($idSite)
     {
         $idSite = array_map('intval', $idSite);
diff --git a/plugins/Goals/tests/Integration/APITest.php b/plugins/Goals/tests/Integration/APITest.php
index 7dcb79eef5..b2a1d60e98 100644
--- a/plugins/Goals/tests/Integration/APITest.php
+++ b/plugins/Goals/tests/Integration/APITest.php
@@ -187,6 +187,42 @@ class APITest extends IntegrationTestCase
         $this->assertHasNoGoals();
     }
 
+    /**
+     * @expectedException \Exception
+     * @expectedExceptionMessage checkUserHasViewAccess Fake exception
+     */
+    public function test_getGoal_shouldThrowException_IfNotEnoughPermission()
+    {
+        $idGoal = $this->createAnyGoal();
+        $this->assertSame(1, $idGoal);
+        $this->setNonAdminUser();
+        $this->api->getGoal($this->idSite, $idGoal);
+    }
+
+    public function test_getGoal_shouldReturnNullIfItDoesNotExist()
+    {
+        $this->assertNull($this->api->getGoal($this->idSite, $idGoal = 99));
+    }
+
+    public function test_getGoal_shouldReturnExistingGoal()
+    {
+        $idGoal = $this->createAnyGoal();
+        $this->assertSame(1, $idGoal);
+        $goal = $this->api->getGoal($this->idSite, $idGoal);
+        $this->assertEquals(array(
+            'idsite' => '1',
+            'idgoal' => '1',
+            'name' => 'MyName1',
+            'match_attribute' => 'event_action',
+            'pattern' => 'test',
+            'pattern_type' => 'exact',
+            'case_sensitive' => '0',
+            'allow_multiple' => '0',
+            'revenue' => '0',
+            'deleted' => '0',
+        ), $goal);
+    }
+
     private function assertHasGoals()
     {
         $goals = $this->getGoals();