Flamework

Flamework is a PHP web-application framework, born out of the processes and house-style developed at Flickr.com.

This library is a work in progress. It is immediately usable, but lacks many of the components needed to create a fully featured modern application. These pieces are being added as the individual contributors find a need to in their personal projects. If you've written a missing piece of the puzzle, please send a pull-request.

Installation - As a base for a new project

• Copy everything in www to a web server running Apache with mod_php and php5-mcrypt.
• Enable AllowOverrides all for the root.
• If some of your rewrite rules like ^account/password$ aren't working, try Options -MultiViews.
• Copy include/config.php.example to include/config.php and edit it.
• Ensure that the templates_c directory can be written to by your webserver.
• Load the schema into mysql: mysql -uwww -Dflamework -p < schema/db_main.schema

That's it.

For a longer version, read the installation guide.

If you'd like to use Flamework as an external library, read this.

To install Flamework on AppFog.com, read this.

Global Variables

Flamework uses and assigns global PHP variables on the grounds that it's really just not that big a deal. A non-exhaustive list of global variables that Flameworks assigns is:

• $GLOBALS['cfg'] -- A great big hash that contains all the various site configs and runtime user authentication info.

• $GLOBALS['smarty'] -- A Smarty templating object.

• $GLOBALS['timings'] & $GLOBALS['timing_keys'] -- Hashs used to store site performance metrics.

Some libraries use their own globals internally, usually prefixed with LIBRARYNAME_ or _LIBRARYNAME_.

Other documentation

• Troubleshooting
• Design Philosophy
• Database Model
• Style guide

Libraries & Tools

There are several drop-in external libraries for common tasks:

• flamework-geo - Geo libraries and helper functions
• flamework-aws - S3 upload library
• flamework-api - Add an external API
• flamework-invitecodes - Generate invite codes
• flamework-useragent - Parse useragent strings
• flamework-JSON - Parse invalid JSON
• flamework-sendgrid - Use the SendGrid SMTP Service

Aaron has created several starter configurations for using delegated auth:

• flamework-flickrapp - Authenticate using Flickr
• flamework-twitterapp - Authenticate using Twitter
• flamework-foursquareapp - Authenticate using foursquare
• flamework-osmapp - Authenticate using OpenStreetMap
• flamework-tumblrapp - Authenticate using Tumblr

And some random odds and ends:

• flamework-tools - Automation scripts

Tests

If you have make and and recent perl installed (you almost certainly do, or if not see Vagrant and Docker sections below), you can run the tests using:

make test

If you also have xdebug and PHP_CodeCoverage installed, you can generate test coverage information:

make cover

Test coverage needs some serious improvement.

Vagrant

If you don't want to mess with your local development environment, you can run the tests under Vagrant by doing:

vagrant up
vagrant ssh
cd /vagrant
make test

Docker

Similarly, Docker is an option for both local development and test running, but is not suitable for production use (really, REALLY don't use it for prod -- we (intentionally) do not have this configured securely). To build and run:

docker build -t flamework .
docker run -ti -p80:8081 -p443:4331 -v ~/dev/flamework:/mnt/flamework --name=flamework --rm flamework

Your local flamework copy should now be listening on ports 8081 and 4331. Use docker ps to verify them. You'll need to edit include/config.php as usual. Since you mounted your local dev flamework directory into the container, any code changes you make should be reflected immediately.

Once the container is running, to run tests you can do:

docker exec -ti flamework make test

And to tail the error logs:

docker exec -ti flamework tail -F /var/log/apache2/error.log

When killing the container using either CTRL+C or docker stop flamework, the container will be removed and all data will be reset next run. This is useful for running tests.