HACKING

HOW TO FIND YOUR WAY AROUND THE GLOTPRESS CODEBASE?

Say you want to fix a bug, add a feature, or understand how something in GlotPress works. You came to the right place.

First, GlotPress shares a lot with WordPress, bbPress and actually uses BackPress. Familiarity with these systems will be helpful.

The structure of the project is very MVC-like. Models are called Things, Views are Templates and Controllers are Routes.

*** Routes ***

Each route is responsible for some URL pattern. For example the method single() of the class GP_Route_Project is responsible for
URLs like /project/{project-slug}.

The active route is chosen by the router in gp-includes/router.php. It's a simple loop over some regular expressions. The first match wins.

Each route class handles a logical group of requests. For example, the project route is responsible for CRUD for projects.

A route retrieves some data via the Things, does some magic (aka logic) based on the request parameters and the data and in the end either
renders a template or redirects.

All the routes live in gp-includes/routes/*.php

*** Things ***

Things is a poor men's ORM. Sometimes it's just better to be poor. It keeps you closer to the ground.

The main goal of a Thing is *not* to hide SQL behind a OOP wall. It's goal is to help you better structure your code. It gives you a place to put all
the functions related to an entity in your system.

For example, let's take the GP_Project class, which is a descendant of GP_Thing. It has methods like `by_path()`, which finds a project by its path,
`sub_projects()`, which retrieves all sub-projects of a project and so on.

Some very commonly used functionality like find by id, create, very simple searches, deleting/updating come for free from the parent GP_Thing class.

If you need more performance (less memory footprint), you have a very easy way to opt out of mapping the results of the queries
to a Thing class. Just append _no_map() to the method name.

Things provide basic validation tools, which come very handy when going through the endless CRUD forms.

Since static variables cause all sort of pains in PHP, you can access an instance of each Thing like GP::$project.

All Things live in gp-includes/things/*.php

*** Templates ***

These are just plain PHP files. Some variables come from above. And we can load other templates.

All templates live in gp-templates/*.php

*** Testing ***

All tests live in t/. Go in t/ and run:

$ phpunit all

You will need to install phpunit: http://www.phpunit.de/manual/current/en/installation.html


*** TODO ***
- routes: notices & errors
- route: die
- route: capabilities checks
- route: headers for download, stuff like that
- templates: helpers
- templates: links function
- tests
- init phase
- plugins: where to put
- plugins: GP_Plugin base class
- API calls