Understanding the MODX getOption() Method

The $modx->getOption() method is the workhorse of MODX snippet code. There are over 1300 instances of it in my core/components/ directory. It’s used in almost any non-trivial snippet and many plugins as well. You may have some idea how it works, but there are some quirks and features that you may not know about.

MODX logo

Using getOption() for Settings

In its simplest form, $modx->getOption() is often used to get the value of a MODX System Setting:

$value = $modx->getOption(setting_name);

If the System Setting is found, $value will be set to its value. If not, it will be set to null. But what if you want to set a default value to use when the setting is not found?

$value = $modx->getOption(setting_name, null, 'default value');

The code above will return the value of the System Setting, or the default value if the Setting is not found. There’s a catch, though, what if you want to use the default value if the setting exists, but is empty? The code above will return an empty string. You could check the return value to see if it’s empty, but there’s an easier way. There’s a little-known fourth argument for getOption() called $skipEmpty in the method’s declaration. It’s a boolean argument, and when it’s set to true, the method will return the default value if the setting doesn’t exist or is empty.

$value = $modx->getOption(setting_name, null, 'default value', true);

PHP considers a variable containing the number 0 to be empty, but the getOption() method is smart enough not to do that. If the fourth argument is set to true and the setting exists and is set to 0, getOption() will return it rather than use the default value. On the other hand, it will return the default value if the property is truly empty even though the property exists (i.e., isset() would return true).

You might be wondering about the null we put as the second argument. The getOption() method can also be used to search the $scriptProperties array, or in fact, any array at all (more on that in a bit). The second argument is the array to search. If it’s set to null, getOption() looks only at the MODX Settings.

Settings?

If you’re paying close attention, you may have noticed that the last sentence above said, “MODX Settings” rather than “MODX System Settings”. The getOption() method will actually check all User Settings, Context Settings, and System Settings (in that order) when used as above.

Actually, it doesn’t check those three groups of settings in turn, though the result is the same. On every request, MODX creates a big array of settings. First, it gets the array of all System Settings, then it overwrites any of them that match current Context Settings (if any) with the Context Setting values, then it overwrites any of them that match User Settings for the current user (if any) with the values of the user settings. The resulting array is stored in the $modx->config array and that array is what getOption() checks if the second argument is null or only the first argument is sent. The result is the Context Settings override System Settings and User Settings override Context Settings.

Using getOption() with Snippet Properties

When you send properties in a snippet tag, they are available in the snippet as the $scriptProperties array, and getOption() is often used to retrieve them. It makes for shorter, easier to understand, safer code.

If you look at older MODX code, written before getOption() existed, you might find the first part of a snippet riddled with code like this example:


$defaultCount = 10;
if (isset($scriptProperties['count'])) {
    if ($scriptProperties['count'] === '0') }
       $count = 0;
    } elseif (!empty($scriptProperties['count'])) {
        $count = $scriptProperties['count']
    } else {
        $count = $defaultCount;
    }
} else {
    $count = $defaultCount;
}

There are a variety of ways to write this code, but no matter how you do it, it’s a lot of code, it’s difficult to follow, and there are a lot of ways to get it wrong, especially if you have to do it for every property that might be sent in the snippet tag. Enter $modx->getOption(). The code below does exactly the same thing:

$count = $modx->getOption('count', $scriptProperties, 10, true);

The variable, $scriptProperties is a pain to type. It’s also long enough that it can keep a statement from being displayed on a single line. In a lot of MODX code, you’ll see that the author has assigned that variable to one that’s shorter and easier to type. Here are some common examples:

$sp = $scriptProperties;
$config = $scriptProperties;
$props = $scriptProperties;

Or, in a class:

$this->sp = $scriptProperties;
$this->config = $scriptProperties;
$this->props = $scriptProperties;

You will sometimes see =& used instead of = in these cases. This is called a “reference” assignment. It sets the first variable to the actual address of the second one. In some languages, this would make things faster, but in PHP, it usually makes things slower. The only time it should be used in MODX is if you plan to alter the variable and want the original variable to change too. References to the $modx variable are often done this way because changes to that variable need to be available somewhere else. It’s never necessary for the $scriptProperties array if you’re just getting values from it.

Other Arrays

It’s a little-known fact, but getOption() can actually be used to find a value in *any* simple PHP associative array. The value sent in the second argument doesn’t have to be the $scriptProperties array, it can be any array (though if it’s a nested array, you may need some extra code). Consider the following example:

$a = array(
    'color1' => 'Red',
    'color2' => 'Blue',
    'color3' => 'Green',
);

$color1 = $modx->getOption('color1', $a, 'Gray');
$color2 = $modx->getOption('color2', $a, 'Gray);
$color5 = $modx->getOption('color5', $a, 'Gray);

The code above will set the three variables to Red, Blue, and Gray. What if, however, the array keys are numbers, not strings? This will actually work too:

$a = array(
    1 => 'Red',
    2 => 'Blue',
    4 => 'Green',
);

$color1 = $modx->getOption('1', $a, 'Gray');
$color2 = $modx->getOption('2', $a, 'Gray);
$color5 = $modx->getOption('5', $a, 'Gray);

 

Notice that in the example above, we’ve used quoted strings for the first argument to getOption(). That argument must *always* be a string. It doesn’t seem like it should work, but it does because of PHP’s loose typing of variables. The following, however, would not work because getOption() tests the first argument with is_string() and returns the default value if it’s not a string:

$color1 = $modx->getOption(1, $a, 'Gray');

But Wait, There’s More

A truly little-known (and little used) fact is that the *first* argument to getOption() can also be an array. Consider this code:

$a = array(
    1 => 'Red',
    2 => 'Blue',
    4 => 'Green',
);

$colors = $modx->getOption(array('1','2','5', $a, 'Gray'));

With the code above, getOption() will return the following array:

Array (
    [1] => Red
    [2] => Blue
    [5] => Gray
)

If getOption() is called with an array as the first argument, it will call itself recursively with each array member and build the array to return. I’ve never seen this option used in MODX, since the array you send in the second argument is *already* an array and contains all the information you need. In addition, the keys of the original array are lost in the process.

Potential Gotcha

There is another aspect of getOption() that could have you tearing your hair out if you don’t know about it. The getOption() method is a MODX method, not a generic PHP function. It has certain ideas about what you want. Most of the time, it works as expected, but it helps to be aware of exactly what it’s doing.

When getOption() doesn’t find the key you’re looking for, it doesn’t give up and return the default value. Instead, it searches the MODX Settings. This means that if you search for a snippet property called ‘emailSender’ and the property is not set, you’ll get back the value of the MODX emailSender System Setting (or a User Setting or Context Setting if there is one). This might be what you want to happen, but if it’s not, it can be very confusing. You shouldn’t use properties with the same name as MODX Settings unless you actually want this behavior.

Is That It?

Actually, no. There are a few quirks of getOption() that relate specifically to snippet properties sent in a snippet tag. We’ll look at those in the next article.


For more information on how to use MODX to create a web site, see my web site Bob’s Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for quality MODX Web Hosting? Look no further than Arvixe Web Hosting!

Tags: , , , , , , , , | Posted under MODX, MODX | RSS 2.0

Author Spotlight

Bob Ray

Bob Ray

I am the author of MODX: The Official Guide and over 30 MODX add-on components. I host Bob's Guides, a source of valuable information for MODX users, and I've been very active in the MODX Forums with over 14,000 posts.

Leave a Reply

Your email address will not be published. Required fields are marked *


7 − = 6

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>