flatPHPbook Plus

Readme for 1.0

Released date: February 3, 2009


Features

This PHP guestbook script was written by Thomas Hettenhausen and it updated by Vincenzo Capuano since 2006.

Visit flatPHPbook @ SourceForge or sitoserio.it for the latest version.

This guestbook stores all of its data in a flat text file, so no database is needed. This makes it easy to use for people who want their own guestbook and have webspace with PHP support, but no access to a MySQL database, which often costs more and is not needed for smaller web projects. That does not mean that you have to live with less comfort - this script offers some features known from other guestbook and bulletin board / forum scripts, among them

You are welcome to help implement the features!
But also to make suggestion ;-)

- Up -


Requirements

This guestbook script does not need much; it basically comes down to this:

I tested it on www.sitoserio.it (on webserver running Linux operative system).

- Up -


Installation / Upgrade

The flatPHPbook archive contains the following files (in alphabetical order):

  1. bannedWords.txt → a very basic file containing some words that are banned from posting, modify if you do not agree with my selection
  2. button.php → the captcha script itself
  3. Changelog.txt → a text file listing the changes between the versions
  4. customFooter.inc.html → file containing any kind of HTML code that is placed right before the closing body tag
  5. customHeader.inc.html → file containing any kind of HTML code that is placed right after the opening body tag
  6. dutch.gif → the little Dutch icon
  7. dutch.lang → the Dutch language pack
  8. email.png → the little email icon
  9. english.gif → the little English icon
  10. english.lang → the English language pack
  11. french.gif → the little French icon
  12. french.lang → the French language pack
  13. german.gif → the little German icon
  14. german.lang → the German language pack
  15. guestbook.css → the default style sheet for the guestbook
  16. guestbook2.css → an other style sheet for the guestbook
  17. guestbook3.css → an other style sheet for the guestbook
  18. guestbook.db → an empty file which will later hold the guestbook data
  19. guestbook.ini → the configuration file for the guestbook script
  20. guestbook.js → the JavaScript functions used with the BBcode buttons
  21. homepage.png → the little homepage icon
  22. icelandic.gif → the little Icelandic icon
  23. icelandic.lang → the Icelandic language pack
  24. index.php → the guestbook script itself
  25. italian.gif → the little Italian icon
  26. italian.lang → the default Italian language pack
  27. LICENSE → the GNU GPL, the license under which this script is released
  28. polish.gif → the little Polish icon
  29. polish.lang → the Polish language pack
  30. README.html → this file
  31. russian.gif → the little Russian icon
  32. russian.lang → the Russian language pack
  33. setCookie.php → language setting script
  34. spanish.gif → the little Spanish icon
  35. spanish.lang → the Spanish language pack
  36. swedish.gif → the little Swedish icon
  37. swedish.lang → the Swedish language pack
  38. welcomeMessage.inc.html → file containing the text displayed above the input fields

Just copy all these files into the same directory on your web space.

After that, you must make your guestbook.db and guestbook.ini files writable for the web server process (guestbook.ini only needs to be writable if you plan to use the web interface for configuration, if you edit the file manually, it is not necessary). With most webhosters that means setting the writable flag for other (since the web server process which will be writing to it is neither run by your account nor by anyone of your group). This would correspond to the CHMOD number 666, making the file readable and writable for all. You can also try if writable for group is enough (664), for me it is.

If it is possible, you set the CHMOD number to the value 755, equivalent to read-write-execute access to the user (owner) and read-execute to the group and all others.

With some webhosters you might have to explicitly flag the script as executable. You will see this is necessary if you know for sure that PHP is enabled for you but you only get to see the code instead of a nice looking guestbook.

To do either, load your favorite FTP program (I use FileZilla on Windows and gFTP on Linux, but every ftp program should be fine), and open the directory where you put these files. Now this is where it is probably different with each FTP program, but usually you right-click on the file index.php and select "Properties / CHMOD" or something similar from the context menu. At the bottom of the new window, you can set so-called flags (read, write, execute) for either user, group and other, and sometimes also a field with a 3-digit number. Experiment until it works, usually you have to set executable for either group or other.

If you are upgrading beware:
Do not overwrite your old guestbook.db file or all your posts will be deleted and gone forever (unless your server contains some undelete feature and you have access to it).
You might also want to make sure to check if you made any update to the index.php file and/or the stylesheet (guestbook.css) instead of creating your own/using a modified copy.

Note:

– from the AntiSpam version 1.0 on, the language file and the INI file are changed;
– in the Plus version 1.0, the INI file is changed again.

- Up -


Configuration

The file index.php is the PHP script itself, but you can of course open it with any text editor you have at hand and take a look at it.

Pretty much at the top, you can see a line reading

$INIfileName = "guestbook.ini";

This points to the configuration file called guestbook.ini. In there I defined the variables that control the behaviour of the scipt. You may of course edit that file with a text editor and change these settings, but if you log in as admin you will be presented with a link to edit the configuration via a web interface. The options you will be able to edit are the following:

General
versionthis is the flatPHPbook script release version number - no need to edit this
gbNamethe guestbook name, this is displayed as the title and headline of the page
delimiterthe special character used to tokenize the parts of a post in the database file - no need to edit this
useCookies if set to "1", the script will use cookies to log the admin in instead of PHP sessions (set to "0" for this) which do not work on all web hosters
CharSetyou can set the default character encoding for the HTML code of the guestbook. Just leave at the default of "ISO-8859-1" if you use regular western (English, Italian, German, French, ...) letters. I you experience problems e.g. with the Russian file (cyrillic alphabet), set to "windows-1251". The official list can be found at the IANA homepage
disableMSSmartTagsif set to "1", prevents Microsoft products like MS Office and the Internet Explorer from creating so called "Smart Tags" (hyperlinks) out of company names mentioned on the page. These get created only for companies Microsoft has on their list for this feature. Set to "0" to allow Smart Tags
useAntiSpamif set to "1", the script will use CAPTCHA image to prevent spammers
useMultiLanguageif set to "1", the buttons for multi-language are displayed. Defaults to "1"
Files
guestbookFilefilename of the guestbook database file where the posts are stored. Defaults to "guestbook.db"
stylesheetFilefilename of the CSS stylesheet. Defaults to "guestbook.css"
javascriptFilefile containing the JavaScript functions that make the buttons work. Defaults to "guestbook.js"
emailIconthe icon/image representing the email address. Defaults to "email.png"
homepageIconthe icon/image representing the homepage. Defaults to "homepage.png"
languageFilethe default language file from which the output texts are read. Defaults to "italian.lang"
welcomeMessagethe default file containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
customHeaderfile containing any kind of HTML code that is placed right after the opening body tag. Defaults to "customHeader.inc.html"
customFooterfile containing any kind of HTML code that is placed right before the closing body tag. Defaults to "customFooter.inc.html"
bannedWordsFilefile containing words that are not allowed in posts, one per line. Defaults to "bannedWords.txt"
Behaviour
displayNewestFirstsorting order for display of entries, "1" for newest first, "0" for oldest first (in both cases, the oldest is labelled 1)
refreshWaitingTimetime to wait in seconds before a refresh on the Thanks-for-posting page
showTotalNumbertoggles display of total number of posts above the list of entries ("0" or "1")
entriesPerPageset to "0" for all entries on a single page, or else to how many you want on one page
separateViewFromSignif set to "1", the form for signing is displayed on another page and not together with the old entries
trackUserIPset to "0" if you do not want to (or it is illegal in your country) log user IP addresses, will log "0.0.0.0" then, else it logs the posters IP address to the database file
timeNotationdetermines the format in which the post date and time is displayed:
"ISO" → "DD-MM-YYYY, H:mm:ss"
"american" → "MM-DD-YYYY, h:mm:ss am/pm"
"german" → "DD.MM.YYYY, H:mm:ss"
"italian" → "DD/MM/YYYY, H:mm:ss"
timeOffsetOnSavethe number of hours that gets added to the time a post was made - at posting time, not display time. Defaults to "0"
tableLayoutdetermines what table layout to use for the guestbook display: "classic" uses the 4-cells layout (2 rows, 2 columns per post) that is the default since release of the first version, "simple" uses only 2 cells
externalLinksTargetdetermines the target of the external links. Defaults to "_top"
customFieldsthe number of custom fields (additional to the standard nickname, email, homepage and comment
customFieldNamesa comma separated list of the names for the custom fields (so it reads something like "City,Country" without the quotation marks)
moderatedPostsif set to "1" instead of "0", posts do not automatically appear in the guestbook, but have to be approved by the site administrator first
wordFilterif set to "1", messages containing words listed in the bannedWordsFile are rejected
Email
sendEmailset to "1" if you want to be notified via email every time a new post is made to your guestbook
fromAddressthe email address the notification is sent from (some mail servers do not accept mails without a valid From: address)
toAddressthe email address the notification is sent to (like the From: address you should probably use your address for this)
SMTPthe SMTP server for sending messages - check with your ISP for this (or open your email programm like Outlook or Mozilla Mail and search for an entry called "SMTP Server" or something like this)
overrideLocalhostonly useful on Unix/Linux web servers - set to "1" if you do not want to use the email service on your web server (usually has some MTA like sendmail, exim or postfix installed), but your regular email account instead. Has no effect on Windows machines, as you need to use your regular account there anyways
BBcode
displayButtonsif set to "1", the buttons for BBcode are displayed; if set to "0" they are not displayed. Does not disable the interpretation of BBcode in messages posted earlier. If enabled, only those buttons explicitly set to "1" below are being displayed
displayWebButtonssets whether the "www" and the "@" buttons for hyperlinks and mailto-links are displayed
displayFormatButtonssets whether the buttons for bold, italic and underlined are displayed
displayColorButtonsets whether the color selector dropdown field is displayed
displaySizeButtonsets whether the size selector dropdown field is displayed
displayImageButtonsets whether the button for linking to an image on the web is displayed
displayCodeButtonsets whether the button for entering preformatted (verbatim) text is displayed
Language_1
1_Filethe language1 file. Defaults to "italian.lang"
1_Iconthe little language1 icon. Defaults to "italian.gif"
1_Titlethe language1 title. Defaults to "Italiano"
1_welcomeMsgfile1 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
1_HTTPcharsetthe charset of the language1. Defaults to "iso-8859-1"
Language_2
2_Filethe language2 file. Defaults to "english.lang"
2_Iconthe little language2 icon. Defaults to "english.gif"
2_Titlethe language2 title. Defaults to "English"
2_welcomeMsgfile2 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
2_HTTPcharsetthe charset of the language2. Defaults to "iso-8859-1"
Language_3
3_Filethe language3 file. Defaults to "french.lang"
3_Iconthe little language3 icon. Defaults to "french.gif"
3_Titlethe language3 title. Defaults to "Français"
3_welcomeMsgfile3 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
3_HTTPcharsetthe charset of the language3. Defaults to "iso-8859-1"
Language_4
4_Filethe language4 file. Defaults to "german.lang"
4_Iconthe little language4 icon. Defaults to "german.gif"
4_Titlethe language4 title. Defaults to "Deutsch"
4_welcomeMsgfile4 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
4_HTTPcharsetthe charset of the language4. Defaults to "iso-8859-1"
Language_5
5_Filethe language5 file. Defaults to "spanish.lang"
5_Iconthe little language5 icon. Defaults to "spanish.gif"
5_Titlethe language5 title. Defaults to "Español"
5_welcomeMsgfile5 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
5_HTTPcharsetthe charset of the language5. Defaults to "iso-8859-1"
Language_6
6_Filethe language6 file. Defaults to "dutch.lang"
6_Iconthe little language6 icon. Defaults to "dutch.gif"
6_Titlethe language6 title. Defaults to "Nederlands"
6_welcomeMsgfile6 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
6_HTTPcharsetthe charset of the language6. Defaults to "iso-8859-1"
Language_7
7_Filethe language7 file. Defaults to none
7_Iconthe little language7 icon. Defaults to none
7_Titlethe language7 title. Defaults to none
7_welcomeMsgfile7 containing the text displayed above the input fields. Defaults to none
7_HTTPcharsetthe charset of the language7. Defaults to none
Language_8
8_Filethe language8 file. Defaults to none
8_Iconthe little language8 icon. Defaults to none
8_Titlethe language8 title. Defaults to none
8_welcomeMsgfile8 containing the text displayed above the input fields. Defaults to none
8_HTTPcharsetthe charset of the language8. Defaults to none

Just edit these values to your liking, but be warned: I do not have any checks in there to catch problems if you set e.g. the number of posts per page to below zero - this is not something someone from outside is going to hack, and I think you will be wise enough to fill in valid numbers. After all, you want this to work...

Just above the line mentioned above in the file index.php, you will find the two lines setting the admin username and password,

$adminusername = "admin"; // the administrator username who can delete posts
$adminpassword = "123456" ; // the corresponding password

and, as noted in the code as well, you really should change $adminusername and $adminpassword to something else.

The file guestbook.css is a CSS file for the guestbook. If you know how to write HTML and used CSS yourself, go ahead and play with it. This is just regular CSS, no magic involved. Make the guestbook fit your own webpage with this. If you do not know what CSS is, either be daring and play around, or go learn something about it first. There are some pretty good online tutorials for CSS and HTML.

The file guestbook.js contains the JavaScript functions for the buttons: the ones insert the BBcode into the message and those that make the help appear when hovering over the buttons. The same caveat as with the CSS applies: if you don't know this, you might break something while playing around with it.

- Up -


Misc

This PHP guestbook script was written by Thomas Hettenhausen and it updated by Vincenzo Capuano since 2006. It is released under the GPL.

Thomas Hettenhausen wrote this little script because he intended to move your web presence from a HTML-only host to one allowing PHP, but not MySQL (a matter of money), and he did not find any suitable PHP-based guestbook. Right now he does have MySQL (found a cheaper host), but hey - that does not mean he cannot finish a project he starts! On the other hand, free guestbook services might have been ok, too, but they usually display advertisements, are often slow in response time (after all, they are free, and their companies do not want to spent lots of money for their free services), and they often are not exactly easy to modify in their appearance, so they never quite fit your web page design.

Vincenzo Capuano updated the flatPHPbook version 1.02 and wrote the AntiSpam version. In this version he added a CAPTCHA AntiSpam Controller, the Multi-Language functionality and the new language packs.

This is the first stable release of flatPHPbook Plus version which updates the Antispam version 2.1. The 1.x line is essentially feature frozen, point releases will see only bugs and/or minor changes. Please do not post questions asking when new version will be available, no release date has been set, but you feel free to suggest new features for the guestbook.

The editor used to write this script is Notepad++. It is a free source code editor (and Notepad replacement), which supports several programming languages, running under the MS Windows environment. Give it a try!

If you like this guestbook, drop me a line and tell me! I would love to hear from installations, and I can also put up links to some of the sites that use it.

- Up -


Appendix A: Interna

Here I will document e.g. the structure of the database file (guestbook.db) for all those who want to edit it manually.

Each line in this file represents a post, new ones being appended at the end of the file. The line consists of the entries in the post, separated by the delimiter stored in the variable $delimiter. The order of the fields is:

  1. nickname
  2. email address
  3. homepage
  4. date and time in Unix timestamp format
  5. IP address of the poster (you might later need it for legal reasons)
  6. the message itself

followed by some possible custom fields, each with the delimiter before it.

A typical line might look like this:

El Gringo::elgringo@provider.com::www.provider.com/elgringo/::1076874034::129.70.102.13::That is a nice guestbook you have! See my homepage [url=www.myhomepage.com]here[/url].

This would show up in the guestbook as follows:

El Gringo 20:40:34, 2004-02-15
  That is a nice guestbook you have! See my homepage here.

- Up -


Appendix B: Localization

It is possible to use a localized version of the script. The following languages are included:

flatPHPbook Plus version Language Packs
LanguageIconVersionCharSetThis translation done by
Dutch1.0iso-8859-1Pieter Bos en Bas van den Bosch
English1.0iso-8859-1Thomas Hettenhausen
French1.0iso-8859-1Susanne Jegge
German1.0iso-8859-1Thomas Hettenhausen
Icelandic1.0iso-8859-1Einar Steinsson
Italian1.1iso-8859-1Vincenzo Capuano
Polishbetaiso-8859-2Adam Potempa
Russianbetawindows-1251Andrey Mikhalchuk
Spanish1.1iso-8859-1Giampiero Mancini
Swedishbetaiso-8859-1Odd Nydren

If you want to do another language, check out the file english.lang. Technically, this is an INI-file containing just one section (ATM) called "General", and then some lines with a variable name and then the appropriate string with which this variable is to be substituted in this language.

Just copy the file, name it to your language (e.g. greek.lang), and then translate the strings. Keep in mind that the strings has to be enclosed in quotes, and may not contain "too" special characters (just try it out...). Also pay attention to where the string is used: the "New post! and " just added a new post to your guestbook!" strings are used in emails and therefore should not contain HTML entities, e.g. like "ä" for "ä" - use the real character or like in this case "ae" as workaround.

For your own use it is of course sufficient to only translate those phrases that regular users will see, but if you did a complete translation please send it in and I can make it available for download for everybody! For credit, just include your name as a comment in the language file (that means on a line starting with a semicolon).

- Up -


Appendix C: Multi-Language

In the second stable release of flatPHPbook AntiSpam version the possibility to select the user's language in front-end side (Multi-Language mode) has been added.

e.g.: if the user clicks on the little Italian icon, it will set the Italian language. So the user will able to use his own language.
NOTE: the language setting should last until the browser is closed.

To use this mode needs to set the INI file in this way:

useCookies = 1
useMultiLanguage = 1

besides to the configuration of the other points (see default values).

For each language it is possible to set the language file (e.g. italian.lang), the language icon (e.g. italian.gif), the language title (e.g. Italiano), the welcome message file (e.g. welcomeMessageITA.html) and the typical charset (e.g. iso-8859-1).

- Up -


Appendix D: AntiSpam

This version uses CAPTCHA images based on a technology created by Vincenzo Capuano. It limits the robots bombarding spams.

A CAPTCHA image shows a random string which the user has to type to submit a form. This is a simple problem for (seeing) humans, but a very hard problem for computers which have to use character recognition, especially, because the displayed string is alienated in a way, which makes it very hard for a computer to decode.

You have probably encountered such tests when signing up for an online email or forum account. The form might include an image of distorted text which you are required to type into a text field.

The idea is to prevent spammers from using web boots to automatically post form data in order to submit feedback comments or guestbook entries containing spam messages. The text in the image is usually distorted to prevent the use of OCR software to defeat the process. Hotmail, PayPal, Yahoo and a number of blog sites have employed this technique.

The CAPTCHA image needs the GD Graphics Library extension to be installed. GD is an open source code library for the dynamic creation of images by programmers. This library was originally developped by Thomas Boutell and is now maintained by Pierre-A. Joye under the umbrella of PHP.net.

- Up -


Credits

The flatPHPbook script was written by Thomas Hettenhausen in 2003.
flatPHPbook @ SourceForge
http://www.hettenhausen.net

This PHP guestbook script was written by Thomas Hettenhausen and it updated by Vincenzo Capuano since 2006.
http://www.sitoserio.it

- Up -


License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

- Up -