$Id$

This is the README file I wrote for phpVideoPro v0.1.3 (and last updated for
v0.8.5). As you may know, programmers get very lazy on writing documentation -
so starting with point 3.), the information in this file may or may not fit
newer versions, since I may have forgotten to update it. Don't be angry at me if
this happens - just drop me a note about it - or even better, update this file
(if you know the missing/changed information) and send it back to me, so I can
replace it in the package :)

More documentation may follow (or not - see above ;) in the future, some even
is already contained in the help system. But I'm more concerned about new
features and, if needed, bugfixes to come asap, so again I may forget about
the documentation - although I always try to keep at least the online help
up-to-date to reflect the recent application state.

So I hope you can cope with this code, and wish you good luck - and enjoy
phpVideoPro!

Itzchak "Izzy" Rehberg (izzysoft AT qumran DOT org)

===============================================================================

Contents:
---------
  1.) CopyRight
  2.) Warranty
  3.) Requirements
  4.) Pre-Requisites
  5.) Installation
  6.) Updating
  7.) Administrative hints
  8.) Protecting your installation
  9.) Known bugs / limitations
 10.) Download and Sites

===============================================================================

1.) CopyRight (and CopyLeft)
----------------------------

  This nice piece of software is (c) 2001-2007 by Itzchak Rehberg and IzzySoft,
  and is protected by the GNU Public License Version 2 (GPL). In short, this
  means:
  - you'll have the source code available
  - you may run this program on as many machines as you want/have
  - you may copy and distribute it as much as you want - as long as you don't
    take money for it (and keep all files together!)
  - you may edit this code to fit your needs/wishes (please, let me know about
    improvements!)
  - you may use this code for own applications - but they have to be released
    under GPL then as well.
  For details, please read the file named LICENSE in the doc/ directory.
  If you release this program e.g. in a bundle of software on CD/DVD, release
  an article about this program etc, let the author know about this. Not that
  you need an explicit permission (as long as you stick to the above terms,
  especially the GPL) - you are even encouraged to do so. I just want to be
  informed about the fact to be up-to-date about all PR taking place ;).

===============================================================================

2.) Warranty
------------

  This program is provided "as is" with no warranty (see GPL Par. 11).
  Especially this means, that the author is not responsible for any damages
  caused by the use of this software - explicitly or implicitly. The only thing
  I can guarantee you is: it will consume some disk space :)

===============================================================================

3.) Requirements
----------------

 There are a few things you have to make sure first (without them the whole
 program, including this setup, won't work at all):
 1. have a webserver running (I just tested it with Apache)
 2. have PHP running, at least v4.1 (a version less than this won't work;
    I recommend using Apache with PHP as loadable module, and that's
    the only combination I've tested)
 3. make sure your PHP has built in support for the database you want to use
    (this has to be one supported by phpVideoPro, of course)! If requirements
    1. and 2. are met, you can find out by creating a file called "test.php"
    (or whatever you like), containing only one line:
    <?php phpinfo(); ?>
    Point your browser to it via http (e.g. "http://localhost/test.php" -
    depending on where you put the file and how you named your (local) web
    service). The resulting page will tell you what features are supported by
    your PHP setup
 4. Supported databases are:
    - MySQL version 3.28.32 or higher
    - PostgreSQL 7.1 (?) or higher (may be lower, too - YOU need to report this)

===============================================================================

4.) Pre-Requisites
------------------

 First, we need to check that Apache and PHP are set up correctly for the
 application. There are a few settings for additional security which are to
 recommend. If your Apache installation allows to adjust "Options" by
 directory for the target location of your installation (i.e. for that
 directory "AllowOverride Options" or "AllowOverride All" is set), you can
 directly jump to the next chapter (Installation), since the distribution
 contains a ".htaccess" file with the correct settings.

 Still here? Okay, looks like your Apache is not set up such. This leaves you
 with three options: a) to change your apache2.conf according what is said in
 above paragraph, b) globally change your php.ini and apache2.conf with the
 settings you find in the .htaccess file mentioned (and delete/rename that
 file afterwards to avoid complications), or c) add a special "<Directory...>"
 entry to your apache configuration which contains the content of the
 .htaccess file. All of these options have their pros and cons: a) makes sure
 that if I add some changes to the .htaccess file, you never need to care about
 this in the future, but marginally slows down the webserver (I don't think
 you will notice that), b) is slightly faster, but changes those values also
 for all other web applications, which may not be desired, and c) has the pro
 from b) without its con - but b+c leave you with the need to check these
 values for future updates (just check the timestamp of the file to see IF
 there are changes).

 In short: I would recommend you option a - you don't notice the minimal
 slow down, and don't have to care about the changes in the future.

===============================================================================

5.) Installation
---------------------------------

 If above mentioned requirements are met, we can start setting up phpVideoPro.
 To do this, follow these steps:
 1. *UNPACK THE TARBALL* to a directory of your choice. It has to be located
    below your webservers document root (or you have to configure your
    webserver in a way it can use that directory, e.g. by creating an alias).
    Simple advice: use "tar xzf <tarfile>" to unpack it into the current
    directory. Probably you have already done this - since you are reading
    this file :)
 2. rename inc/config.sample to inc/config.inc and optionally edit it to
    reflect your structures. Alternatively, this can be done with the
    configuration wizzard as well: in that case you only need to copy the new
    created config to its place lateron. The other settings (Hu? Ah, other
    files ;) you should leave unchanged. If you need more customization, you
    can do so later via the web interface.
 3. now, point your browser to <phpvideopro>/setup/install/index.php, which
    starts the *INSTALLATION WIZZARD*. This wizzard will create your database
    (and, if necessary, also the user) and install the "skeleton" (all the
    technical data needed to run phpVideoPro). If you are going to restore from
    a previously created backup, this is also done here. The wizzard will
    guide you through the whole process.
 4. After the wizzard has successfully finished the installation, you should
    protect the setup/install/ directory against unprivileged use. Either
    * remove the directory
    * move it somewhere outside your web tree
    * protect it via the web server (e.g. with .htaccess file when using
      Apache - a sample file, .htaccess_sample, with instructions you find
      already within this directory)
    * change its permissions with "chmod 0700 install" if the web server
      user is not its owner
 5. If you are concerned about *DISK SPACE*, you may want to remove the
    language support files for languages you won't ever use. By this, you
    will save about 100..250kB per language (with phpVideoPro v0.6.0 - may be
    more with future versions). I'm going to explain the removal of a
    language by the example of GERMAN.
    The German language has the code "de" (to find this out, you may want
    to look into setup/tech_data.sql and find the language together with
    its code at the end of the file).
    Remove German help files: delete the whole help/de directory.
    Remove German translations: delete the setup/lang_de.sql file (the
    translations may still be available if you loaded them into the database
    prior to this step).
    You won't destroy anything by these steps (as long as you don't remove
    files for the English [en] support, since these files ARE ALLWAYS
    REQUIRED by phpVideoPro). The worst thing to happen is, that the whole
    application may be English only, regardless of your configuration.
 6. For the *DATA RETRIEVAL FROM IMDB*, phpVideoPro needs a directory to store
    the images in (as shipped, this is moviepic/imdb/). This directory must
    be readable and writable for the web server process, which - depending on
    the distribution used, runs under different users. To make this work
    out-of-the-box, the moviepic/imdb/ directory is read/writeable for
    everybody. You may want to change this, if you are concerned about
    security: as root user, own this directory to the web server user (e.g.
    "chown wwwrun:www moviepic/imdb") and make it writable for its owner
    only ("chmod 0755 moviepic/imdb"). You CAN do so if you are concerned,
    but you don't need it to use the functionality.

 Finally, you may want to install some more templates for the label printing.
 These can be downloaded from the projects page at
 http://projects.izzysoft.de/?topic=progs;subject=phpvideopro - I started separating some
 rarely changed files to keep the distribution archive of the application
 smaller to ease updates, so the application archive now only contains a few
 sample templates for the label system.
 For the PSLabels, this installation can be done automatically from within the
 application - provided, you granted the web server write permission to the
 pslabels/ subdirectory. However, if you consider this a security risk, a
 semi-automatic installation process is provided as well.

===============================================================================

6.) Updating
------------

  When updating from a previous version of phpVideoPro, the steps to do
  follow easier rules. After updating the files (and comparing your config.inc
  with the new config.sample for possible changes), point your browser to the
  setup/index.php and just follow the update link there.

  When updating from v0.7.6 or earlier, make sure to delete all PVP cookies
  whose names start with "imdb_tx" from your browser(s) cache (and if other
  people use your installation, tell them to do so as well). According to the
  specifications, browsers only capable of a certain amount of cookies per
  domain, so we combined a few settings to be placed into one cookie (instead
  of using multiple cookies).

===============================================================================

7.) Administrative hints
------------------------

  Starting with v0.3.8, phpVideoPro supports a kind of "multi-user" environment.
  While the main configuration and default preferences are stored inside the
  database, user preferences can be managed via cookies. The biggest advantage
  of that is, that multiple users can use different filter settings at the
  same time, without overwriting each others settings (as it was until v0.3.7).
  This also concerns default settings as templates, data records per page for
  lists etc. For new users, defaults are loaded from the DB. If they change
  anything via the edit->preferences menue, changes can be stored into cookies
  and be loaded from there - if you specify so.
  For this, it is recommended to set up defaults via the admin->configuration
  menue, and optionally protect the admin part by placing an appropriate
  .htaccess file into the admin/ directory - so only authorized users can
  change configuration issues (though this part should be covered by phpVideoPros
  own user management). Make sure to enable cookies in this form, otherwise the
  edit->preferences use the database as storage instead (but a separate table).

  With v0.4.1, the multi-user capatibilities of phpVideoPro grew a lot. Now it
  contains a complete user management, including "permissions". By default, two
  users are created: admin (pwd: video) and guest (no pwd), and the guest
  account is strong limited (r/o) while the admin account has full access. You
  may want to login as admin first and adjust these settings (via the admin
  menue), and/or create new accounts. Make sure to change the admin pwd soon :)

===============================================================================

8.) Protecting your installation
--------------------------------

  There are several things you can do to protect your installation. First, you
  for sure want to prevent that anyone can run a fresh install or unwanted
  update, and thus destroy your database. Two ways. Normal one: Use an
  .htaccess file in the setup/install/ and setup/update directories - an
  example is to be found in the setp/install/.htaccess_sample file. Paranoia:
  Immediately after the installation/update is done, remove both mentioned
  directories (and just place them here again if YOU need them).

  Similiar approach to your configuration data. Sensitive information is stored
  inside the inc/config.inc file. Again, you can protect the entire include/
  directory by placing an appropriate .htaccess file here (nobody needs to go
  here with the browser - and PHP can include everything regardless whether
  it is protected this way or not). Paranoia: Move your inc/config.inc file
  to, say, /etc/pvp_config.inc. Then put a new inc/config.inc which just
  contains the line "<? include('/etc/pvp_config.inc'); ?>" - so nobody can
  read it via the web, but PVP gets its information.

  See also the "Installation" section of this document for a few more examples.

===============================================================================

9.) Known bugs / limitations
----------------------------

  Any bugs are not known to me (or not to mention here - because I tend to fix
  them faster than I update this file ;) - I didn't find any (or fixed them
  immediately, as mentioned), and nobody reported anything still open recently :)

  As for limitations: At least some versions of M$ Internet Explorer do have
  problems with the Hebrew support - but I don't know what to do about it...

  One more limitation is regarding the (PS) Label system: it currently only
  supports ISO-8859-1 (and -15) characters, thus labels may look funny if you
  e.g. use Kyrillic letters with your movie descriptions. You are invited to
  supply a solution to this: the reason is the font encoding (and dictionary)
  within the PostScript templates. By supplying these blocks to us for other
  encodings, we could make these parts variable within the templates, so it
  should work for other encodings as well.

===============================================================================

10.) Download and Sites
-----------------------

  Two running demos are to be found on my private homepage using the URL
  http://projects.izzysoft.de/?topic=progs;subject=phpvideopro - one of them,
  the developers demo, reflects the latest changes (and thus may be inter-
  mittently "broken" when larger changes take place), the other reflects the
  latest release. At the same place you will also find some information on
  some other projects of mine - for more, also visit my business site,
  http://www.izzysoft.de/
  As a backup, you can also download the latest version at SourceForge,
  http://sourceforge.net/projects/phpvideopro/. The tarball of the latest
  available version should always be available by an "alias":
  http://projects.izzysoft.de/progs/get_update?program=pvp should
  always send you the GNU-zipped tarball of the latest version (hopefully - if
  I didn't forget to update it :)
  If you have questions/suggestions, you can also contact me via email, using
  the address izzysoft AT qumran DOT org - and please, don't give up waiting if
  I do not respond that quickly; it sometimes takes me a while :)
