/ 
Wiki-Toolkit-Store-Mediawiki-0.06
River stage zero No dependents
/ Wiki::Toolkit::Store::Mediawiki

NAME

Wiki::Toolkit::Store::Mediawiki - Mediawiki (MySQL) storage backend for Wiki::Toolkit

VERSION

Version 0.06

REQUIRES

Subclasses Wiki::Toolkit::Store::Database.

SYNOPSIS

Implementation of Wiki::Toolkit::Store::Database which reads and writes to a Mediawiki 1.6 database running in MySQL. This is module is intended to be capable of running concurrently with a Mediawiki 1.6 installation without data corruption. That said, use it at your own risk.

If you are looking for a general Wiki implementation, you might be better off looking at Wiki::Toolkit::Kwiki. It is simpler, more general, and does not require the database to be initialized by outside software. Currently, initializing the database for this module requires a working (PHP) Mediawiki installation.

I initially wrote this module because I was sick of running both PHP and Perl on my web server so that I could have the only wiki I could find with the full featureset I wanted running in parallel with the Perl scripts which generate the rest of my content dynamically. Generating my Perl content was much faster than my Mediawiki installation and I like Perl better, so PHP lost. Converting the old Mediawiki database into a format that a less fully featured wiki could read looked generally unrewarding, so here we are.

All date and time values are returned as Time::Piece::Adaptive objects. This should be transparent for most uses.

See Wiki::Toolkit::Store::Database for more on the general API.

METHODS

check_and_write_node

  $store->check_and_write_node (node     => $node,
				checksum => $checksum,
                                %other_args);

Locks the node, verifies the checksum, calls write_node_post_locking with all supplied arguments, unlocks the node. Returns 1 on successful writing, 0 if checksum doesn't match, croaks on error.

Note: Uses MySQL's user level locking, so any locks are released when the database handle disconnects. Doing it like this because I can't seem to get it to work properly with transactions.

new

Like the new function from Wiki::Toolkit::Store::MySQL, but also requires a `wikiname' argument.

list_all_nodes

Like the parent function, but accepts metadata_is, metadata_isnt, limit, & offset arguments.

list_recent_changes

Like the parent method, but the limit argument may be used in conjunction with the others (since, days, and between_days are still mutually exclusive). A new, $args{between_secs} argument is also processed. Its contents should be two unix timestamps.

list_unmoderated_nodes

$store->list_unmoderated_nodes (only_where_latest => 0);

Like the Wiki::Toolkit::Store::Database function of the same name, returns the list of nodes which have not been moderated (in Mediawiki context, this is the list of nodes that have revisions that have not had their "patrolled" bit set).

only_where_latest defaults to 0 and, when set, returns revisions iff they are both the most recent revision of a node and remain unmoderated. i.e., there will be at most one entry returned per node and a node with a moderated latest edit but which has older, unmoderated edits, will not appear in the list.

set_node_moderation

This method's concept has no parallel in Mediawiki.

moderate_node

$store->moderate_node (version => $version);

Give a version number (rc_this_oldid from recent changes), mark it as patrolled. If the revisions no longer exists in the recent changes table, silently ignore this.

set_node_restrictions

$store->set_node_restrictions (name => $nodename, username => $username, set => %restrictions, %otherargs);
WHERE
%restrictions is of the form $restriction{restrictionType} = @affectedGroups;

Requires a node name or page id, and at least one set restriction argument. The method will add or remove the permissions for the specified user groups to the 'page_restriction' field for the page corresponding to the node name given.

delete_node

This method is unimplemented due to lack of support for archival and logging of deleted pages from Wiki::Toolkit.

Please see the delete_page documentation for the deletetion of nodes as is comparable to the Mediawiki method of node removal.

delete_page

$store->delete_page ($name, $comment, $edit_type, $username, $ip);
OR 
$store->delete_page ($name, $comment, $edit_type, $username, $ip, $version);

Given the node name, a comment about deletion, user name, and user IP this will 'delete' a page and its history from the wiki. If also given a version number, only the specified revision will be removed.

This moves all or specified revisions of a page to the archive table, removes all related rows from recentchanges/page/revision, and adds a row to recentchanges noting the deletion.

restore_page

    $store->restore_page (name => $name, revisions => \@revisions,
			  username => $username, ip => $ip);

Given the node name, this will restore all versions of a 'deleted' wiki page. If given a version number or numbers, it will restore all 'deleted' revisions selected.

If a new page with the same name has been created since the last delete, the revisions will be restored to history, but the new most recent page will not change.

This move revisions of a page from archive and repopulates revision/page with the appropriate data. It then adds a log entry into recentchanges to denote that there was a restoration.

list_archived_pages

$store->list_archived_pages (name => $name);

Loads and returns the list of deleted pages from the archive table.

get_previous_version

$store->get_previous_version ($node_name, $node_version, %other_args);

Given a version number, returns the previous version for the given node. This function is necessary because mediawiki gives every revision of every page a version number which is unique across all pages.

Techincally, node name shouldn't be necessary here, but it allows for a faster search and you probably have it. Not requiring it would be an easy hack.

get_next_version

$store->get_next_version ($node_name, $node_version, %other_args);

Given a version number, returns the next version for the given node. This function is necessary because mediawiki gives every revision of every page a version number which is unique across all pages.

Techincally, node name shouldn't be necessary here, but it allows for a faster search and you probably have it. Not requiring it would be an easy hack.

get_current_version

$store->get_current_version ($node);
$store->get_current_version (name => $node, %other_args);

Given a node, returns the current (most recent) version, or undef, if the node does not exist.

get_oldest_version

$store->get_oldest_version ($node);
$store->get_oldest_version (name => $node, %other_args);

Given a node, returns the oldest (first non-archived) version, or undef, if the node does not exist.

$config->{store}update_links( name => $node, links=> \@links_to );

Given a node and a list containing internal, external, and template links, update the three link tables.

write_node_post_locking

Like the parent function, but works with the mediawiki DB.

node_exists

$store->node_exists ($node);
$store->node_exists (name => $node, %other_args);

Like the parent function of the same name, but much faster. Really just a wrapper for get_current_version, returns the current version number when it exists and undef otherwise.

# List all nodes that link to the Home Page.
my @links = $store->list_backlinks (node => "Home Page");
# List all nodes that have been linked to from other nodes but don't
# yet exist.
my @links = $store->list_dangling_links;

Each node is returned once only, regardless of how many other nodes link to it. Nodes are be returned unsorted.

# List all nodes that have been linked to from other nodes but don't
# yet exist, with a reference count.
foreach my $link ($store->list_dangling_links_w_count)
{
  print "Missing `", $link->[0], "' has ", $link->[1], " references.\n";
}

Nodes are returned sorted primarily by the reference count, greatest first, and secondarily in alphabetical order.

get_user_groups $config{store}->get_user_groups(name => $user_name); or $config{store}->get_user_groups(id => $user_id); or $config{store}->get_user_groups();

Given a valid user name, or user id, this function will return an array of the group names for the groups the user belongs to.

Given no arguments it will return an array of available group names.

get_user_info

  my ($username, $email_validated, $token)
	= $store->get_user_info (name => $username,
				 password => $password,
				 fields => [name, email_authenticated,
					    token],
				 %other_args);

Given a user name, return the requested fields if the user exists and undef, otherwise. Given a password or a token, undef is also returned if the specified password or token is incorrect.

The list of fields to return defaults to name, email_authenticated, & token.

The returned user name may be different from the one passed in when $args{ignore_case} is set.

When an email_token is supplied and validated, the user's email is automatically marked as authenticated in the database.

add_to_block_list

my @errmsgs = $store->add_to_block_list (blockee => $b, expiry => $e,
                                         reason => $r);

Add new user or ip/netmask to the ipblocks table.

blockee can be either a username that must exist in the user table, or an ip address with an optional ip mask. expiry the date for when the block expires. This should be either seconds since the epoch or a Time::Piece:Adaptive. reason will be the moderators reason for the blocking.

create_new_user

my @errmsgs = $store->create_new_user (name => $username, password => $p);

Create a new user. name and password are required arguments. Optional arguments are email & real_name.

Returns a potentially empty list of error messages.

update_user

Like create_user, except only either name or id, and one field to update, are required arguments.

schema_current

Overrides the parent function of the same name. At the moment it only returns (0, 0).

get_interwiki_url

$url = $store->get_interwiki_url ($wikilink);

Converts an interwiki link (like Wikipedia:Perl) to a URL (in this example, something like http://en.wikipedia.org/wiki/Perl), or returns undef if $wikilink does not appear to refer to a known wiki. This match is always case insensitive because users are often careless.

SEE ALSO

Wiki::Toolkit::Kwiki
Wiki::Toolkit::Formatter::Mediawiki
Wiki::Toolkit
Wiki::Toolkit::Store::Database
Wiki::Toolkit::Store::MySQL
Time::Piece::Adaptive

AUTHOR

Derek Price, <derek at ximbiot.com>

BUGS

Please report any bugs or feature requests to bug-cgi-wiki-store-mediawiki at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Wiki-Toolkit-Store-Mediawiki. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Wiki::Toolkit::Store::Mediawiki

You can also look for information at:

ACKNOWLEDGEMENTS

My thanks go to Kake Pugh, for providing the well written Wiki::Toolkit and Wiki::Toolkit::Kwiki modules, which got me started on this.

COPYRIGHT & LICENSE

Copyright 2006 Derek Price, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.