Skip to content

1. The Codebase

Jump to bottom
Greg Ross edited this page Oct 30, 2018 · 9 revisions

Coding Standards

GlotPress follows the WordPress coding standards.

Pull requests are automatically validated against the coding standards by Travis CI so please make sure to follow them.

If you need to whitelist any validation rules, please use the standard comment format to do so.

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

You will need to install PHPUnit version 5 before you can test.

As well make sure you have installed the WordPress PHPUnit tests.

You may need to setup an environment variable to point back to the WP Test suite:

export WP_TESTS_DIR=[path to the WP source code]/trunk/tests/phpunit

The GlotPress tests live in tests/phpunit from the GIT repo (they are not included in the plugin zip from wordpress.org).

From the main GlotPress directory run:

$ phpunit

Detailed Test Installation HowTo

The above testing setup instructions are a high level requirements, below is a more detailed set of instruction on how to setup and run the GlotPress test cases based on a Linux/Apache/MySQL/PHP (LAMP) configuration. The instructions will be based on Debian/Ubuntu command line tools so if your using another distro you will need to substitute the appropriate package tools/names.

  1. Make sure you have your LAMP up and running by visiting http://localhost, you should see the Apache default page.
  2. Check to see if PHPUnit isalready be installed with your distro by running phpunit --version. Most modern distro's come with PHPUnit 7, which WordPress and therefore GlotPress do no support. If PHPUnit 6 is install you may use this but you will receive some warnings when running GlotPress tests.
  3. If needed install PHPUnit 5 via the instructions found here. If you need both version 5 and 6/7 installed at the same time you can rename version 5 from phpunit to phpunit5. Once that is done, move your new PHPUnit 5 file to your /usr/bin directory and change the owner/group info.
  4. Install GIT via sudo apt install git.
  5. Install SVN via sudo apt install subversion.
  6. Create a new directory somewhere you want to do your development, like ~/source or ~/dev.
  7. Go in to the new direcotyr (I'll assume ~/source from now on).
  8. Create a directory to store WordPress in: mkdir wordpress.
  9. Checkout the WordPress development tree with svn checkout https://core.svn.wordpress.org/trunk/ wordpress
  10. Create a directory to store GlotPress in: mkdir glotpress.
  11. Checkout the GlotPress development tree with git clone https://github.com/GlotPress/GlotPress-WP.git glotpress
  12. Create a new test config file for WordPress, cd ~/source/wordpress; cp wp-tests-config-sample.php wp-tests-config.php.
  13. Edit your new config file and update the settings for your new test config. Do not use an existing database for your test config as it is wiped before each test run is executed.
  14. Add the following to your ~/.profile: export WP_TESTS_DIR="~/source/wordpress/tests/phpunit"
  15. Re-process your .profile: source ~/.profile. Note you will need to do this with each new shell you open until you have rebooted your computer.
  16. Go to your GlotPress directory: cd ~/source/glotpress
  17. Run phpunit (or phpunit5), you should then see the following output:
Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml
Installing GlotPress...
Not running ajax tests. To execute these, use --group ajax.
Not running ms-files tests. To execute these, use --group ms-files.
Not running external-http tests. To execute these, use --group external-http.
PHPUnit 5.7.27 by Sebastian Bergmann and contributors.

Error:         No code coverage driver is available

...............................................................  63 / 335 ( 18%)
............................................................... 126 / 335 ( 37%)
............................................................... 189 / 335 ( 56%)
............................................................... 252 / 335 ( 75%)
............................................................... 315 / 335 ( 94%)
....................                                            335 / 335 (100%)

Time: 7.67 seconds, Memory: 42.25MB

OK (335 tests, 1269 assertions)
  1. Profit!

PHP/WP Coding Standards Installation HowTo

When submitting code to GlotPress as a pull request on GitHub, your submissions must follow the WordPress coding standards and as such TravisCI will run automated tests to ensure they do.

However, it can be quicker/easier to run these tests locally before submitting your PR. You can do this by installing PHP_CodeSniffer and the appropriate WP rules.

The instructions will be based on Debian/Ubuntu command line tools so if your using another distro you will need to substitute the appropriate package tools/names.

  1. First check to see if phpcs is already install by running the following command phpcs --version.
  2. If the above returns something like PHP_CodeSniffer version 3.3.2 (stable) by Squiz (http://www.squiz.net), where the version is above 2.9, skip to step 5.
  3. If your version is below 2.9, you will need to install a newer version of phpcs, to do so, do the following:
# Or download using wget
wget https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar
wget https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar

# Then test the downloaded PHARs
php phpcs.phar -h
php phpcbf.phar -h

mv phpcs.phar phpcs
mv phpcbf.phar phpcbf

chmod +x phpcs phpcbf
  1. Move phpcs in to your /usr/bin directory, if phpcs is already installed, double check to make sure it's in /usr/bin with which phpcs before you do the following steps. If it's somewhere else, use that directory in the below move commands:
chgrp root phpcs phpcbf
chown root phpcs phpcbf

sudo mv phpcs /usr/bin
sudo mv phpcbf /usr/bin

Note the above will most likely overwrite your existing phpcs if you have one, you may want to add a version number to the end of these files when you rename them if you need your current version for another reason.

  1. Create a local directory to store the WordPress coding standards in, for example ~/source.
  2. Checkout the WPCS repo via: git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git ~/source/wordpress-coding-standards (you can use any directory name you prefer, just note it for the next step).
  3. Add the WPCS standards to phpcs: phpcs --config-set installed_paths ~/source/wordpress-coding-standards
  4. Validate they installed correctly, phpcs -i, if they have you should see something like the following output:
The installed coding standards are MySource, PEAR, PSR1, PSR12, PSR2, Squiz, Zend, WordPress-Docs, WordPress, WordPress-Extra, WordPress-Core and WordPress-VIP

Note the WordPress rules at the end.

  1. Profit!
Clone this wiki locally