Creating Extensions

MrColor's color object can be extended by extending the Extension class and registering it either as a default extension for all color objects (current and future), or on a per object basis.

Building your extension

All you need to do to create a new extension for MrColor is to create a new class that extends the SyHolloway\MrColor\Extension class and put some methods in there. the default functionality for an extension occurs when a method is called on the Color class that doesn't exist. When this happens, registered extension classes are searched for methods of the same name to run instead. If a method is found it is run and passed the Color object the method was called from and any additional parameters. Any changes to the Color object change the original Color object (its the same object passed by reference). When the extension method returns a value, it is sent all the way back to the calling code.

Below is a basic example of an extension for MrColor:

<?php

use SyHolloway\MrColor\Color;
use SyHolloway\MrColor\Extension;

/**
 * My MrColor Extension
 *
 * @author you <you@yourdomain.com>
 */
class MyExtension extends Extension
{
    public function newFuncOne(Color $color, $extraParam)
    {
        //Edit the color object the function was called from
        $color->lightness = ($color->lightness < 0.5) ? $color->lightness + 0.5 : $color->lightness - 0.5
        
        //Use parameters 
        $message = 'The parameter "' . $extraParam . '" was sent';
        
        //Return a message to the client code
        return $message;
    }

    public function newFuncTwo(Color $color, $extraParamOne, $extraParamTwo)
    {
        //Edit the color object the function was called from
        $color->red = max(2, $color->red) / 2;
        $color->blue = min(127, $color->blue) * 2;
        
        //Use parameters 
        $message = $extraParamOne . ' + ' . $extraParamTwo . ' = ' . ($extraParamOne + $extraParamTwo);
        
        //Return a message to the client code
        return $message; 
    }
}

?>

Registering your extension

Once an extension is created, it must be registered. extensions can be registered in 2 ways; either register it as a default extension to make it apply to all Color objects, or apply it to a single Color object.

Register extension to all color objects

<?php

use SyHolloway\MrColor\ExtensionCollection;

ExtensionCollection::registerDefaultExtension(
    new MyExtension();
);

?>

Register extension to a single color object

<?php

use SyHolloway\MrColor\Color;

$color = Color::create();

$color->registerExtension(
    new MyExtension();
);

?>

Using your extension

Now your extension is created and registered, it is ready to be used!

See below for examples of our MyExtension class we have been working on:

<?php

use SyHolloway\MrColor\Color;

$color = Color::create();

// will increase lightness by 50%
$result = $color->newFuncOne('My String');

// will output: string 'The parameter "My String" was sent' (length=34)
var_dump($result);

$color = Color::create(array(
    'red' => 20,
    'green' => 20,
    'blue' => 20
));

// will make $color->red 10 and $color->blue 40
$result = $color->newFuncTwo(2, 4);

// will output: string '2 + 4 = 6' (length=9)
var_dump($result);

/*
 * in the case of static calls, a new Color object will created and sent 
 * as the first parameter to your extension class method, but because 
 * the string is returned instead of the new Color object, the new
 * Color object is no longer accessable anywhere, thus it is destroyed.
 */
$result = Color::newFuncTwo(5, 5);

// will output: string '5 + 5 = 10' (length=10)
var_dump($result);

?>

Overriding default extension functions

the SyHolloway\MrColor\Extension class has 2 methods that will happily be overridden by your child class.

Query

$extension->query() is called from the ExtensionCollection class when a method is called on a Color object/class that doesn't exist or can not be accessed (private/protected). The method name of the attempted call is sent to this query method, it is then your extension objects responsibility to decide if it wants to handle this method call. the expected response is a boolean, true to handle the method, false to ignore it and check other extensions.

The default query method is below:

<?php

public function query($method)
{
    // check to see if the method exists and is callable in the current extension
    return (is_callable(array($this, $method)));
}

?>

An example of an alternative query method is below:

<?php

public function query($method)
{
    $handle = false;
    
    // check if the method name starts with the word 'format' 
    if(substr($method, 0, 6) === 'format')
    {
        $handle  = true;
    }

    return $handle;
}

?>

Trigger

$extension->trigger() is called from the ExtensionCollection class when your query() method returns true. trigger is passed the Color object the method was called from (or a new Color object if called statically) as well as the method name and parameters of the attempted call. ExtensionCollection takes whatever is returned from your trigger method and returns it to the client code. because the Color object is passed (passing objects around is not quite but pretty much all done by reference as of PHP5) all changes made to the Color object in the extension will be made to the Color object the method was called from.

The default trigger method is below:

<?php

public function trigger(Color $color, $method, $args)
{
    if(is_callable(array($this, $method)))
    {
        array_unshift($args, $color);
        
        return call_user_func_array(array($this, $method), $args);
    }
    
    return null;
}
?>

An example of an alternative trigger method is below:

<?php

public function trigger(Color $color, $method, $args)
{
    return file_get_contents('http://myapiurl.com/api/v1/' . method . '/'. implode('&', $args) );
}
?>