Table Of Contents

1 What is phpReview?

2 What do I need to run phpReview?

3 Installing the bugger.

4 Security.

5 The Template system

6 Information Exchange between phpReview-sites

7 Developers guide.

8 About this FAQ and the people behind phpReview


1 What is phpReview?

1.1.What is phpReview.

phpReview is aiming to be a complete free reviewing system, based on an online webapplication that currently holds more then 100 book reviews. Since we would like to share a simular application we started working on an open source version in the late fall of 1999.

1.2.The tools we used.

We decided to use PHP and MySQL to create it. After a few months people requested support for other databaservers like PostgreSQL. In the future we will support other database servers too.

1.3.What are the features.

Default features:

Optional features:

1.4.Future plans.

We discussed this a lot. People have been asking us if it can support other items like cd, video. In the future there will be support for it but our main target is to create a stable application.

2 What do I need to run phpReview?

To run phpReview you will need a webserver running PHP and a database server. Currently both MySQL and PostgreSQL are supported. In the futere we will enable support for more database servers.

To have a more secure application I would like to suggest to use OpenSSL and mod_ssl. This enables you to use Secure Sockets for all of the pages where a password is needed. For the installation of the you should checkout the sites (see below). When using SSL on your own server you should create two webtrees, one for the normal files and one tree for the files where you need passwords. Move the password related files to the SSL tree. Next to that you should have some redirects from the password related files in your normal tree to the files in your https tree. Remember to store basic files like images, and the complete config dir in the other webtree too. Otherwise it can't find certain files.

Until version 0.9.0 phpReview used Smarty as a template system. In order to run this you will need to have access to the PEAR repository which will be installed on most systems where PHP is installed. If your ISP doesn't have it installed you can get the PEAR.php from a local distribution and put the PEAR.php in the classes dir of phpReview. Since Version 0.9-final, you do not need PEAR anymore. Also SMARTY has been revised and stripped for security reasons, our stripped version will not allow things like embedded php, etc... You will be able to use the original smarty version too.

At this moment it is not possible to use phpReview when safe_mode is enabled since the new template engine writes files as user nobody. We will examine if it's possible to create a safe_mode version in the futere.

2.1 Where to get PHP, MySQL, PostgreSQL and the optional OpenSSL / ModSSL

PHP http://www.php.net/
MySQL http://www.mysql.com/
PostgreSQL http://www.ca.postgresql.org/
OpenSSL http://www.openssl.org/
mod_ssl http://www.modssl.org/

3 Installing the bugger.

3.1 Installation of PHP

PHP http://www.php.net/manual/installation.php
E-gineer http://www.e-gineer.com/instructions/

3.2 Installation of MySQL.

MySQL http://www.mysql.com/documentation/mysql/bychapter/manual_Installing.html#Installing

3.3 Installation of PostgreSQL

Devshed http://www.devshed.com/Server_Side/PostgreSQL/Installing/
PostgreSQL site Docs http://postgresql.readysetnet.com/users-lounge/docs/7.1/admin/installation.html

3.4 Installation of phpReview.

3.4.1 Untar your package

To install phpReview you will have to untar the package. Don't store it directly into the webroot, the package contains three directories and 4 files. The manual directory contains this document in both ascii, html and postscript.

Directories: Files
  • manual (doc for old versions)
  • phpreview
  • INSTALL
  • phpreview.sql
  • postgres.sql
  • update.sql
  • README
Make sure that your webroot will parse php files like they should. If so, move the phpReview directory to a place within the webroot.

The template documentation only exists for the versions below 0.9.0. Since we had some major troubles with Fast Template (errors) we suggest that you update to a later version.

To have a safe installation you should chown both the templates and the templates_c dir to nobody:nobody, next you should chmod the templates_c dir to 700.

3.4.2 Dumping the data file into your database server

MySQL
In order to run phpReview on MySQL you will have to read the mysql.sql into the database with the help of mysql itself. On Unix/Linux this will require you to have privileges to create a database or have root privileges. To create a database you can use the mysqladmin command. ( mysqladmin create phpreview ). The syntax to read the file into the database :
mysql -u root -p phpreview < mysql.sql
PostgreSQL
If you are using PostgreSQL you will have to read the postgres.sql into the database with the help of psql. Login to your postgres account and create a database called phpreview.
createdb phpreview
You can now read the postgres.sql into the new database:
psql phpreview < postgres.sql

3.4.3 Updating a current version of the database

The database schema has been altered to provide an optimal use of the tables with other modules that will be released in the future. In order to update your own database you will have to make sure you have the correct privilges for it.

In the tarbal you will find a file called Update.sql. This file will show you the correct queries to alter your db for your database server. Just run every line for your version and dbserver on the db console. Please make sure you have a backup before you start altering the tables.

3.4.4 Enabling access for the visitors

The database you have read into the database server requires access for the web visitor. phpReview only requires select, insert, update and delete privledges for the user. Altering these rights is not needed and should be avoided on the database, since security issues has not been thoroughly tested yet.

Passwords

Since we try to take Security real serious, and will not trade conveniece for it, there are some issues about the use of passwords. We incorparated passwordchecks to guard against weak-passwords.

The password should be set to a minimal hardness to Crack, so they should be:

A minimum of 8 Characters long

Have at least ONE Upper-case Character

Have at least ONE Numerical Character

Have at least ONE Lower-case Character

Have at least ONE of these six `other' "SHIFT"-Characters: Exclamation-mark, Hash-symbol, Aprul, Percentage-sign, UP-mark, Ampersand.

All four above mentioned elements MUST be present in ANY password, otherwise it will be regarded as Invalid.

For example:

Phpreview1@ is A Valid Password

phpreview123 is NOT Valid, for it has NO Special-Characters and NO Upper-case Characters in it.

PHPREVIEW@ is NOT Valid, for it has NO Lower-case Characters in it.

MySQL
Login to MySQL using the monitor with the following syntax, you will be prompted for a root password:
mysql -u root -p mysql
Next you will need to grant the permissions with the following syntax:
GRANT SELECT, INSERT, UPDATE ON phpreview.* TO dbuser@yourdomain IDENTIFIED BY 'password';
You will also have to flush the database in order to make the changes available:
flush privileges
Your database is configured now. Logout of MySQL by using quit and proceed to the chapter where we describe the configuration of phpReview itself.

3.4.5 The config file.

The configuration file, which is located in the includes dir, enables you to change the settings of the application. This is an overview of these options.

Setting: Purpose Default value:
$dba Email address of the person that will maintain the database.
$dbaerrorsubject Mail subject of error mailings that will be send.
$postgresport Port to connect to. 5432
$mysqlport Port to connect to. 3306
$InnoDB Boolean value to see if InnoDB tables are being used. Do not alter this to true if you have a normal MySQL installation. false
$newreviews Email address where mailings about new reviews will be send to.
$newreviewSubject Email subject for new reviews.
$usestopwords This will enable a per language list of words that will not be searched for in the visitor interface. true
$forumEnabled Provides a forum for each review. true
$usedb Database server (choose between postgres or mysql).
$dbhost Hostname of the database server localhost
$dblogin Loginame to connect to the databaseserver.
$dbpassword Password to connect to the databaseserver.
$dbdatabase Database to use on the databaseserver phpreview
$style Template Style
$lang Default language us
$visitorchooselang If set to true it will allow people to choose a language in the footerbar. true

3.4.6 First Use of phpReview

After successfully dumping the (provided) standard SQL-dump, most categories et-al are allready in the database. When you login into phpReview throug the web-interface you are automagically promoted to SUPERVISOR of the phpReview program with ALL priviliges . In this way we prevent that every phpReview-site could have the same supervisor-passwd. Keep in mind that the FIRST login will get these rights, no matter who it is!!!!!!

Now you can use the web-interface to add and/or remove any item which is in the standard setup of phpReview. By browsing to the admin dir you will be able to setup new categories, names with privileges, publishers, books, etc...

3.4.7 Authentication levels ( all modules )

phpReview works with Authorization levels. These levels are used to check if a user has the privileges to view, alter, delete and/or add information. Currently the following levels exist :

Level name Description
writer Used for product owners. These users don't have any privledges on the pages unless you change their level.
owner The lowest level with privileges. Owners have the right to insert, add, and alter their own submitted reviews.
jradmin Not only can jradmin's alter/add their own reviews, but they can add/alter categories, publishers and books too.
admin Admins can alter, add and delete their all reviews, and also add/alter/delete categories, publishers and books.
supervisor In addition to the admin privledges, a supervisor can alter/add/delete names too.

In addition to these levels you can approve a user. Users who are approved can insert a review that will be visible without approval of the admins.

4 Security.

4.1 General Security issues

This section is growing.

A real-world reality check to phpReview security is pending at an Hackers_fest in July 2001. The was contest to see "who can hack phpReview" and "how can it be done". This revealed no major issues apart from some minor issues wich were solved.

Some things to keep in mind when you are using phpReview:

More general security issues:

http://phpreview.nl.linux.org/manual/html/4.1.html

4.2 PHP Security

We have a mindset to put Security before beauty.

To get rid of some nasty security-flaws in the Smarty-Engine we had to hack it to prevent unsafe behaviour..

But with the original Smarty the application will work fine, but will be less Secure.

4.3 Database Security

As always, it's important to be secure. This section is important to read and understand when dealing with Databases and Database Administration.

Always keep in mind the following points :

Most Databases have measures in place to take care of these matters, but not always.

Never forget that your Database is just one link in the chain of events and that even the strictest type of security can be flawed by the weakest link in this given chain.

The links below lead you to relevant information with regards to Database Security, thus far we'll include information about MySQL and PostgreSQL.

MySQL http://www.mysql.com/doc/P/r/Privilege_system.htm
PostgreSQL http://www.postgresql.org/idocs/index.php?admin.htm

4.4 Apache Security

Since Apache is under constant development, you must take and stay up-to-date on all security related matters.

Here are a few related resources about common security tips for the Apache Webserver.

http://httpd.apache.org/docs/misc/security_tips.html

A more comprehensive look at the Apache related issues can be found at :

http://httpd.apache.org/docs/

5 The Template system

Describes what templates are and what they can do for the users.

The templates are build on Smarty and have a lot of functionality in them. There is a posibility to make decisions in the templates themselfs. You can make your own template sets to make phpReview adjust to your own website layout.

More information about what you can do in your templates can be found on the site of Smarty ( http://www.phpinsider.com/php/code/Smarty)

5.1 General layout of the templates

The templates have different names for the things where they are used for.

We have the following name sections:

The books_* files are used for the books module of phpReview. The adm_* files are used for administration of all modules. The gen* tpl files are created to be used with other modules too.

All the files have a logical name. And some of the files are included in others. Like the books_header.tpl and books_footer.tpl are used for almost every other books_* file.

5.2 Template Sets

Right now two different template sets are distributed with phpReview. The base set is the same set as the demo site. The second set, which is called plain, has been optimized for the use of textbrowsers.

We encourage people to create their own set of templates and submit them to phpReview. Any set that is able to work on all browsers will be distributed by us.

6 Information Exchange between phpReview-sites

6.1 The phpReview approach

As we all know data Exchange means a lot of different things to different people. In this paragraph we elaborate on how we think phpReview could exchange data between sites which work together as an network of phpReview sites. Whitout having to have to resort to bulk data-transport between locations.

This will be done by enabeling exchange of META-data between sites which run a phpReview-module on a site and to the users of that site.

6.1.1 The facilities in the PhpReview Book-Module

Currently, with version 1.0.1, you will be able to import and export single books with phpReview and sync the publishers in your phpReview version with the phpReview site data.

Export is done from within the summary pages. For every book there is a link on those pages which will offer a download file in XML format. The encoding is utf-8 and the file has a link to a dtd on the phpreview site. At this moment the regular xml functions within PHP are not able to validate XML by the dtd's but usage with libxml (gnome) works.

To import books you will need to visit the admin pages of your phpReview version. The import link will offer you a small interface where you can enter the /path/file on that local machine or the url of the xmldata of a book on a remote site. Once the file is read it will show you the meta data for this book. You have the choice to import it. In future versions you will be able to import complete booklists.

Version 1.0.2 will enable you to sync your own publisher list with the datarepository of phpReview's main site. You will have to enter the following url at the import page:

http://phpReview.nl.linux.org/books/xmlbook.php?getpublishers=1

It will load the data independent of the database engine you are using and store the data in your database. Future versions will have a more sofisticated interface.

At this moment we are testing several options to offer you an automated update section where data will be exchanged between other sites using phpReview. More about will be announced on our site.

6.2 The phpReview DATA-types

Please keep in mind that this section is a work in progress, and by no means complete. But we try to keep the documentation up-to-date with development.

Here you find the discriptions of the DATA-types and XML-ENTITIES used in the phpReview-Manual and the DATA-types used in the DATA-Exchange-module

The base doc.dtd is part of the original XSLT-doc-dtd definition. The character-definitions herein lack some of the characters used in phpReview. This is due to the multiple language capabilities available in phpReview. We made (some) provisions to acommodate these special-characters in the phpReview.dtd.

http://phpreview.nl.linux.org/manual/html/phpreview-dtd.txt

http://phpreview.nl.linux.org/manual/html/phpreviewdoc-dtd.txt

http://phpreview.nl.linux.org/manual/html/phpreviewbook-dtd.txt

7 Developers guide.

7.1 Helping out on the project

This part of the manual will not give you a complete overview of the code structure but rather, it's a small introduction to give an idea of how we're working. If you're interested in helping out then please contact us at phpchannel @ nl.linux.org

7.2 General developing issues regarding phpReview.

phpReview is build with the help of classes. We did start using phpdoc to have a api documentation set but no of the developers (the active ones) felt happy with it. As of version 0.9.0 we will use plain comments within the code.

Those of you that are not familiar with classes could find more information about them on www.zend.com, the manual or any good php book that is around. PHP classes are not OOP. They are not aware of public or private methods and vars. They do give you reusable code and the chance to provide functionallity to users who don't want to go over a complete set of fuctions. They can instance the class, provide some vars and call a method or two instead.

At this moment phpReview has one extra template set for the books module. The directories that contain those templates are located in both the templates and the books/templates directory. Whenever you are making changes in the base/module templates you should be aware of the effect and alter the extra template set(s) too.

7.3 Coding style

At this moment it's all based on common logic and we will continue to do until we can describe a base that is accepted by all the developers. Some ground rules that should be considered are :

8 About this FAQ and the people behind phpReview

8.1 Legal

We encourage people to distribute it for free and translate it in any language.

The phpReview team takes no responsibility for any problems you may encounter resulting from the use of this document or the use of phpReview.

8.2 Contacting us

If you wish to contact us about this manual or phpReview you can do this in more then one way. The quickest is to send an email to the general mailing list, phpchannel @ nl.linux.org (remove the spaces around the @).

It's also possible to drop a message in the forum. It can be found at the following url:

http://phpReview.nl.linux.org/forum.php

8.3 The people behind phpReview

8.3.1 Hans Wolters

Well, I started it... phpReview is build upon the previous bookreviewing app at http://nl.linux.org. I decided to Open Source it so other people could benefit from it too. Currently I'm working for Terena in Amsterdam, this company is using part of phpReview and lets me do some additional work on it during office hours.

8.3.2 Cor Gest Jr.

Our Changelog creator, sysop, tester and Manual co-writer.

8.3.3 Patrick v. Zweden

Submitted the part where people can insert new reviews.

8.3.4 Stefan Ubbink

Was very busy creating the plain layout and writing documentation for the templates.

8.3.5 Craig Davis

Submitted the Logo.

8.3.6 Philip Olson

Just started to work on phpReview.

8.3.7 Jamie G. Wong

Submitted the Spannish menu.

8.3.8 Wolfgang Drews

Worked on a part of the language and authentication code.

8.3.9 Keith Nunn

Submitted the ISBN check

8.3.10 Dedimio Emilio Grimaldo Tunon

Part of the code base for the rss channel was coded by him for the phpchannel project.

8.4 The tools which created this document

We would like to thank Arjen Baart from Andromeda for building XMLDoc. We are using it to create this manual.