[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  namespace core_my\external;
  18  
  19  use core_external\external_api;
  20  use core_external\external_function_parameters;
  21  use core_external\external_single_structure;
  22  use core_external\external_value;
  23  use core_external\external_warnings;
  24  
  25  /**
  26   * External service to log viewed Dashboard and My pages.
  27   *
  28   * This is mainly used by the mobile application.
  29   *
  30   * @package   core_my
  31   * @category  external
  32   * @copyright 2023 Rodrigo Mady <rodrigo.mady@moodle.com>
  33   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34   * @since Moodle 4.3
  35   */
  36  class view_page extends external_api {
  37      /**
  38       * Returns description of method parameters
  39       *
  40       * @return external_function_parameters
  41       */
  42      public static function execute_parameters(): external_function_parameters {
  43          return new external_function_parameters([
  44              'page' => new external_value(PARAM_TEXT, 'My page to trigger a view event'),
  45          ]);
  46      }
  47  
  48      /**
  49       * Execute the My or Dashboard view event.
  50       *
  51       * @param string $page the page for trigger the event.
  52       * @return array
  53       */
  54      public static function execute(string $page): array {
  55          $warnings = [];
  56          $status   = true;
  57          // Validate the cmid ID.
  58          ['page'  => $page] = self::validate_parameters(
  59              self::execute_parameters(), ['page' => $page]
  60          );
  61  
  62          if ($page === 'my') {
  63              $eventname = '\core\event\mycourses_viewed';
  64          } else if ($page === 'dashboard') {
  65              $eventname = '\core\event\dashboard_viewed';
  66          } else {
  67              $status     = false;
  68              $warnings[] = [
  69                  'item'        => $page,
  70                  'warningcode' => 'invalidmypage',
  71                  'message'     => 'The value for the page request is invalid!'
  72              ];
  73          }
  74  
  75          // Trigger my/dashboard view event.
  76          $context = \context_system::instance();
  77          self::validate_context($context);
  78          if ($status) {
  79              $event = $eventname::create(['context' => $context]);
  80              $event->trigger();
  81          }
  82          $result = [
  83              'status'   => $status,
  84              'warnings' => $warnings
  85          ];
  86          return $result;
  87      }
  88  
  89      /**
  90       * Describe the return structure of the external service.
  91       *
  92       * @return external_single_structure
  93       */
  94      public static function execute_returns(): external_single_structure {
  95          return new external_single_structure([
  96              'status'   => new external_value(PARAM_BOOL, 'status: true if success'),
  97              'warnings' => new external_warnings(),
  98          ]);
  99      }
 100  }