some adjustments to logging methods

opencaching · Nov 17, 2018 · 49cb964 · 49cb964
1 parent 57080a8
commit 49cb964
Show file tree

Hide file tree

Showing 7 changed files with 76 additions and 86 deletions.
diff --git a/okapi/core/Okapi.php b/okapi/core/Okapi.php
@@ -1085,7 +1085,7 @@ public static function cache_size2_to_oxsize($size2)
     private static $nonsubmittable_log_types = [   # not implemented in services/logs/submit
         # OCPL only
         'Moved' => 4,
-        'Needs maintenance' => 5,
+        'Needs maintenance' => 5,       # submittable by type=Comment&needs_maintenance2=true
         'Maintenance performed' => 6,   # see https://github.com/opencaching/okapi/issues/548
         'OC Team comment' => 12,
 
@@ -1128,7 +1128,7 @@ public static function logtypeid2name($id)
             return $reverted[$id];
 
         # There are lots of strange log types in OCPL databases.
-        # OCPL websites display and export them as 'Comment's.
+        # OCPL websites ignore them or treat them as 'Comment's.
 
         return "Comment";
     }

diff --git a/okapi/locale/de_DE/LC_MESSAGES/okapi_messages.mo b/okapi/locale/de_DE/LC_MESSAGES/okapi_messages.mo
diff --git a/okapi/locale/de_DE/LC_MESSAGES/okapi_messages.po b/okapi/locale/de_DE/LC_MESSAGES/okapi_messages.po
@@ -2,8 +2,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: OKAPI\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-11-17 14:31+0100\n"
-"PO-Revision-Date: 2018-11-17 14:31+0100\n"
+"POT-Creation-Date: 2018-11-17 20:28+0100\n"
+"PO-Revision-Date: 2018-11-17 20:29+0100\n"
 "Last-Translator: following <following@online.de>\n"
 "Language-Team: following <following@online.de>\n"
 "Language: de\n"
@@ -336,30 +336,37 @@ msgstr ""
 "Deine Empfehlung wurde jedoch ignoriert, weil du keine eigenen Caches "
 "empfehlen kannst."
 
-#: services/logs/submit/WebService.php:225
+#: services/logs/submit/WebService.php:215
+msgid ""
+"You are not the owner of this cache. Only the owner may log status changes."
+msgstr ""
+"Du bist nicht der Besitzer dieses Caches. Nur der Besitzer kann "
+"Statusänderungen loggen."
+
+#: services/logs/submit/WebService.php:228
 #, php-format
 msgid "%s does not allow to unarchive geocaches."
 msgstr "%s erlaubt keine Reaktivierung archivierter Caches."
 
-#: services/logs/submit/WebService.php:237
+#: services/logs/submit/WebService.php:240
 msgid "The geocache must be maintained before it is enabled."
 msgstr "Der Geocache muss gewartet werden, bevor er aktiviert wird."
 
-#: services/logs/submit/WebService.php:301
+#: services/logs/submit/WebService.php:304
 msgid "You have already submitted a log entry with exactly the same contents."
 msgstr ""
 "Du hast bereits einen Logeintrag mit genau dem gleichen Inhalt gemacht."
 
-#: services/logs/submit/WebService.php:317
+#: services/logs/submit/WebService.php:320
 msgid "You have already rated this cache once. Your rating cannot be changed."
 msgstr ""
 "Du hast diesen Cache bereits bewertet. Deine Bewertung ist nicht änderbar."
 
-#: services/logs/submit/WebService.php:330
+#: services/logs/submit/WebService.php:333
 msgid "You have already recommended this cache once."
 msgstr "Du hast diesen Cache bereits empfohlen."
 
-#: services/logs/submit/WebService.php:349
+#: services/logs/submit/WebService.php:351
 #, php-format
 msgid "You don't have any recommendations to give. Find one more cache first!"
 msgid_plural ""
@@ -370,11 +377,11 @@ msgstr[0] ""
 msgstr[1] ""
 "Du musst noch %d Caches finden, um eine weitere Bewertung abgeben zu können."
 
-#: services/logs/submit/WebService.php:413
+#: services/logs/submit/WebService.php:415
 msgid "Event caches cannot \"need maintenance\"."
 msgstr "Event-Caches können keine \"Wartung benötigen\"."
 
-#: services/logs/submit/WebService.php:551
+#: services/logs/submit/WebService.php:553
 msgid "Your cache log entry was posted successfully."
 msgstr "Dein Log wurde veröffentlicht."
 

diff --git a/okapi/services/logs/capabilities/WebService.php b/okapi/services/logs/capabilities/WebService.php
@@ -3,8 +3,7 @@
 namespace okapi\services\logs\capabilities;
 
 use okapi\core\Db;
-use okapi\core\Exception\InvalidParam;
-use okapi\core\Exception\ParamMissing;
+use okapi\core\Exception\BadRequest;
 use okapi\core\Okapi;
 use okapi\core\OkapiServiceRunner;
 use okapi\core\Request\OkapiInternalRequest;
@@ -22,8 +21,7 @@ public static function options()
 
     /**
      * This method redundantly implements parts of logs/submit and logs/edit logic.
-     * It's mostly logic that decides if a CannotPublishException is thrown;
-     * a few cases are about BadRequest (they are annotated below).
+     * It's only logic that decides if a CannotPublishException is thrown.
      *
      * This means:
      *
@@ -33,58 +31,45 @@ public static function options()
      *     2. With every change to the allowed log paramters logic, OKAPI 
      *        developers MUST check if logs/capabilities needs an update.
      *
-     *     3. If developers fail to do so in 'CannotPublishException' cases,
-     *        it will not break anything. Either a new OKAPI feature may not be
-     *        immediatly available to all apps, until we fix it here. Or
-     *        a CannotPublishException may be thrown, informing users that a
-     *        feature is not available.
-     *
-     *     4. If we miss a 'BadRequest' case, we introduce a inconsistency
-     *        between the API specs and services/logs/capabilities. This could
-     *        result in buggy clients. So all the 'BadRequests' in logs/submit,
-     *        logs/edit and LogsCommons need special attention.
+     *     3. If developers fail to do so, it will not break anything. Either
+     *        new OKAPI feature may not be immediatly available to all apps,
+     *        until we fix it here. Or a CannotPublishException may be thrown,
+     *        informing users that a feature is not available.
      **/
 
     public static function call(OkapiRequest $request)
     {
         $result = array();
 
-        # evaluate reference_item
+        # evaluate parameters
 
-        $reference_item = $request->get_parameter('reference_item');
-        if (!$reference_item) throw new ParamMissing('reference_item');
-        $submit = (strlen($reference_item) < 20);
-        $edit = !$submit;
+        $cache_code = $request->get_parameter('cache_code');
+        $log_uuid = $request->get_parameter('log_uuid');
+        $submit = ($cache_code != null);
+        $edit = ($log_uuid != null);
+        if (!($edit xor $submit)) {
+            throw new BadRequest(
+                "Either the 'cache_code' or the 'log_uuid' parameter must be supplied."
+            );
+        }
 
-        try
-        {
-            if ($submit) {
-                $cache_code = $reference_item;
-            } else {
-                $log = OkapiServiceRunner::call(
-                    'services/logs/entry',
-                    new OkapiInternalRequest($request->consumer, $request->token, array(
-                        'log_uuid' => $reference_item,
-                        'fields' => 'cache_code|user|type'
-                    ))
-                );
-                $cache_code = $log['cache_code'];
-            }
-            $cache = OkapiServiceRunner::call(
-                'services/caches/geocache',
+        if ($edit) {
+            $log = OkapiServiceRunner::call(
+                'services/logs/entry',
                 new OkapiInternalRequest($request->consumer, $request->token, array(
-                    'cache_code' => $cache_code,
-                    'fields' => 'type|status|owner|is_found|is_recommended|my_rating'
+                    'log_uuid' => $log_uuid,
+                    'fields' => 'cache_code|user|type'
                 ))
             );
+            $cache_code = $log['cache_code'];
         }
-        catch (InvalidParam $e)
-        {
-            throw new InvalidParam(
-                'reference_item',
-                "There is no accessible geocache or log '".$reference_item."'."
-            );
-        }
+        $cache = OkapiServiceRunner::call(
+            'services/caches/geocache',
+            new OkapiInternalRequest($request->consumer, $request->token, array(
+                'cache_code' => $cache_code,
+                'fields' => 'type|status|owner|is_found|is_recommended|my_rating'
+            ))
+        );
 
         # prepare some common variables
 
@@ -208,14 +193,15 @@ public static function call(OkapiRequest $request)
             $result['can_recommend'] = 'false';
             $result['rcmd_founds_needed'] = null;
         } else {
-            # If the user did not yet find this cache, then for adding a
-            # recommendation the user must either submit a 'Found it' log, or
-            # make (edit) a 'Found it' from another type of log. So the user
-            # adds another found, which decreases the number of additional
-            # founds needed for recommending:
-
             $founds_needed = $user['rcmd_founds_needed'];
-            if (!$cache['is_found']) --$founds_needed;
+            if ($submit || $log['type'] != 'Found it')
+            {
+                # To add a recomendation, the user must either submit a new
+                # 'Found it' log, or change an existing log's type to 'Found it'.
+                # This additional 'Found it' counts for the recommendations:
+
+                --$founds_needed;
+            }
 
             if ($founds_needed > 0) {
                 $result['can_recommend'] = 'need_more_founds';

diff --git a/okapi/services/logs/capabilities/docs.xml b/okapi/services/logs/capabilities/docs.xml
@@ -11,24 +11,18 @@
         preconditions. If a logging feature is not avaible, OKAPI will
         accept the request and return a user-friendly explanation.</p>
     </desc>
-    <req name='reference_item'>
-        <p>One of these:</p>
-        <ul>
-            <li>
-                The code of the geocache to be logged. Available features
-                for <a href='%OKAPI:methodargref:services/logs/submit%'>services/logs/submit</a>
-                will be returned.
-            </li>
-            <li>
-                The UUID of the log entry to be edited. Available features
-                for <a href='%OKAPI:methodargref:services/logs/edit%'>services/logs/edit</a>
-                will be returned.
-            </li>
-        </ul>
-        <p>The returned values depend on the type and state of the
-        geocache, on previous logs and on the OC site. They can change
-        any time.</p>
-    </req>
+    <opt name='cache_code'>
+        <p>The code of the geocache to be logged. Available features for
+        <a href='%OKAPI:methodargref:services/logs/submit%'>services/logs/submit</a>
+        will be returned. Either this <i>or</i> the <b>log_uuid</b> argument
+        must be supplied.</p>
+    </opt>
+    <opt name='log_uuid'>
+        <p>The UUID of the log entry to be edited. Available features for
+        <a href='%OKAPI:methodargref:services/logs/edit%'>services/logs/edit</a>
+        will be returned. Either this <i>or</i> the <b>cache_code</b> argument
+        must be supplied.</p>
+    </opt>
     <common-format-params/>
     <returns>
         <p>A dictionary of the following structure:</p>
@@ -89,7 +83,7 @@
             </li>
         </ul>
         <p>All the <b>can_</b> fields currently are <b>false</b> if a
-        log UUID is supplied as <b>reference_item</b>. OKAPI so far does
-        not implement editing those log properties.</p>
+        log UUID is supplied. OKAPI so far does not implement editing those
+        log properties.</p>
     </returns>
 </xml>
diff --git a/okapi/services/logs/submit/WebService.php b/okapi/services/logs/submit/WebService.php
@@ -210,8 +210,11 @@ private static function _call(OkapiRequest $request)
 
         if (in_array($logtype, array('Ready to search', 'Temporarily unavailable', 'Archived')))
         {
-            if ($user['uuid'] != $cache['owner']['uuid'])
-                throw new BadRequest("The status of a geocache can only be changed by the owner.");
+            if ($user['uuid'] != $cache['owner']['uuid']) {
+                throw new CannotPublishException(_(
+                    "You are not the owner of this cache. Only the owner may log status changes."
+                ));
+            }
 
             if (Settings::get('OC_BRANCH') == 'oc.pl')
             {

diff --git a/okapi/services/users/user/docs.xml b/okapi/services/users/user/docs.xml
@@ -46,7 +46,7 @@
             <li><b>rcmds_given</b> - number of recommendations given,</li>
             <li>
                 <b>rcmds_left</b> - number of additional recommendations the user may
-                give, or <b>null</b> if there is no limit. Can be &lt; 0 if found
+                give, or <b>null</b> if there is no limit. Can be &lt; 0 if "Found it"
                 logs of the user were deleted.
             </li>
             <li>