Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-6096

One webservice (external function) per class (voting ends: April 21 00:00 UTC)

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Minor
    • Resolution: Done
    • Component/s: Coding style
    • Labels:

      Description

      Policy: external functions location requirement

      Since 27th April 2020, these rules apply:

      1. Require a single, name-spaced, class (and file) per each external function (params, return and body methods).
      2. Namespace must be in the format: <component>\external[\optional\sub\namespace]

      Background

      Gone are the days of single monolithic files and classes.

      Please, let us move to one web service, and one class, per file.

      See this following example.

      One class, core_table\external\dynamic\get, relates to a single web service, and only contains the functions which relate to that single web service.

      The Web Service is defined here and named core_table_get_dynamic_table_content. It calls the function execute on the get class.

      We can the define functions, like:

      1. execute
      2. execute_parameters
      3. execute_returns
      4. execute_is_deprecated
      5. etc.

      Rationale

      1. Easier to read and work with
      2. Easier migration path for if/when we decide to update our WS. We can more easily make changes web service by web service rather than wholesale
      3. Easier testing
      4. Ability to more easily set new language features (such as declare(strict_types=1);)
      5. Fits well with our Testing Namespace issue to match individual test cases to individual web services
      6. Allows for a future move away from naming services in the services.php file by requiring fixed naming, and allowing use of PHP interfaces
      7. (Andrew's sanity)

      Further rationale relating to future direction of web services

      This change could allow for future improvements to the way in which web services are defined, for example rather than defining a new web service in the services.php, you could simply define a new class:

      Location: mod/assign/classes/external/submission/submit.php
      Namespace: mod_assign\external\submission
      Class name: submit
      Fully-qualified class name: mod_assign\external\submission\submit

      Class signature:

      <?php
       
      declare(strict_types=1);
       
      namespace mod_assign\external\submission;
       
      use core_external\webservice;
      use core_external\local\endpoints\{ajax as ajax_endpoint, mobile as mobile_endpoint};
      use core_external\local\types\readwrite as type_rw;
      use stdClass;
       
      class submit extends webservice implements ajax_endpoint, mobile_endpoint, type_rw {
          public static function execute_parameters(): external_function_parameters {
              return new external_function_parameters(...);
          }
       
          public static function execute(...$args): stdClass {
            return (object) [...];
          }
       
        public static function execute_returns(): external_description {
          return new external_multiple_structure(...);
        }
       
        public static function execute_capabilities(): array {
          return [...];
        }
      }
      

      Description coming from the language string: external\submission\submit,mod_assign

      Proposal

      A) Require a single, namespaced, class per external function.
      B) Fix the naming for the functions inside the class to execute


      Voting


      Proposal A

      1. Require a single, name-spaced, class per external function
      2. Require that the namespace must be in the format: <component>\external[\optional\sub\namespace]
      3. Require that only functions for a single web service should exist in the class

      Vote Accept

      Accept proposal A in its entirety

      Vote Reject

      Do not accept the proposal


      Proposal B

      Note: This proposal's results will only be considered should Proposal A be accepted

      1. Require that the method name all new web services is execute

      Vote Accept

      Accept proposal B in its entirety

      Vote Reject

      Do not accept the proposal


        Attachments

          Issue Links

            Activity

              People

              Assignee:
              stronk7 Eloy Lafuente (stronk7)
              Reporter:
              dobedobedoh Andrew Nicols
              Participants:
              Component watchers:
              Marina Glancy, Eloy Lafuente (stronk7)
              Votes:
              2 Vote for this issue
              Watchers:
              16 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: