flatPHPbook Plus

Readme for version 2.1

Release date: November 25, 2009


Features

This PHP guestbook script was written by Thomas Hettenhausen and it updated by Vincenzo Capuano since 2006. Also it was greatly updated by Ilya Zverev in 2009.

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

The flatPHPbook archive contains the following files:

  1. index.php → the guestbook script itself
  2. charconv.php → database upgrade and charset conversion script
  3. button.php → the captcha script
  4. .htaccess → file preventing users from seeing configuration files
  5. welcomeMessage.inc.html → file containing the text displayed above the input fields
  6. customFooter.inc.html → file containing any kind of HTML code that is placed right before the closing body tag
  7. customHeader.inc.html → file containing any kind of HTML code that is placed right after the opening body tag
  8. bannedWords.txt → plain text file containing some words that are banned from posting, modify if you do not agree with my selection
  9. guestbook.css → the default style sheet for the guestbook
  10. guestbook2.css → an other style sheet for the guestbook
  11. guestbook3.css → an other style sheet for the guestbook
  12. guestbook.db → an empty file which will later hold the guestbook data
  13. guestbook.ini → the configuration file for the guestbook script
  14. configdesc.ini → configuration properties formatting for the editor
  15. guestbook.js → the JavaScript functions used with the BBcode buttons
  16. email.png → the little email icon
  17. homepage.png → the little homepage icon
  18. README.html → this file
  19. LICENSE → the GNU GPL, the license under which this script is released
  20. Changelog.txt → a text file listing the changes between the versions
  21. lang/ folder → contains translation files and icons

Just copy all these files into the same directory on your web space. Files in bold font are required for normal operation, as well as at least one of .lang files. However it's recommended to unpack all the files, adjust configuration options and then remove unneeded files. Language files can reside in base directory, along with index.php.

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.

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 that, 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.

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.

- Up -


Upgrading

To upgrade the script:

  1. Back up your guestbook.db!
  2. Unpack all files missing in your installation.
  3. Unpack all language files (*.lang), probably overwriting yours. If you have changed some lines, make backup of your language file, and after overwriting copy and paste changed lines into new file. All new translation lines must be present!
  4. Unpack all .php and .js files, overwriting yours. Also unpack configdesc.ini.
  5. If you are upgrading from version 0.9.x, you'll need to update your guestbook.css file.
  6. Unpack documentation: README.html, LICENSE and Changelog.txt.
  7. Edit index.php and change admin login and password.
  8. Open your guestbook in browser, login as administrator and open configuration page.
  9. If you have 500 Server Error message, try removing .htaccess file. It was reported to cause problems on some systems.
  10. Start configuration tool. If the 'upgrade' checkbox is checked (and your old flatPHPbook version was below 1.0), select '(no, thanks)' in charset box, enter the secret word (default value is equal to 123456) and press 'Convert' button.
  11. Return to your guestbook and check if everything is OK.
  12. Old versions had problems with non-iso charset handling. Now only UTF-8 charset is used! If you had other charset before, run conversion tool from configuration page, select old charset (probably 'ISO-8859-1'), enter a secret word and press 'Convert'. Then return to guestbook and check if messages are looking properly. Don't forget to UTFize your welcome messages. If anything is wrong, you can restore database from guestbook.db.bak file. There is failsafe: find getCharset() and getDBCharset() function in index.php and change charsets to your liking. Though it is not recommended.
  13. After you've done converting database, delete charconv.php file — it's of no use now, but it can be executed by hackers.

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 were changed;
– in the Plus version 1.0, the INI file was changed again.
– since Plus version 2.0 the INI could be changed, but upgrades automatically.

- 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
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"
allowAnonymousif set to "1", users can post messages not entering their nicknames. Defaults to "0"
readOnlyif set to "1", posting is turned off. Defaults to "0", of course
nbspBrin older versions line breaks were stored as &nbsp;<br />. If this flag is set to "0" (default), they are stored as <br /> This option was introduced to maintain compatibility.
maxLinksPerPostas the name suggests, contain maximum number of links a post can have. This is basic antispam protection, since most spammers tend to put hundred links in each post. Defaults to 5, recommended value is 3
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"
configDescFileContains types of parameters in configuration file. Defaults to "configdesc.ini"
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 "english.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
entriesPerHistoryPagenumber of entries on pages 2 and higher. Defaults to 'entriesPerPage' value
entriesInRSSnumber of posts included in RSS. Set this to "0" to disable RSS feature
separateViewFromSignif set to "1", the form for signing is displayed on another page and not together with the old entries
signAfterViewif set to "1", the form for signing is placed at the bottom of guestbook
alternateSignLinkif set to "1", the link for signing is displayed both before and after guestbook (if there is no signing form displayed)
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"
"american" → "MM-DD-YYYY, h:mm am/pm"
"german" → "DD.MM.YYYY, H:mm"
"italian" → "DD/MM/YYYY, H:mm"
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"
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
displayEmailsif set to "0" (default), email addresses will be shown only to administrator
forcePreviewif set to "1", users will be forced to preview their messages before posting: 'Submit' button will appear only on preview screen.
displayHomepageif set to "0", homepage input field will be hidden (but homepage links will still be visible)
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 "english.lang"
1_Iconthe little language1 icon. Defaults to "english.gif"
1_Titlethe language1 title. Defaults to "English"
1_welcomeMsgfile1 containing the text displayed above the input fields. Defaults to "welcomeMessage.inc.html"
Language_2 through Language_8
2_File etc.the same as for Language_1, but for other languages (e.g. german, italian, spanish).

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

Equally in the file charconv.php, you will find the one line setting the admin password:

$adminpassword = '123456'; // admin password

As noted in the code as well, you really should change $adminusername and $adminpassword to something else.
Actually, charconv.php isn't needed after you've converted the database, so you should delete it.

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 and by Ilya Zverev in 2009. 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.

Ilya Zverev updated this script fixing all found bugs and implementing some of the requested features. He decided to keep 'Plus' version line.

This is the second stable release of flatPHPbook Plus version which updates the Plus version 1.0. The 2.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.

flatPHPbook's History
VersionReleased dateDeveloper
0.9.0July 26, 2003Thomas Hettenhausen
0.9.1August 02, 2003Thomas Hettenhausen
0.9.2August 19, 2003Thomas Hettenhausen
0.9.3August 29, 2003Thomas Hettenhausen
0.9.4September 01, 2003Thomas Hettenhausen
0.9.5September 14, 2003Thomas Hettenhausen
0.9.6October 06, 2003Thomas Hettenhausen
0.9.7October 15, 2003Thomas Hettenhausen
0.9.8November 08, 2003Thomas Hettenhausen
0.9.9December 12, 2003Thomas Hettenhausen
1.0March 01, 2004Thomas Hettenhausen
1.01June 25, 2004Thomas Hettenhausen
1.02February 08, 2005Thomas Hettenhausen
Antispam version 1.0July 18, 2006Vincenzo Capuano
Antispam version 1.1February 13, 2007Vincenzo Capuano
Antispam version 1.2July 11, 2007Vincenzo Capuano
Antispam version 2.0October 22, 2007Vincenzo Capuano
Antispam version 2.1May 08, 2008Vincenzo Capuano
Plus version 1.0February 03, 2009Vincenzo Capuano
Plus version 2.0September 17, 2009Ilya Zverev
Plus version 2.1November 25, 2009Ilya Zverev

- 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. All translation files reside in lang folder. The following languages are included:

flatPHPbook Plus version Language Packs
LanguageIconVersionThis translation done by
Dutch1.2Pieter Bos en Bas van den Bosch
English1.2Thomas Hettenhausen
French1.2Susanne Jegge
German1.2Thomas Hettenhausen
Icelandic1.2Einar Steinsson
Italian1.3Vincenzo Capuano
PolishbetaAdam Potempa
Russian1.1Andrey Mikhalchuk and Ilya Zverev
Spanish1.3Giampiero Mancini
SwedishbetaOdd 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 "&auml;" for "" - use the real character or like in this case "ae" as workaround. Also do not forget to add your language file name to 'languageFile' key in configdesc.ini.

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) and the welcome message file (e.g. welcomeMessageITA.html).

- 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 -


Appendix E: RSS

Since Plus version 2.1 flatPHPbook allows users to use RSS feed to monitor new posts. This feature can be turned off by setting entriesInRSS configuration parameter to zero. Note that that only disables link to RSS, but the feed itself is generated, but with no items in it.

There is no link to RSS in default templates. It is placed in META tag, and all modern browsers understand it and inform user about RSS presence. An example of placing the link to RSS on the page can be found in bundled customFooter.inc.html.

- Up -


Credits

The flatPHPbook script was written by Thomas Hettenhausen in 2003.
http://flatphpbook.sourceforge.net
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

This script was updated by Ilya Zverev in 2009. No point showcasing his sites :)

- 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 -