Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

MNET 2.0

From MoodleDocs
Revision as of 13:36, 14 July 2021 by David Mudrak (talk | contribs) (Text replacement - "<code php>" to "<syntaxhighlight lang="php">")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Introduction

This page attempts to summarise the changes in MNET between Moodle 1.9 and Moodle 2.0, both from an administrative perspective, and a code perspective.

There are still things to do before 2.0 is released, so this page is a work in progress.

See this list for all closed 2.0 MNET bugs.

Backwards Compatibility Breaks

Plugins registering MNET services

It used to be that the plugins that needed to export mnet services used a mnet_publishes() method on the class (static or not). This led to a list of hard coded plugins that supported it, and in some cases auth factory involvement, just to get a list of the RPC functions available.

This has now changed to a file containing an array, in db/mnet.php, similar to lib/db/services.php. This file looks something like this (example from the Mahara portfolio plugin):

$publishes = array(
    'pf' => array(
        'apiversion' => 1,
        'classname'  => 'portfolio_plugin_mahara',
        'filename'   => 'lib.php',
        'methods'    => array(
            'fetch_file'
        ),
    ),
);
$subscribes = array(
    'pf' => array(
        'send_content_intent' => 'portfolio/mahara/lib.php/send_content_intent',
        'send_content_ready'  => 'portfolio/mahara/lib.php/send_content_ready',
    ),
);

Note that there is a unsymmetricality between the methods that are published and the methods that are subscribed to. This is new .

This also resulted in two new tables. The old tables, mnet_rpc and mnet_service2rpc relate to the methods that are being published. The new tables, mnet_remote_rpc and mnet_remote_service2rpc relate to the methods that are being subscribed to.

See the following bugs about this:

Method signatures

The method signature code used to use a string tokeniser to parse the php files that contained mnet services and store information about them in the database. This was unreliable and slow. We've switched to using php5's reflection utilities, which gives us some information about the code, and the Zend_Server Reflection to get the rest. This uses the native php5 reflection, as well as parsing the phpdoc blocks to find information about the types of function arguments, and the return values.

Important: this means that you must write phpdocs in the correct format, otherwise a php warning will be generated

Because of this, we can now reliably include both argument types and return value information in the method signature, where previously only arguments had been included (and in the case of no arguments, the return value had previously been erroneously used).

This means that before where the method signature looked like this:

array(
    array(
        'type' => 'string',
        'description' => 'something here',
    ),
    array(
        /* ... */
    ),
    /* ... */
)

it now looks like this:

array(
    'parameters' =>  array(
        array(
            'name' => 'token',
            'type' => 'string',
            'description' => 'something here',
        ),
        array(
            /* ... */
        ),
        /* ... */,
    ),
    'return' => array(
        'type' => 'string',
        'description' => 'something here',
    ),
)

Which, although it is unarguably more informative and clearer, is a backwards compatibility break. This information is what is sent as the response to the system/methodSignature xmlrpc method. The only place this is used within Moodle, however, is in the old testclient.php, which was present in code, but not linked to from anywhere. This has been changed and is covered under Administrative changes.

See the following bugs about this:

Other code changes

Removal of all MNET globals

There were two regularly used MNET globals, $MNET and $MNET_REMOTE_CLIENT. These have both been removed, and replaced with get_mnet_environment and get_mnet_remote_client functions, which are available in the global scope. The mnet remote client object is only set at the start of mnet/xmlrpc/server.php, and if it is attempted to be accessed outside of the mnet xmlrpc server environment, an error will occur. This will be a debugging() level error in the case of trying to get the mnet remote client object, and an exception if trying to set it.

The last MNET global was only used in one place, and it related to the jump url of a given user. This was used in rewriting urls in a preg_replace_callback in email_to_user. This has been replaced with no global and a partially bound function. PHP has no native partial binding, but a workaround has been recently added to HEAD.

See the following bugs about this:

Conditional MNET environment bootstrapping

Previously any time you included mnet/lib.php, the mnet environment was bootstrapped. This is not ideal as it adds a lot of unnecessary overhead. Now any time you need any bit of the mnet environment, you must do $mnet = get_mnet_environment. Note that this replaces the old $MNET global, but it is no longer always bootstrapped for you.

See the following bug about this:

Removal of library code from mnet/xmlrpc/server.php

mnet/xmlrpc/server.php used to contain both functional code and library code, and I always found it annoying reading through what should have been a simple script, which was hundreds of lines long, so I moved all the functions into mnet/xmlrpc/serverlib.php in case they needed to be reused.

Better debugging

There is now an mnet_debug function which will print to the error log. MNET previously used trigger_error in places, which raises a PHP-level notice/warning/error. This is not helpful in all cases, because of ini settings, or log targets. In particular if php errors are going to STDOUT, this will cause problems in the XMLRPC responses. The mnet_debug function takes any sort of argument (it will recursively call itself for objects and arrays) and a debuglevel. This is controlled by $CFG->mnet_rpcdebug, which is a config.php only setting (and has been there since before the MNET overhaul)

Administrative changes

New Networking Test Client

Previously there was a hidden MNET test client that could only be accessed via url directly by administrators. This has been cleaned up, rewritten to work with the method signature and placed under the Development Menu in the main Administration Block. This can be used to perform introspection on remote hosts and find out what methods are available and what their method signatures are. It is very helpful for debugging MNET.

This was done as part of MDL-21261

Removal of 'auto create users' configuration option

Under the configuration screen for the MNET authentication plugin, there was previously a setting called 'auto add remote users'. As far as I can understand, there was never a case where this should have been off, so it has been removed now.

See the following forum post: http://moodle.org/mod/forum/discuss.php?d=141491 and the bug: MDL-21327

Reworked MNET administration screens

Most of admin/mnet has been updated to use Moodle Forms and the new Output API. This should not result in functional changes, but there may be some smaller aesthetic ones. Not all screens have been rewritten yet.

The relevant bug is MDL-21256