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.
- Always use <?php as PHP opening tag. Never user <? and try
to avoid using <?PHP.
- Indent properly, using a tabwidth of 8. This is easy if you use
emacs or nedit.
- Put curly braces in the correct places. They should go on a line
of their own.
- Comment your code (see below).
- Try to seperate logic and presentation.
- Make yourself comfortable with the translation system (see the
README.makedistro in the docs directory of the source code)
- Use underscores in file names to seperate words.
- Use underscores in function names.
- Try to avoid unnecessary file unclusions (see config.php and mainfile.php)
Now for the (former) status quo. The comments are derived
from a mail from Brian W. Brown.
- wild mixture of indentation styles
this is going to change to emacs default cc-mode style
- curly braces sometimes on next line, sometimes not...
this is going to change to emacs default cc-mode style
- no consistent file naming - sometimes underscore, sometimes not
underscores are preferred - keep that in mind when developing new code!
- far too many calls to config.php
will be cleaned up
- dbconnect() called more often then needed
will be cleaned up
- some functions are redeclared during runtime (themesidebox and the likes)
- messy embedding of html and php - using templates or a similar technology would be great
- relatively hard to do heavy redesign (see before...)
the above three points are to be addressed with a theme API
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:
- class
- function
- var
- include and variants
- define
The available variable types, as far as I know, are:
- integer
- float
- string
- boolean
- array
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
*/
- The first line should be short but meaningful.
- The longer explanation may span several lines. Currently HTML
markup is not retained, so try to avoid it.
- An @author statement might be present - see function comments
below for details.
- The @version statement should be used
unchanged except that you of course have to put real dollar
signs into the source - this way it will be substituted through CVS
(and that is why I cannot use the real dollar sign in this text - it
would get substituted.) If you want to know how this looks, look at
this web pages source, first line.
- The @module statement gives the file a more meaningful
name. Usually it should be the filename without the suffix
.php. Dots are not allowed in the name, convert them to
underscore if needed.
- The @modulegroup should be one of the following. If you think a
new group is needed, please email me (better yet the developers
mailing list). We will add it if appropriate.
- action - files that just do something (e.g. the action_* files)
- administration - all files that deal with administration
- calendar - the calendar files (this might go away as soon as the calendar is a plugin)
- content_handling - files that deal with user pages, layout, ...
- core - core files
- misc - stuff that doesn´t fit anywhere else
- theme - all theme related code
- unused - this is for code that is not used but left alone (like the banner code)
- The @package statement should be left unchanged.
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
*/
- The first line should be short but meaningful.
- The longer explanation may span several lines. Currently HTML
markup is not retained, so try to avoid it.
- One @author statement may be present. More than one author
may appear in the stamement, consisting of his/her name and
optionally the email address in lt or gt signs, individual
authors seperated by colons. If given, the email address will be
converted into a hyperlink automagically.
- One or more @param statements describing the arguments the
function expects. They must be given in the order in which they appear
in the function definition.
- A return statement, if the function returns something.
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
-
if $mainfile is not set, mainfile.php and config.php get included
- define a set of core functions
- connect to db using dbconnect()
- set $index = 1
-
include header.php
- include config.php (again?!?!)
- emit doctype
- include banners.php if $banners is true
- include config.php...
- if called directly, include mainfile.php
- call dbconnect() (!?!)
- define core banner functions
- switch according to $op parameter, default is viewbanner()
- define head function (basically just determines what header.php from themes is to be included)
- call head function (the following is true for the provided themes - YMMV)
- include config.php (!?!)
- menu.php is included (see below for details)
- login block is printed
- today´s events are pulled from db and displayed
- if $admin is set, include config.php (?!?), pull admin block from db and display
- include config.php (!?!?), pull lblocks from db and display
- define function themeboxtop (includes config.php...)
- define function themesidebox (includes config.php...)
- include counter.php
- call plug_check(2)
- set $storynum to either $cookie[3] or $top
- select all stories up to limit $storynum from db and bail out if an mysql error occurs
- select main_page_content from db
- show main content using themesidebox()
- show stories using themeindex
- mysql_free_result()
- include footer.php
- define foot function
- call foot()
- include config.php
- determine footer.php to include from themes (the following is true for the provided themes - YMMV)
- display poll block
- display user block
- display right blocks
- display old news
- include config.php
- display small text at bottom of pages
- 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
- if $mainfile is not set, include mainfile.php
- include header.php (see above for what happens)
- if $admin is set, offer link to admin.php (edit page)
- include layout.php
- grab layout for $page_id from db
- switch() according to layout from db
- now comes (almost) the same function repeatedly (6 times) for the different layouts
include config.php (!?!)
- get number of sections and title, output title
- recurse through sections, get contents, output
- include footer.php (see above for what happens)
top of page
what menu.php does
- call menu1(), menu2() or menu3() according to $menu value:
$menu is | function |
<100 | menu1() |
<10000 | menu2() |
<1000000 | menu3() |
- 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.
- function themeplugin($title, $content)
- function themeindex ($aid, $informant, $time, $title, $counter, $topic, $thetext, $notes, $morelink, $topicname, $topicimage, $topictext) {
- function themearticle ($aid, $informant, $datetime, $title, $thetext, $topic, $topicname, $topicimage, $topictext) {
- function themepollbox($title, $content)
- function themesidebox($title, $content)
- function themeboxtop($title)
- function thememainbox($title, $content)
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>