[Librefm-discuss] RFC: Initial Design Work on Events and Plugins Systems

[P. J. McDermott]

Hey all, apologies in advance for the long message.

For anyone who might not know me, my name is Patrick McDermott, but I
usually go by P. J. (and on Freenode, I'm pehjota).  I applied [1] to
work on GNU FM in the Google Summer of Code, though I wasn't chosen for
the program.  I agreed to do the proposed work anyway.  So I'm working
first on a events/hooks system to respond to user-driven events.  Once
complete, I can add karma and badge implementations to GNU FM to award
users for certain activities.  A full plugins system wasn't in my
proposal, but I'm thinking the hooks engine is already effort along that
path and it would be best to modularize new functionality (e.g. karma
and badges) into discrete and optional plugins.  In the April news [2]
and podcast, Mike Sheldon mentioned that I'd be working on a plugins
system, so that seemed to confirm the idea in my mind.

I've been doing as much of the design work around an events engine and
plugins architecture as I could in these past couple of weeks.
(Unfortunately, I underestimated the workload of two accelerated online
university courses and haven't had as much time as I hoped I'd have.  At
least one of them will be over by the end of June.)  I've identified the
events systems of the following projects as possible references: MyBB
[3], DokuWiki [4], MediaWiki [5], and Drupal [6].

I've scoured the Nixtape and GNUkebox codebases and come up with this
list of 30 hookable events.  The file names and line numbers are the
approximate locations at which I'd call any registered hooks (in two
events, there are two such locations).  I'm defining each event as
happening on the lowest level possible (e.g., I defined editing a user
profile as happening in User::save() at nixtape/data/User.php:158
instead of in the profile editing view at nixtape/user-edit.php:130) to
minimize the duplication of events at higher levels.
    user
        activate
            nixtape/register.php:62
        register
            nixtape/register.php:153
        login (get web session)
            see auth -> {get,destroy} web session
        password reset
            nixtape/reset.php:65
        send password reset request
            nixtape/reset.php:142
        delete
            nixtape/delete-profile.php:70
        send delete request
            nixtape/delete-profile.php:83
        edit
            nixtape/data/User.php:158
    auth
        get web (Nixtape) session (login)
            nixtape/login.php:73
        destroy web session (logout)
            nixtape/login.php:28
        web session check
            nixtape/auth.php:49
            could be used to track visits
        get application session
            nixtape/2.0/index.php:377
        get mobile app session
            nixtape/2.0/index.php:333
        get radio session
            nixtape/data/Server.php:491
        get web service session
            nixtape/data/Server.php:509
            not currently used
        get scrobble session
            nixtape/data/User.php:220
    artist
        add artist tags
            nixtape/data/Artist.php:193
            nixtape/api/TrackXML.php:45
        edit artist
            nixtape/artist-manage.php:68
    album
        add album tags
            nixtape/api/TrackXML.php:45
        create album
            nixtape/data/Album.php:97
    track
        add track tags
            nixtape/api/TrackXML.php:45
        love
            nixtape/api/TrackXML.php:117
        unlove
            nixtape/api/TrackXML.php:142
        ban
            nixtape/api/TrackXML.php:101
        unban
            nixtape/api/TrackXML.php:129
        create track
            nixtape/data/Track.php:102
        edit track
            nixtape/track-add.php:116
    radio
        tune
            see auth -> get radio session
        get playlist
            nixtape/radio/radio-utils.php:218
    scrobbling/submissions
        handshake
            gnukebox/submissions/1.1/handshake.php:70
            gnukebox/submissions/1.2/handshake.php:80
        update now playing
            gnukebox/nowplaying/1.2/index.php:91
        submit track
            gnukebox/submissions/1.2/index.php:192
A list similar to this (perhaps automatically generated by a script that
reads through the GNU FM codebase) would of course be included in the
events system documentation.  In naming the events, I propose a
convention similar to that of MyBB [3]; that is, events would be grouped
by function (as they mostly are in this list), the first part of an
event's identifier would indicate its function group, identifiers would
be in lowercase, and word boundaries in identifiers would be delimited
by underscores.

I think there should also be events for the ~30 views (e.g. index.php
and user-stats.php) in Nixtape.  But I'm still not sure if the hooks
should be called at the start of the file, on successful rendering of
the view (that is, when $smarty->display() is called), or both.  And
it's not terribly important right now; more events can always be added
later, and I don't need view events for implementations of karma or badges.

Now on to the plugins architecture.  I'm thinking that a plugin loader
can scan some directory (e.g. $component/plugins/ for $component =
{nixtape,gnukebox}) for plugins.  For each plugin found, it would
include a file (e.g. $component/plugins/$plugin/init.php).  That file
should then initialize the plugin and register with the events engine
any hooks that the plugin has.

Since GNUkebox and Nixtape are independent components with separate
functions, the events and plugins systems will have to be duplicated.
In theory, there can be plugins for GNUkebox and plugins for Nixtape.
For example, consider the proposed karma functionality.  A GNUkebox
plugin could give users karma for listening to free music and have an
administration page to control the amount of karma awarded for scrobbles
(nothing is stopping us from using Smarty in GNUkebox, right?).  A
Nixtape plugin could give users karma for tagging free artists, etc;
show karma amounts on user profiles and perhaps leaderboards; and have
an administration page to control karma award amounts.

I still have to design the events engine itself (and its handling of
hook arguments) and the implementation of the plugins system.  But
first, I wanted to share what I've worked out so far and solicit
feedback.  Does anyone have any suggestions or see any problems with my
proposals?  Does the events list appear complete (except for the display
of Nixtape views, as noted)?

Also, I'm considering managing all of my notes on this project in a
publicly-accessible Git repository (probably hosted on Gitorious).  The
revisioning would be useful, and the public access could improve the
transparency in my work.  Thoughts?

Thanks,
P. J.

1:
http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/pehjota/1
2: http://libre.fm/2011/05/news-for-april-2011.html
3: http://wiki.mybb.com/index.php/MyBB_Plugin_Hooks
4: http://www.dokuwiki.org/devel:events
5: http://www.mediawiki.org/wiki/Manual:Hooks
6: http://api.drupal.org/api/drupal/includes--module.inc/group/hooks