[Summary view] [Print] [Text view]

   1  HOW TO FIND YOUR WAY AROUND THE GLOTPRESS CODEBASE?
   2  
   3  Say you want to fix a bug, add a feature, or understand how something in GlotPress works. You came to the rigth place.
   4  
   5  First, GlotPress shares a lot with WordPress, bbPress and actually uses BackPress. Familiarity with these systems will be helpful.
   6  
   7  The structure of the project is very MVC-like. Models are called Things, Views are Templates and Controllers are Routes.
   8  
   9  *** Routes ***
  10  
  11  Each route is reponsible for some URL pattern. For example the method single() of the class GP_Route_Project is reponsible for
  12  URLs like /project/{project-slug}.
  13  
  14  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.
  15  
  16  Each route class handles a logical group of requests. For example, the project route is responsible for CRUD for projects.
  17  
  18  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
  19  renders a template or redirects.
  20  
  21  All the routes live in gp-includes/routes/*.php
  22  
  23  *** Things ***
  24  
  25  Things is a poor men's ORM. Sometimes it's just better to be poor. It keeps you closer to the ground.
  26  
  27  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
  28  the functions related to an entity in your system.
  29  
  30  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,
  31  `sub_projects()`, which retrieves all sub-projects of a project and so on.
  32  
  33  Some very commonly used functionality like find by id, create, very simple searches, deleting/updating come for free from the parent GP_Thing class.
  34  
  35  If you need more performance (less memory footprint), you have a very easy way to opt out of mapping the results of the queries
  36  to a Thing class. Just append _no_map() to the method name.
  37  
  38  Things provide basic validation tools, which come very handy when going through the endless CRUD forms.
  39  
  40  Since static variables cause all sort of pains in PHP, you can access an instance of each Thing like GP::$project.
  41  
  42  All Things live in gp-includes/things/*.php
  43  
  44  *** Templates ***
  45  
  46  These are just plain PHP files. Some variables come from above. And we can load other templates.
  47  
  48  All templates live in gp-templates/*.php
  49  
  50  *** Testing ***
  51  
  52  All tests live in t/. Go in t/ and run:
  53  
  54  $ phpunit all
  55  
  56  You will need to install phpunit: http://www.phpunit.de/manual/current/en/installation.html
  57  
  58  
  59  *** TODO ***
  60  - routes: notices & errors
  61  - route: die
  62  - route: capabilities checks
  63  - route: headers for download, stuff like that
  64  - templates: helpers
  65  - tamplates: links function
  66  - tests
  67  - init phase
  68  - plugins: where to put
  69  - plugins: GP_Plugin base class
  70  - API calls