Introducing Animal. A Static Site Generator for PHP

Today at work I was given a very interesting problem. Build a blog. You cannot use a database, it has to be editable by non-coders, and you can only use PHP. I love these kinds of problems. We host a number of different legacy websites on this server and the configuration is pretty brittle so I didn’t have a lot of options. Luckily, I had just finished a crash course in using Octopress, the static blogging framework based off Jekyll and written in Ruby. So I knew a thing or two about static site generators at this point. So with a text editor, a notebook, and my knowledge of PHP I began the process of building a static file based blog for a multi-million dollar company. Animal F. was born.

Animal's Mascot

Design decisions

Animal (which stands for Awesome Newsfeeds in Minimal and Long-form Format) was built with the concepts I learned from Jekyll in mind except its made to run on the server and requires no technical skill once set up. Version 1 is functional but not ideal though, much like the project I open sourced yesterday. It works but requires a little tinkering if you want it to work for your situation (its very little tinkering). Animal was coded in two hours and made for the non-technical girls in my department. Half way into it I realized this could be useful for other projects of mine and maybe even other people. So when I was finished I immediately created a GitHub repository and pushed. I’m hoping to have some time to clean it up and make it more useful for a more broad range of use cases before anyone picks it up.

How it works

Installation

First, grab it from GitHub (be warned, this is alpha software but it isn’t likely to break anything). Right now there’s a lot of presentation markup that was meant for the purposes I was building it for at work. That stuff can be ignored. The bulk of the project, which is actually only a handful of files, is in the admin and tests folders. The entire “blog engine” is meant to be self contained and just dropped into your web root. Now, if you don’t want a URL like mydomain.com/blog then you should just be able to rip out the contents of the animal-f folder and place it the web root.

Usage

To write posts you log into the admin area which, predictably, is at /admin. Once there you give your post a title, content, then you have to manually create an excerpt. This can and will be automated in future versions but, like I said, I whipped this up in a couple of hours yesterday for a very specific use-case. So stay tuned for big improvements to that. Categories are one thing I can think need to be added just off the top of my head now.

Once you press the ‘Post’ button, that’s when the magic happens. The very short but powerful new_post.php script runs. It takes your form input and creates for you:

  • A valid Unix filename suitable for servers to serve upon request

  • An entry on the ‘Recent Posts’ sidebar for you

  • Adds an entry to the blog index page with the title, excerpt, and link to read more (I just realized now it adds them in the wrong order)

  • Shows you a little heart and a success message so you know it worked

  • Creates the actual single post page while the rest of the script adds links in all the right places to it

Files and their usage

So because I made this for a specific purpose and have yet to turn this into a general purpose blogging engine, there are a few gotchas that might trip people up. Here’s what you need to know about Animal.

/tests folder

After uploading Animal to your server, run the tests first. It’ll save you tons of time later in case there’s a problem. Before using Animal go to /tests/write.php. Enter a string of text and submit. You should get a success message and a link to the saved file. If the file contains the text you submitted then Animal should have no problems working in your environment. If you get an error then you most likely either have a permissions problem, a PHP version problem, or have certain features of PHP turned off. If you get an error, start by giving full permissions 777 to the folder Animal is in and its sub-folders. Most of the time the problems that arise are from the PHP user who runs as either nobody, www-data or apache doesn’t have permissions to modify files so chmod-ding the folders to 777 should help. If not then you might be in a locked down PHP environment (shared hosts, I’m looking at you). If you have access to a PHP.ini file then use it. Otherwise call support.

If you navigate to /test/env.php you’ll see your PHP configuration. This file just calls phpinfo() and is just a small convenience to help you resolve issues if you have them.

new_posts.php

This file absolutely should be modified… in the right places. The first and last part of this file are necessary for Animal to work properly. The middle section should be modified to hold your own custom single page blog post template. It’s important to note that any PHP that you add to the middle template section of this file will be processed and then written as HTML. So, for example, if you have a PHP include statement that pulls in a static header, Animal will run that PHP first and then write the result of that PHP statement to an HTML file. This means that you need to make sure that any PHP within your template is written relative to the path of new_post.php and not relative to where the file will be output. If any PHP errors pop up while new_post.php runs, the output of those errors will be written to the resulting HTML file exactly as you would have seen them on a dynamic PHP page. This is because new_post.php uses the output buffer to first run any PHP statements in the template, hold the results in memory, then write the output to an HTML file.

/includes folder

This is where I currently have the blog sidebar and blog index pages. These will change soon and more will likely be added. The basic idea is that these are files that get added on to and appear where static information usually appears on a blog. Its a lot like the custom asides in Ocopress and they’ll resemble them more as I refine this project and broaden it.

Markdown

Animal uses Markdown instead of that TinyMCE bullshit. ‘Nuff said.

Roadmap

I would consider Animal an alpha release. Let’s call it version 0.1 alpha. Tomorrow I’m attending a hackathonish meetup in Chicago and I’m thinking of using my time there to work on Animal. No matter what I’ll be updating this project and making it far more user friendly in the coming days.

That’s how open source projects are born sometimes. Out of someone’s need that turns into a fun project. It wasn’t until I was pretty far into it that I fell in love with the idea and decided to make it awesome. I have a website that I’m going to use this on soon. This is the perfect piece of software for it.

PHP, Projects, Web development

« The Making of an Octopress Theme I Ship, Therefore I Am »

Comments