Latest commit 972f017
Feb 19, 2010
…nt in Atom feed output (requires database regen)
|Failed to load latest commit information.|
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@example.com/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.