ZFPlanet is a simple Blog Planet designed to aggregate content from a collection
of feeds and display it in readable paginated form. Its function is mainly
to gather content from a related topic into one easy to reach location for
readers.

Purpose
=======

ZFPlanet is currently a demonstration project utilising pieces of Zend Framework
1.10 specifically its newer Zend_Feed components including Zend_Feed_Reader,
Zend_Feed_Writer, Zend_Feed_Pubsubhubbub, Zend_Cache_Manager, and
Zend_Cache_Backend_Static. This allows it to serve as a demonstration platform
for individuals interested in seeing how all these pieces can be used in a single
application.

Disclaimer
==========

No claim is made that this is a stable application. It's currently in
development, has quirks, will change rapidly up to the end of January, and there
are pieces of functionality yet to be added. It is not yet suitable to be used
in production. It's presented here untagged and non-versioned as a demo app for
Zend Framework 1.10. I'll switch its status to stable when its ready ;).

Estimated status is BETA (mostly complete but may be unstable/unoptimised).

Prerequisites
=============

The application is not packaged with the Zend Framework. Prior to use, you should
ensure Zend Framework 1.10.2 is available from your include_path. At the time of
writing, 1.10.2 is not released as stable and therefore you are required to
use the current Subversion HEAD of the standard trunk until a stable release is
available. This ensures the application has access to as yet unreleased
improvements.

In line with recent Zend Framework versions, PHP 5.2.6 is the lowest supported
version supported though it is strongly recommended the latest PHP version be
used.

This is not a production-ready application (yet) so please do not put this on a
live website ;).

Installation
============

Note: These instructions were written assuming a Linux system (using Ubuntu
here) - modify where relevant for other systems.

1. Install the current trunk (HEAD) of Zend Framework to your include_path or
edit the contents of ./public/index.php to declare the path to this Zend Framework
library explicitly prior to any Zend namespaced classes being required.

2. Copy the application to your destination of choice and ensure any intended
Virtual Host is pointing to the ./public directory as the Host's document
root. The ./data directory (and its sub-directories) should be writeable from
PHP, either by setting relevant permissions or changing the directories' ownership
to the user under which HTTP requests are served. The same goes for the ./public
directory's cached subdirectory. For example:

    sudo chown -R www-data:www-data ./data
    sudo chown www-data:www-data ./public/cached

If using a Virtual Host, if using this in production you may consider adding the
contents of ./public/.htaccess to your Virtual Host configuration to gain some
performance. No alternative is currently presented for web servers other than
Apache 2 at this time.

3. Copy or rename the four configuration files in ./application/configs to
application.ini, cli.ini, http.ini and site.ini respectively. Note the presence
of the following line in application.ini:

    doctrine.connection_string = "mysql://username:[email protected]/databasename"

At the top of cli.ini, you should edit the value of the "host" configuration
setting to reflect the hostname of your URI, for example:

    host = "example.com"

This is used to generate URIs for the application when the CLI tasks are running
(since we cannot access $_SERVER['HTTP_HOST'] from the command line).

In site.ini, you can configure the title of the Planet Blog itself. This config
file also allows for setting up Twitter OAuth credentials (so the planet can
optionally tweet about updates) and a ShareThis Publisher ID (to enable
ShareThis dialogs next to articles).

There are four configurations for a simple reason. application.ini is a base
configuration merged with one of http.ini or cli.ini depending on whether the
application is accessed over HTTP or via the ./scripts/zf-cli script over the
command line (e.g. with a cronjob). site.ini is specifically geared towards
site specific naming and service APIs.
    
4. Create a new database (and optionally user). For MySQL, you should not use
MyISAM tables as they do not support cascading deletes and updates used by the
application's Model layer. Edit the configuration line (noted earlier)
in application.ini to reflect these details. The initial protocol name
of "mysql" assumes a MySQL database but can be edited with reference to the
Doctrine ORM 1.2 documentation for a DSN string. While we intend supporting
multiple database, MySQL is the only one officially supported at this time.

5. From the command line navigate to the base directory of the application and
issue the following command:

    ./scripts/doctrine create-tables
    
This command should (provided accurate credentials) generate all the necessary
database tables for the application based on the Model definition classes in
./application/modules/zfplanet/models/Base. You may delete the ./script/doctrine
script (if something goes wrong later just copy it back).

6. The application relies on polling aggregated feeds. To trigger this you may add
a new crontab entry which calls the following command at a polling interval of
your choice. Here is a sample entry for regular half-hour polling (at the top of
the hour and the half past mark):

    0,30 * * * * /path/to/scripts/zf-cli -e production -c cron -a poll > /dev/null

This directs that the Poll action of the Cron controller be executed given a
production environment. The output is directed to the null device. You can pipe
the output (if any) to a log file of your choice. By default, issues with polling
(primarily exception traces) are logged to ./data/log/feedsync.log. This can
be examined to identify fatal polling failures.

Since the script also cleans the static file cache of any HTML pages or XML feeds
to allow for a refresh based on any new entries, the script should be run with
sufficient privaleges to delete cache files generated by the application. This may
require configuring different cache permissions, but it would be simpler just to
add the above cronjob to run under the user involved in HTTP requests, e.g.
www-data. Most systems will not allow you to switch to the www-data user by
default. You can temporarily override this using something along the lines of:

    sudo cp /etc/shadow /etc/shadow.backup
    sudo passwd www-data
    [Add your cronjob as above after setting a password...]
    sudo cp /etc/shadow.backup /etc/shadow
    
The important thing is that you don't set a permanant password for this user,
leaving it place only as long as it is needed to setup the cronjob.

7. Add some blogs! At present a default user is not created (all users are
Administrators). You can manually add one to the database's "user" table. The
password should be a SHA256 hash of the actual password if entered directly into
the entry via something like the mysql client or phpmyadmin.

To access the administration section, simply direct your browser to
http://yourhost/admin.

From here you can add blogs to be aggregated. The time to add a blog is variable
since several tasks are performed on each such as grabbing the feed to confirm
specific details and setting up any possible Pubsubhubbub subscriptions.

Copyright & License
===================

Please refer to the LICENSE file for details on the copyright and the New BSD
License applicable to this application.

Bugs & Support
==============

Support will be informal. I can be messaged over Github or by email with
specific queries. You can find me on Twitter as @padraicb. I am also often in
the #zftalk or #zftalk.dev channels on irc.freenode.net.