What you should know PHPwise - lokothodida/DM_Matrix GitHub Wiki

If you really want to jump into The Matrix and use it to its full potential, you need to have an understanding of PHP beyond just copy-pasting code. W3Schools has a great PHP learning resource that I throughly recommend (read through from the Basic to the end of the Advanced section at least). Nettuts is also good, particularly for their Object Oriented PHP tutorial (in order to understand Classes). This page is really here just to summarise some of the important aspects of PHP that you should know about in order to understand what the coding you are supposed to do will mean. As such, this is by absolutely no means an exhaustive list of everything you need to know in PHP - just the clip-notes to help you get the inner workings of this plugin.

Constants and variables are placeholders for various values, be they a string, a numeric value, a boolean or even an array or object. The difference between a constant and a variable is that once a constant's value has been set, it cannot be changed for the rest of the script's execution (hence it being called a constant), whereas variables can always change their values throughout.

<?php
  // constants
  define('CONSTANT', 'FOO');   // gives the constant CONSTANT a value of 'FOO'
  echo CONSTANT;               // outputs 'CONSTANT' on the page
  define('CONSTANT', 'BAR');   // results in an error, as constants cannot be redefined this way

  // variables
  $variable = 'foo';           // gives variable $variable a value of 'foo'
  echo $variable;              // outputs 'foo' on the page
  $variable = 'bar';           // $variable now takes the value 'bar' (the previous output on the page is unaffected)
?>

Arrays hold lists of information. They are made up of keys and values, where each key corresponds to a value in that list. Take the following list:

• Item 1
• Item 2
• Item 3

An array structure that would reflect such a list would be the following:

<?php
  // load the array into a variable
  $array = array('Item 1', 'Item 2', 'Item 3');
?>

Array keys come in 2 flavours: indexed and associative. Indexed keys are purely numeric and start from 0, and are automatically the case when you don't explicitly define an array key. So for example, from that previous array, Item 1 has an array key of 0; Item 2 has 1 and Item 3 has 2. If you wished to output the contents of the array individually, you can access the array items via their keys like so:

<?php
  echo $array[0]; // outputs 'Item 1'
?>

Associative arrays are custom defined keys (often taking strings instead of numeric values).

<?php
  $array = array('item-1' => 'Item 1', 'item-2' => 'Item 2', 'item-3' => 'Item 3');
  echo $array['item-2']; // outputs 'Item 2'
?>

When you call the query() method from The Matrix, the result is in fact an associative array, where the array keys are the field names and the values are the record values.

Loops allow you to repeatedly do a particular action so long as particular condition is met. This allows you to quickly perform (what would be) tedious actions dynamically that you would otherwise have to do manually. You could use a loop to output numbers 1-100 for example, without needing to write out the numbers yourself. There are 4 main loop types, but there is one particular loop that you will find yourself using most often in The Matrix.

While loops say 'while this condition is being met, do this'.

<?php
  $i = 0; // just a variable we've set up
  while ($i<5) {
     echo $i;
     $i++; // (same as writing $i = $i + 1, meaning increase $i by 1)
  }
?>

The above loop will output 01234, because as long as $i is less than 5, it will output the value of $i (which increases at the end of each loop cycle thanks to the $i++ line. These loops are very easy to mess up because the initial and terminating conditions are not always explicitly clear. If we hasn't put the $i++ in there, this would have resulted in an infinite loop, as $i would never increase and would hence always be less than 5. As such, while loops are not the most preferred loops to use when iterating over a particular set of data.

This is mainly here for completion, but do while loops are just while loops that always execute at least once. In a while loop, if the conditions are never met, the loop never executes, but with a do while loop, you are guaranteed to have one execution.

<?php
  $i = 0;
  do {
    echo $i;
  }
  while ($i>0); // since $i = 0, this condition will never be the case, but it will be executed once
?>

For loops (in the sense that we will be using them) are essentially more explicitly structured while loops. You are forced to specify initial conditions, continuation/termination conditions and incrementing conditions from the start, which lessens the chance of you causing an infinite loop (as a result of absent mindedly forgetting one of the three essential conditions). The below is an example of the first while loop we had, rewritten as a for loop.

<?php
  for ($i=0; $i<5; $i++) {
    echo $i;
  }
?>

Finally the most important loop of them all (in our case). Foreach loops are specially designed to tackle arrays. They let us loop through each item in the array and perform any given action that we want. It works by setting up a temporary variable that holds the contents of the current array item in the loop and changing that variable as we walk through the loop. This piece of code will let us output the whole contents of the array, instead of having to output each value based on their key.

<?php
  $array = array('Item 1', 'Item 2', 'Item 3'); // same array we had before
  foreach ($array as $value) {
    echo $value;
  }
?>

So the loop says 'Walk through each array item. At each stage, give the item the variable $value, then output $value on the page'.

If they keys of the array are in any way important (regardless of whether they are indexed or associative), you can also utilize them in the foreach loop by changing the syntax slightly.

<?php
  $array = array('item-1' => 'Item 1', 'item-2' => 'Item 2', 'item-3' => 'Item 3');
  foreach ($array as $key => $value) {
    echo $key.' : '.$value.'<br/>';
  }
?>

Note: you can give the $key and $value variables any name that you want - they don't have to be $key and $value specifically. However, realize that they should not take the names of existing variables, otherwise you will overwrite them!

This is arguably the most important feature of any programming language - the ability to change an output based on a particular condition, i.e. if x is the case, do 'this', otherwise do 'that'. If/else statements let you do this.

<?php
  $i = 0;
  if ($i == 0) {
    echo 'i is 0';
  }
  else {
    echo 'i is not 0';
  }

You can extend if statements using 'elseif':

<?php
  $i = 0;
  if ($i == 0) {
    echo 'i is 0';
  }
  elseif ($i == 1) {
    echo 'i is 1';
  }
  else {
    echo 'i is not 0 or 1';
  }

If statements can be used within all the different loop types as well, so you can change the output during a particular loop based on conditions that you specify.

All of the coding that we have talked about thus far are basically instructions. Sets of instructions issued to the server for the PHP parser to analyze. Functions let us automate a set of instructions that we would otherwise have to copy and paste repeatedly, saving us a lot of tedium and frustration in the long run. Functions have to be declared with a prefix 'function', and can take any number of parameters (variables) that can be passed directly into the function for analysis.

<?php
  function foo($var) {
    if ($var==0) {
      echo '$var is 0';
    }
    else {
      echo '$var is not 0';
    }
  }

  foo(0); // outputs '$var is 0'
  foo(21); // outputs '$var is not 0'
?>

GetSimple relies on functions so that users and developers can access certain data and output content. All of the template functions and plugin hooks/actions are examples of this.

Scope is about what domain in which a variable is affected. For example:

<?php
  $var = 0;

  function foo() {
   echo $var;
  }

  foo();
?>

This code will produce an error. This is because the scope of $var within a function is native to that function itself, i.e. it is local. As such, there is technically no $var variable to echo.

Global variables can be accessed from anywhere in the script (once they exist). If a piece of code is not within a function, it is considered global, and hence affects global variables/constants/functions. To call a global variable from inside a function, you must first declare it as global.

<?php
  $var = 0;

  function foo() {
   global $var;
   echo $var;
  }

  foo();
?>

So that piece of code would evaluate correctly. The confusing thing about scope however is the following:

• Variables within a function are local, unless declared otherwise
• Constants within a function are global (if they have been defined globally)
• Constants defined within functions are also global (so there are no local constants, unless we are talking about PHP classes, covered later)
• Functions, unless a part of a class, are global
• So once a function is defined (globally), you can access it from within another function

They might not be confusing to everyone, but those facts are important to know (especially for the final heading).

So scope can easily mess up a script that one is writing if they don't have a clear idea of which scope they are using. Many PHP developers discourage the use of purely global coding and encourage a different approach - one where you can set up your code without worrying about whether its variables impact or change important existing ones: in essence, it lets you develop the code in isolation and implement it how you want to. This is Object Oriented PHP programming.

I cannot do a solid yet succinct writeup of OOP here, so you will most certainly need to do that reading elsewhere. What I will say is this: make an effort to understand it, because when I explain how to develop plugins, I will be doing so from within an OOP framework, not a procedural one.

XML is the main data format for GetSimple. Data gets stored in xml files, which we can both generate and parse using PHP. The easiest way to do so is through classes specifically designed to handled XML parsing (hence the necessity for understanding Object Oriented PHP). TheMatrix however is equipped with 2 particular classes: XML2Array and Array2XML. These allow you to parse XML structures as though they were multidimensional arrays and save them as well, saving you the hassle that would come with other XML parsers that treat the whole entity as an object (rather than an array).