Details
-
Improvement
-
Status: Closed
-
Low
-
Resolution: Done
Description
Since 27th April 2020, these rules apply:
- Require a single, name-spaced, class (and file) per each external function (params, return and body methods).
- 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.
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:
- execute
- execute_parameters
- execute_returns
- execute_is_deprecated
- etc.
Rationale
- Easier to read and work with
- 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
- Easier testing
- Ability to more easily set new language features (such as declare(strict_types=1);)
- Fits well with our Testing Namespace issue to match individual test cases to individual web services
- Allows for a future move away from naming services in the services.php file by requiring fixed naming, and allowing use of PHP interfaces
- (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
- Require a single, name-spaced, class per external function
- Require that the namespace must be in the format: <component>\external[\optional\sub\namespace]
- 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
- 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
- has a non-specific relationship to
-
MDL-68559 Review recent service names violating service naming rules
-
- Open
-
-
CONTRIB-8076 Warn about external functions being added out of place
-
- Closed
-
-
MDL-71169 Default name for the method implementing the external function
-
- Closed
-
- has to be done after
-
MDLSITE-5667 Coding style ruling about function/method return types and nullables
-
- Closed
-