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

[Mike Sheldon]

Hi all,

 Below is a request for comments from P. J. regarding his new plugin
system project. (Forwarded due to the mailing list being a bit broken).

> -------- Original Message --------
> Subject: RFC: Initial Design Work on Events and Plugins Systems
> Date: Thu, 09 Jun 2011 04:11:37 -0400
> From: P. J. McDermott <address@hidden>
> To: address@hidden
> 
> 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.
> 
> E-mail:        address@hidden
> Freenode IRC:  pehjota
> Microblogging: http://identi.ca/pehjota
> Gitorious:     https://gitorious.org/~pehjota
> 
> 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