phpWebSite developer documentation

Content

...more is about to come! As phpWebSite currebtly approaches stable status, a lot of the information herein may be obsoleted - hopefully, as this would mean a cleaner code :-)


top of page

Coding style?

Below are some personal comments on the code I found when I joined phpWebSite development. But before you read that, let me introduce you to the preferred coding style.

Now for the (former) status quo. The comments are derived from a mail from Brian W. Brown.


top of page

Commenting the Code - PHPDoc

If you change code and/or write new code you should add appropriate comments. This applies to whole files (so called modules when we talk about procedural code like in phpWS, or classes when talking OO), function/method definitions, included files and important variables.

Always remember: Commenting is important! It helps you to understand other's code faster, makes it easier to understand your own code and is a Good Thing [tm] when it comes to software engineering.

If you used Java, you probably came across javadoc, which generates browseable HTML documentation by extracting specially crafted comments from the sourcecode. There is a similar tool for PHP called (who would have guessed that) PHPDoc. It has been written by Ulf Wendel and may be found in PHP CVS (currently checked in in the PEAR directory) or at http://www.phpdoc.de/. The following is a quick guide to writing the most important types of comments we would like you to use when hacking on phpWebSite..

Aside from module comments (which should come before any code in the file), comments are recognized only if found before a certain keyword. These are:

The available variable types, as far as I know, are:

Module comments

These should appear at the beginning of every file, and help to explain the purpose of the file. Further they give the file a name (module) and put the file in a certain group (a module group). All phpWebSite modules should belong to the package phpWebSite. This might be helpful in the future, if code is distributed with phpWebSite that is not part of the core package (e.g. certain plugins). Module comments apply to classes as well, here they magically turn into class comments. Such a comment looks like this:

/**
 * Short explanation (1 line!)
 *
 * Some more text which explains in more detail
 * what the file does and who might be interested
 * in understanding that.
 *
 * @version [dollar sign]Id[dollar sign]
 * @module modulename
 * @modulegroup group
 * @package phpWebSite
 */

Function comments

These explain in detail what a function does, what parameters it expects and what is returned by the function. Function comments apply to classes as well, here they magically turn into method comments. Such a comment appears directly above a function definition looks like this:

/**
 * Short explanation (1 line!)
 *
 * Some more text which explains in more detail what
 * the function does and who might be interested
 * in understanding that.
 *
 * @author Name <email address>, Name2 <other email address>
 * @param type description
 * @return type description
 */

Class variable and Include file comments

These are simple: They just quickly explain what a class varibale is used for, or what an included file does, or why we need it. These comments may be longer, if you have to explain more (e.g. the $dbp variable in the config file). They should appear just above the corresponding variable or include/require statement. They have to be one line and look like this.

/**
 * Some explanation of the variable or file just below this comment.
 */

Some tips and tricks

Those of you using emacs will notice that c-mode and php-mode know those comments and indent, wrap and colourize them correctly. It might be worth trying to use one of the available javadoc editing tools (I didn't try, but if you do, let me know). You should add a single space character at the end of lines in a multi line comment - otherwise the result might look, uhm, interesting. If something seems odd - DON´T PANIC (42, you remember?). PHPDoc is still a young piece of software, not every error has to be your fault. Finally: I will try to run PHPDoc weekly and put up the results at http://www.k-fish.de/krabutzig/phpwebsite/

Some asked whether comments like the following are possible:

/*******************************************************************
 * Some explanation of the variable or file just below this comment.
 ******************************************************************/

This was meant to make the code better to navigate - but alas it does not work. Err... it works, but the results look rather funny, because the leading line of *´s is included in the generated documentation. Similar things happen to the closing line of *´s. So all I can say is: stick with exactly the format shown above. I hope this will someday be resolved in PHPDoc, until then we have to wait.

Feel free to add more comments (preferably c-style, i.e. start them with //, not #) in your code to explain what you are doing. And if you write even more detailed documentation, feel free to link them to these docs and put them in CVS.


top of page

what happens when index.php is requested

  1. if $mainfile is not set, mainfile.php and config.php get included
    1. define a set of core functions
    2. connect to db using dbconnect()
  2. set $index = 1
  3. include header.php
    1. include config.php (again?!?!)
    2. emit doctype
    3. include banners.php if $banners is true
      1. include config.php...
      2. if called directly, include mainfile.php
      3. call dbconnect() (!?!)
      4. define core banner functions
      5. switch according to $op parameter, default is viewbanner()
    4. define head function (basically just determines what header.php from themes is to be included)
    5. call head function (the following is true for the provided themes - YMMV)
      1. include config.php (!?!)
      2. menu.php is included (see below for details)
      3. login block is printed
      4. today´s events are pulled from db and displayed
      5. if $admin is set, include config.php (?!?), pull admin block from db and display
      6. include config.php (!?!?), pull lblocks from db and display
      7. define function themeboxtop (includes config.php...)
      8. define function themesidebox (includes config.php...)
    6. include counter.php
  4. call plug_check(2)
  5. set $storynum to either $cookie[3] or $top
  6. select all stories up to limit $storynum from db and bail out if an mysql error occurs
  7. select main_page_content from db
  8. show main content using themesidebox()
  9. show stories using themeindex
  10. mysql_free_result()
  11. include footer.php
    1. define foot function
    2. call foot()
      1. include config.php
      2. determine footer.php to include from themes (the following is true for the provided themes - YMMV)
      3. display poll block
      4. display user block
      5. display right blocks
      6. display old news
      7. include config.php
      8. display small text at bottom of pages
  12. save referer information

Wohoo! It seems as if 1 superflous inclusion of config.php has been removed... (no offense :o)


top of page

what happens when content.php is requested

  1. if $mainfile is not set, include mainfile.php
  2. include header.php (see above for what happens)
  3. if $admin is set, offer link to admin.php (edit page)
  4. include layout.php
    1. grab layout for $page_id from db
    2. switch() according to layout from db
    3. now comes (almost) the same function repeatedly (6 times) for the different layouts
      include config.php (!?!)
    4. get number of sections and title, output title
    5. recurse through sections, get contents, output
  5. include footer.php (see above for what happens)


top of page

what menu.php does

  1. call menu1(), menu2() or menu3() according to $menu value:

    $menu isfunction
    <100menu1()
    <10000menu2()
    <1000000menu3()

  2. now print the menu according to it´s level (details are an exercise for the reader :o)


top of page

Themes (header.php and footer.php revisited)

If you look at the themes provided, it is not instantly clear what these files do exactly, and where the functions used within are defined. This doesn´t get better if you discover that some of them are redeclared throughout the files! This will be addressed with a theme API. Keep this in mind when reading the following, it is mostly meant to aid in developing a better scheme.

A (standard) theme currently consists of four PHP files, a CSS file and one image file.

index.php
This is just used for sending the user back to the phpWebSite index page when he tries to browse the theme directory directly.
deflogo.gif
The standard logo that appears in the upper right corner of the page.
style.css
Here the styles used in the system are defined. For some documentation about that see below (not really, though...). If you just want to change colours, fonts and the like, this is the place to experiment.
header.php
This file basically is a HTML file, containing the page´s HTML up to the point where the main content area starts. It contains PHP code to insert the title tag, the $sitename, the $titlebar, the plugins (if any), the login box, events and the left blocks.
footer.php
This file basically is a HTML file, containing the page´s HTML from the point on where the main content area end. It contains PHP code to insert the poll booth, the user block, added right blocks and the past articles. This is done only if $index==1, i.e. when we are on the index page.
theme.php
This file provides some basic functions used in the header and footer files. Aside from themeindex, themeboxtop and themearticle they basically all render a box, having a title and some content. themeboxtop just outputs the beginning of a block (look at the code to understand what I mean). themeindex and themearticle are for displaying an article overview (on the index page) or the actual article.

phpWebSite always prepends a XHTML header, as required by the standards. So you must start with the <head> tag and omit the <body> tag! And it always appends the text contained in $foot1, $foot2, $foot3 to the page and closes the page by appending the closing </body> and </html> tags, so you must omit them as well.


top of page

CSS definitions

this is about...
... to come! We are thinking about a new set of styles to be used for the future theme implementation. So I think it use quite useless to document the current state. Right? I knew you´d agree :-)


Karsten Dambekalns <k.dambekalns@fishfarm.de>