Tuesday, May 27, 2008

phpwiki - The Wiki for PHP Developers

This month it's time to look at another of those PHP applications I find useful on a daily basis. I like to use "wikis" for documentation for many of the projects I work on. Most of you are probably familiar with the term wiki, coming from the Hawaiian word for quick (wikiwiki). There are quite a few PHP-based wiki tools out there, including mediawiki (which Wikipedia uses), PmWiki and DokuWiki. In this article we will look at PhpWiki, and we'll show you how to configure and use it with your own projects!

Ward Cunningham wrote the first wiki application in 1995 (although similar software had appeared before, he was the first to apply the term "wiki" to it). Since then, wikis have exploded in popularity, as they provide a convenient way for people to collaborate, with edits being easy, and, equally important, all changes that are made are documented and tracked. The most well-known wiki is of course Wikipedia, the wiki encyclopedia. You can see a more complete list of PHP-based wikis on the Wikipedia site.

Which brings us to PhpWiki! PhpWiki's documentation is not particularly good, which should be a warning that installing a wiki is no panacea for a poorly-documented project. At the time of writing, the latest stable version is 1.3.12p1, but the home page mentions that the latest version as 1.3.11p1, and claims to have last been updated in September 2005. Setup is also a bit more finicky than some of the other applications I looked at in earlier articles. Nevertheless, I find the tool useful, and we will look at setting it up and getting it running in this month's article.

Requirements

  • A web server with PHP version 4.0.6 or greater, though of course you should not be running this old a version for security reasons. There are problems with versions from 4.3.9 and earlier which manifest if you have large installations of around 500 pages or more.
  • Perl regular expressions compiled into PHP (it is by default)
  • Database support. PhpWiki supports MySQL, PostgreSQL, Microsoft SQL Server, Oracle 8, Firebird (with PHP 5's PDO) and later version of Oracle (with PDO).
  • The PEAR DB libraries (installed by default), although PhpWiki comes with these bundled if you don't already have them, and it can also use ADODB.

Installing and configuring PhpWiki

Download the tar file, and place it in your webtree. For the purposes of this tutorial, my wiki will sit in the root directory of the greenman.co.za server. Extract the file:

tar -zxvf phpwiki-1.3.12p1.tar.gz
I suggest renaming  the directory from phpwiki-1.3.12 to simply phpwiki, or even just wiki.
mv phpwiki-1.3.12p1 wiki
You can now access  your wiki from a browser: http://greenman.co.za/wiki. Before you can do any editing,  you'll first have to configure everything.

When you first access the wiki and you haven't configured it yet, the configurator will appear (screenshot 1). This is claimed to be experimental, and has a number of minor usability issues, but it's useful for getting started quickly. The configurator page can look intimidating, as there are many, many options. Don't be put off though, as you can leave most of them with their default values. There are only a few that must be populated in order to get started. Here's what you need to change as a minimum to get your wiki working.

  • admin user
  • admin password
  • Database Type (SQL PEAR should work on any installation)
  • SQL Type (MySQL)
  • SQL User (I chose phpbuilder_wiki)
  • SQL Password (I chose phpbuilder_wiki_password)

In order for the configurator to work, it needs to be able to write to the config directory, as it attempts to create a file called config.ini. If, as is likely by default, it can't create this file, it will output the contents (screenshot 2), and you'll need to copy and paste and create the file yourself. The file must be placed in the config directory. You could also assign write permission to the directory beforehand. Perhaps the easiest alternative of all, seeing as the installation process is finicky enough to demand you work in the command line anyway, is to simply make a copy of the default config file: 

cp config-dist.ini config.ini
and edit the  options above. One minor change is that you have to collate the database  authorization data into the variable DATABASE_DSN. With the options I  chose, the variable will look as follows:
DATABASE_DSN = "mysql://phpbuilder_wiki:phpbuilder_wiki_password@localhost/phpbuilder_wiki
Whichever way you  choose to configure PhpWiki, I suggest that any later changes you make get made  in the config.ini file directly. You can access the configurator again, using  your admin username and password, but you'll need to remember to re-enter passwords,  and watch out for encryption issues, making it an annoyance to use. Rather than  do that, I just go straight to the file - if you can use a text editor you'll  find it just as easy.

In this tutorial, I'll assume you're using MySQL. Specific instructions for other databases are found in the doc directory (an INSTALL file with an extension of the name of the database, e.g. INSTALL.pgsql). You'll need to already have an account with permission (such as root) to create new databases and tables, and populate them, or get your hosting company to do this for you if not.

First, create the new database. The database name must match the name you selected earlier with the configurator (I chose phpbuilder_wiki):

mysqladmin -uroot_user -proot_password create phpbuilder_wiki
Next, create a new  user with the correct permissions (I chose a user with the same name as the  database, phpbuilder_wiki,  and a password of phpbuilder_wiki_password):
mysql -uroot_user -proot_password phpbuilder_wiki
GRANT select, insert, update, delete, lock tables
 ON phpbuilder_wiki.*
 TO phpbuilder_wiki@localhost
 IDENTIFIED BY 'phpbuilder_wiki_password';
Next, create the  tables. The statements for doing this are found in the mysql-initialize.sql file in the schemas directory. Assuming that you're in the wiki directory, run the following  command, this time using the username and password created for your wiki:
mysql -uphpbuilder_wiki -pphpbuilder_wiki_password phpbuilder_wiki < schemas/mysql-initialize.sql
After all this,  you're ready to access your wiki from a browser (simply go to the wiki  directory - in my case www.greenman.co.za/wiki). The first time you access it will  display a long list of files (screenshot  3) that are the wiki's default contents. From now on, anytime you  access the wiki you'll be redirected to the home page - http://greenman.co.za/wiki/index.php/HomePage (screenshot  4).

Using phpwiki

Wikis wouldn't be popular if they weren't simple to use. Even the least technically proficient user can get started very quickly. To make a change to a page, simply press Edit, make the changes you want, then press Save. See screenshot 15 for what comes when editing the default home page. Notice that there's only plain text in the textarea, nothing fancy. If you're new to wikis, that what makes them so powerful. Anyone can edit them with almost no technical knowledge. Most wikis have a section called the SandBox, which is designed to allow people to test their editing and get to know the system. It doesn't matter if someone messes it up as it contains no critical data, and after all, it is designed for testing. In our newly-installed wiki, the whole site is basically a sandbox, so we'll stick to editing the home page for now. Add some text at the top of the page (screenshot 16) and view your changes on the home page again (screenshot 17). What could be easier?!

Of course, to make the best use of your editing potential, it helps to learn a few tricks to enable you to format the page nicely and to create links. PhpWiki makes it really simple to add basic formatting, such as bold and italics. Simply highlight the word, and click the bold or italic symbol, just like any ordinary word processor. You'll see that the highlighted text gets surrounded by some characters, and an asterisk before and after the text makes it bold (don't get confused with a single asterisk at the start of the line, which creates a bulleted list), and an underscore for italics (screenshot 18, and screenshot 19 after saving). 

this *text is bold*
*bulleted item 1
*bulleted item 2
this _text is italicised_
You'll soon find  it easier to enter these special text characters as you type rather than  worrying about highlighting with the mouse, and you can then call yourself a  true wiki user. Have a look at the bottom of the edit page for more text that  doesn't appear in the shortcuts above (such as exclamation marks for a heading,  or a hash for a numbered list).

Adding a link can be done in the same way (the special character is a square bracket), but there's an even easier way. You may have noticed that words such as WikiWikiWeb and SandBox are links, though they don't have any special characters around them. The secret here is in the capitalization. If a word starts with a capital letter, and has one or more capital letters later in the word, it's automatically a link. The idea here is to combine two or more words into one page title. Try adding some text, such as TestPageOne and view the results after you've saved (screenshot 20). You'll see that the word is underlined, with a question mark after it. This means it's a link, but the page has not yet been created. Simply click on the question mark, and you're immediately editing the new page. Create the new page, but try not to make the newbie mistake of leaving the default text (Describe [TestPageOne] here.) at the top of the page.

There's more to editing. It doesn't have to be a hit and miss experience. I always preview a page before finally saving it (the page jumps back to the editing part, but the previewed page will be above that). You can also sign in in the bottom right (no authentication is necessary by default) - you may have noticed that I've been signed in if you've been viewing the screenshots. One of the advantages of this is that PhpWiki keeps a record of changes made, and it usually helps if others can see who made the change. If someone makes a change without signing in, their IP is recorded instead, so it's still theoretically possible to track them.

To view all changes made to the system, go back to the home page (by clicking on the logo), and then click RecentChanges (screenshot 21). Assuming you've been doing the same changes I have, you'll notice only one change listed, even though you've actually edited the page three times. The reason for this is that PhpWiki also takes note of the difference between a major change and a minor change. The mechanism for this is the little checkbox you may have noticed beneath the editing textarea that reads This is a minor change. It's unchecked by default when a page is created, and when a page is edited for the first time that day. If you click on the RecentEdits link (at the top of the RecentChanges page, you'll see that all three edits have been recorded. (screenshot 22)

When your wiki gets larger, you may start to find that you're not only interested in links that leave the page you're on (such as TestPageOne leading off HomePage), but also the other way around. When you're on TestPageOne, you may want to know which page(s) link to it. The answer here is provided by the BackLinks button. On any page, click BackLinks, and you'll get a list of all pages that link to that particular page. Try this on your newly created TestPageOne (screenshot 23).

Another commonly used page reveals the edit history of a page. On Wikipedia for example, the history is often as revealing as what's on the front page, especially for controversial topics in the midst of an edit war. You can see a page's history by clicking the PageHistory button (screenshot 24). There are more powerful features related to the history. As a collaboration tool, tracking changes is very important. You can see the difference between any two versions by checking the checkoxes next to those versions. Take a look at the differences between the initial and current versions of the HomePage for example (screenshot 25). You'll also see that you can easily revert to an earlier version (making post-vandalism repairs very easy).

Changing the look

Like so many Open Source applications, it's not only the coders who've contributed, but also the designers. PhpWiki comes with a number of skins. Here's a list of those bundled with PhpWiki:

To change the theme associated with the wiki, open up config.ini, and scroll down to Part Four, which lists all the available themes:

;=========================================================================
;
; Part Four:
; Page appearance and layout
;=========================================================================
 
; THEME
;
; Most of the page appearance is controlled by files in the theme
; subdirectory.
;
; There are a number of pre-defined themes shipped with PhpWiki.
; You may also create your own (e.g. by copying and then modifying one of
; stock themes.)
;
;   THEME = default
;   THEME = MacOSX
;   THEME = smaller
;   THEME = Wordpress
;   THEME = Portland
;   THEME = Sidebar
;   THEME = Crao
;   THEME = wikilens (Ratings)
;   THEME = Hawaiian
;   THEME = SpaceWiki
;   THEME = Hawaiian
;
;
; Problems:
;
;   THEME = MonoBook (WikiPedia) [experimental. MSIE problems]
;   THEME = blog     (Kubrick)   [experimental. Several links missing]
;
THEME = default
Simply change the  uncommented line (lines beginning with a semicolon are commented out) THEME = default to reflect the theme you want, for example THEME = Crao. Note that if you're  experimenting with different themes, you may be thrown by the default caching  behaviour, thinking that the themes are not working. PhpWiki by default uses LOOSE caching, which means that the page is cached until the next time it is edited  (so a theme change is only reflected after a new edit). You can change this  setting to NO_CACHE in Part One of config.ini if it's causing problems.

More configuration

Depending on the nature of your wiki, you may not want just anybody editing, or even viewing, your pages. You have quite a lot of flexibility with regards to this. Take a deeper look in the config.ini file. Part Three is what's relevant here. By default, most options are set to their least strict possibility. ALLOW_ANON_USER is set to true, so users don't have to log in to view the pages. Similarly, ALLOW_ANON_EDIT is also true, so anonymous users can make edits. Even if they do log in, ALLOW_BOGO_LOGIN is set to true, which means that no actual password authentication is performed. There are all sorts of more rigorous alternatives, from Apache authentication, IMAP authentication, LDAP authentication or external database authentication. Have a look at the documentation in the config file for more details.
There are many more options. PhpWiki is certainly flexible. You can create user groups, fine-tune the caching mechanism, implement spamassasin and captcha, persistent sessions and much, much more! Take the time to read through the configuration file carefully. You may find something that makes your life a lot easier.

Conclusion

Although PhpWiki can be finicky to install and configure when compared with other PHP applications, it's a faithful clone of the original WikiWikiWeb, and is more flexible than some of the alternatives. It's a powerful collaboration tool--enjoy using it!

Links

This article originally appeared on PHPBuilder.com.

Posted by at
Categories: ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)