DEV Community: Lee Noble

Evolution of PHP Object Instantiation with detailed error diagnostics

Lee Noble — Thu, 29 Apr 2021 20:18:24 +0000

I've recently devised a new method (to me) of object instantiation that I think I'm going to use a lot in my future developments. I strongly suspect it's an established design pattern that probably has a name, but I didn't get a CS qualification and I made it up myself.

I say made it up, but mathematicians are fond of stating how they discover new maths, that it already exists in nature and the structure of the universe, and in a similar way I suspect this pattern is a natural evolution that has occurred before, multiple times.

Private constructor with optional return object

Most basic object classes I create have private constructors and offer one or more public instantiation methods:

class token {
    public static function create(string $prop) : ?token {
        $token = null;
        if(is_valid($prop)){
            /* I use static routinely in case I want to extend 
            the class later */
            $token = new static();
            $token->prop = $prop;
        }
        return $token;
    }

    protected function __construct(){

    }
}

Cool, now when we call token::create('Foo') we may get a token object or we may get null. It's a start.

But what if something goes wrong? And we want to know what? NULL doesn't tell us a great deal.

Something I've done in the past is to pass in a generic error handler to the constructor.

class token {
    public static function create(string $prop, errorHandler $errorHandler) : ?token {
        $token = null;
        if(is_valid($prop)){
            /* I use static routinely in case I want to extend the 
            class later */
            $token = new static();
            $token->prop = $prop;
        } else {
            $errorHandler->addError(errorHandler::INVALID_PROPERTY, $prop.' is not a valid string for some reason.');
        }
        return $token;
    }
    ...
}

That's a bit better, we can give our errorHandler class any number of error constants and compile an array of error messages to feed back to the user.

The problem with this is two-fold. If the ::create method has more than a few parameters, devs have to pass defaults for all the intermediate properties before they can append the errorHandler object, unless we put it up front I suppose; and secondly we have to create the errorHandler object prior to creating the object we actually want, every single time. It adds a boilerplate overhead to every object instantiation that I'd rather avoid.

Introducing the requestResult object

The ::create method comes with the implication that it's kind of going to work...that it'll return an object of the correct type. Adding the ? on the typehint because things might go awry is where the problems arise.

What if we could be certain we're going to get back on object of a particular type? We could "request" an object and process the return result.

class token {
    public static function request(string $prop) : tokenRequestResult {
        $result = new tokenRequestResult();
        if(!is_valid($prop)){
            $result->addError(tokenRequestResult::INVALID_PROPERTY_VALUE);
        }
        if(!$result->getErrorMask()){
            $token = new static();
            $token->prop = $prop;
            $result->setObject($token);
        }
        return $result;
    }
    ....
}

I've defined an interface and abstract class to handle most of the functionality of the requestResult object.

interface requestResult {
    public function getErrorMask() : int;
    public function getErrorMessages() : array;
    // TODO: When PHP >= 7.4 add typehints as per commented lines below
    public function getObject();
    public function setObject($object);
//  public function getObject() : Object;
//  public function setObject(Object $object);
    public function addError(int $maskBit, ?string $message);
}

abstract class baseRequestResult implements requestResult {
    protected $errorMask = 0;
    protected $errorMessages = [];
    protected $object;

    public function getErrorMask(): int {
        return $this->errorMask;
    }

    public function getErrorMessages(): array {
        return $this->errorMessages;
    }

    public function buildErrorMessageList(dataWriter $writer) : string {
        $response = '';
        if(count($this->errorMessages)){
            $response .= $writer->beforeResults();

            foreach($this->errorMessages as $errorMessage){
                $response .= $writer->item((object)['message'=>$errorMessage]);
            }

            $response .= $writer->afterResults();
        } else {
            $response .= $writer->noResults();
        }
        return $response;
    }

    // TODO: When PHP >= 7.4 add typehints as per interface
    abstract public function getObject();
    abstract public function setObject($object);

    public function addError(int $maskBit, ?string $message) {
        $this->errorMask |= $maskBit;
        if($message && !in_array($message, $this->errorMessages)){
            $this->errorMessages[] = $message;
        }
    }
}

And the tokenRequest class is really very small and easily replicable for different object types:

class tokenRequestResult extends baseRequestResult {
    const INVALID_TYPE = 1<<0;
    const MATCHING_TOKEN_IN_USE = 1<<1;

    // TODO: When PHP >= 7.4 use typehint for \token here instead of instanceof condition
    public function setObject($token) {
        if($token instanceof \token){
            $this->object = $token;
        }
    }

    public function getObject() : \token {
        return $this->object;
    }
}

Externally, the API is then used like this:

$tokenResult = token::request('Foo');
if($tokenResult->getErrorMask()){
    /*
        There are errors that need handling. We can flesh out the 
        tokenRequestResult object to handle the various error mask values 
        and/or error messages, pass in a writer class to output the 
        errors to screen, whatever.
    */

} else {
    /*
        But if reported errors are 0 we can be confident that `->getObject()` 
        will get us our native `token` object and act accordingly
    */
    $token = $tokenResult->getObject();
    $token->callPublicMethodOfTokenObject();
}

I think this technique is going to prove pretty valuable in my work. Like I said, it's probably a documented pattern but given I don't know what it might be called I'm not sure how to begin looking it up.

If you happen to know its name, I'd be thankful, but if it's new to you I hope you find it useful.

Increase your browser count to improve productivity

Lee Noble — Tue, 03 Sep 2019 22:35:21 +0000

The proliferation of SaaS and other web-based applications has led to my routinely having multiple windows open with dozens of tabs. I'll try to limit task-specific tabs by closing them down when task switching but that's not always possible, especially if the task(s) I'm switching to are temporary and I need to keep my main task tabs accessible. But what's harder to manage are things like Jira, the odd PHPMyAdmin window, github pages and sites I use to consume audio in the background. These tabs tend to stay open permanently, and they can get lost in background windows or buried in a myriad of tiny tab icons. Finding the one I want in a hurry isn't always possible. I've used various browser plugins over the years to manage task specific sessions but task switching remains painful.

Last week I idly Googled for site specific browsers and what came back was Fluid. This might be old news to some, but it's absolutely been revolutionary for me. Jira now has its own application icon on the Command-tab overlay and Dock, along with Overcast, Workflowy and client specific PHPMyAdmin instances. This has freed up my main browser for tabs relating ONLY to the task I'm working on (side-tasks in separate windows notwithstanding), which eases the burden of task-switching considerably. It's also made the possibility of switching to a new main browser more likely, since I'm no longer invested so much in the ad-hoc window and tab formations of Chrome.

Preventing free-range Wordpress hooks

Lee Noble — Wed, 07 Aug 2019 08:46:20 +0000

One of the major frustrations I experience when developing for WordPress is the abundance of functionality that relies on writing opaque strings. The most common of these are Actions and Filters. Pretty much every tutorial or piece of documentation you might find on creating and applying filters will present you with code like this:

add_filter('post_class', 'my_post_class_modifier', 10);

function my_post_class_modifier($classes){
    if($myConditionIsMet){
      $classes[] = 'another-css-class';
    }
    return $classes;
}

I've always had a disdain for this approach. It requires:

Prefixing the function name with a clunky namespace to avoid potential clashes
Writing the function name twice, one of which is inside a string, so Intellisense won't be any help

You won't be able to option-click on the function name and find out where it's being called, or find the function by clicking on the calling code. This is more of an issue when you need to use the same function for multiple filters. Your function gets further and further away from the calling code and unless you're very organised your functions.php file (which by default is where you'll put this code) will end up becoming an unnavigable dumping area full of nasty opaque string function calls. Ack!

Object method hooks

Ok, so most of the time I am a little bit cleaner in my approach and I'll try to corral hooks related to eachother or to particular custom post types into a class. You can of course use object methods in your hooks.

class myClass {
    public function applyHooks(){
        add_action('hook_string', array($this, 'hookForThisThing'), 10);
    }

    public function hookForThisThing($arg){
        // Perform an action here
    }
}

This approach means you don't have to prefix faux namespaces to function names and it does at least allow you to more easily find the original priority value - you could even make it a property of the class.

You can also use class properties inside your function's body which is a nice way of passing arbitrary data to the conditionals within. But you still have to use opaque strings which I'm frankly just against. I want my IDE to write as much of my code as possible as there's less room for typographic errors. Remembering function names is also an issue. A proper IDE will help you find it even if you only know one word in its name (a good reason for writing clear and long if necessary function names).

Anonymous functions

One approach I've started to use more frequently is to just pass an anonymous function to the filter:

add_filter('post_class', function($classes){
    if($myConditionIsMet){
      $classes[] = 'another-css-class';
    }
    return $classes;
}, 10);

This has a few advantages:

No clunkily named loose function knocking around the functions file
The hook being used is adjacent to the function.
You can pass in local variables if you need to like this:

$mySpecialValue = 87;
add_filter('post_class', function($classes) use ($mySpecialValue) {
    if(count($classes) == $mySpecialValue){
      $classes[] = 'has-88-css-classes';
    }
    return $classes;
}, 10);

But disadvantages include the inability to use the function on multiple hooks, and crucially the ability to REMOVE the hooked function if you need to later. You can't use the WordPress remove_filter method using anonymous functions.

For the vast majority of cases though, this has worked well for me. I could always define the anonymous function as a variable if I needed to use it on multiple filters but that removal thing became a problem that I needed to solve.

The problem

I had a bit of a hacky filter that I needed to run on 'posts_where' to modify the main query. Once applied to the main query, however, it was subsequently applied to any and all other queries used within the page building process. In the past I'd removed this type of filter by use of the overly-convoluted method of applying an action to remove the filter on some arbitrary filter following the main query being run. This results in more cruft drifting about in the functions file. It also requires recall of the priority value since the removal parameters must match. If at some point in the future you, or another developer (you of the future is another developer), changes the priority on the original hook then your remove operation (which is buried in the body of an unrelated function somewhere else) won't work any more. Your IDE won't tell you about it either since this code is impenetrable.

I decided to see if I could make self-removing filter.

Introducing the Closure class

<?php
/*
 *
 */
namespace MyNamespace;

class closure {
    public $priority = 10;
    public $method;
    public $args = 1;
    public $hook;
    public $persistent = false;
    public $hookType;

    const TYPE_ACTION = 1;
    const TYPE_FILTER = 2;

    // Instantiators
    public static function createFilter($hook, $method, $priority=10, $args=1, $persistent=false, $hookType=self::TYPE_FILTER){
        $closure = new static();
        if(is_callable($method)) {
            $closure->hookType = $hookType;
            $closure->hook = $hook;
            $closure->method = $method;
            $closure->priority = $priority;
            $closure->args = $args;
            $closure->persistent = $persistent;
            static::apply($closure);
        } else {
            $closure = false;
        }
        return $closure;
    }

    public static function createAction($hook, $method, $priority=10, $args=1, $persistent=false){
        return static::createFilter($hook, $method, $priority, $args, $persistent, self::TYPE_ACTION);
    }

    public static function createPersistentFilter($hook, $method, $priority=10, $args=1){
        return static::createFilter($hook, $method, $priority, $args, true);
    }

    public static function createPersistentAction($hook, $method, $priority=10, $args=1){
        return static::createAction($hook, $method, $priority, $args, true);
    }

    // public API [WordPress needs public visibility]
    public function filter(){
        $args = func_get_args();
        $val = $args[0];
        if(is_callable($this->method)){
            $val = call_user_func_array($this->method, $args);
        }
        if(!$this->persistent) {
            static::remove($this);
        }
        if($this->hookType == self::TYPE_FILTER) {
            return $val;
        }
        return true;
    }

    // Utility methods
    public static function apply(closure $closure){
        if($closure->hookType == self::TYPE_ACTION){
            add_action($closure->hook, array($closure, 'filter'), $closure->priority, $closure->args);
        } else {
            add_filter($closure->hook, array($closure, 'filter'), $closure->priority, $closure->args);
        }
    }

    public static function remove(closure $closure){
        if($closure->hookType == self::TYPE_ACTION){
            remove_action($closure->hook, array($closure, 'filter'), $closure->priority);
        } else {
            remove_filter($closure->hook, array($closure, 'filter'), $closure->priority);
        }

    }
}

As long as it's created using the createFilter or createAction instantiation methods, then by default, a closure object will remove it's own hook the first time it's employed. You can use the persistent methods if you don't want it to do that, but as I'm not envisaging using this for every single action and filter, only for ones like my posts_where where I need it removed following its first application, then I'm happy for that to be the default.

Here's an example of the closure class in use:

use MyNamespace\closure;

$mySpecialVar = 4077;
closure::createFilter('posts_where', function($where) use ($mySpecialVar) {
  $currentWhere = preg_replace("'^\s?AND\s'i", '', $where);
  $where = ' AND wp_posts.ID IN (SELECT 
     DISTINCT mp_a.meta_value
     FROM wp_postmeta mp_a
     WHERE mp_a.meta_key = \'my_meta_key_im_looking_for\'
       AND mp_a.post_id = '.(1*$mySpecialVar).') 
     OR (' . $currentWhere . ') ';
  return $where;
});

If I needed to I could still store the closure object as a variable and use it on multiple filters. In fact I could probably add a method to the class to accept multiple filter strings to keep everything together.

Because the closure object remembers its own arguments, should you retain a copy of the closure you may at any time use the method:

closure::remove($myClosure);

to remove the hook. Changing the priority in the original closure creation won't now affect the removal.

Why sudoku aren't worth your time.

Lee Noble — Sun, 08 Jul 2018 18:41:34 +0000

I see quite a few posts around solving sudoku algorithmically in various languages. I used to do them the old fashioned way, but sudoku are in my opinion a worthless activity, barely qualifying as a puzzle. They aren't difficult to solve, and the ones that are, are just an test of your threshold for carrying out mundane repetitive tasks - the perfect job for a computer!

It was the early 21st century when Sudoku arrived on UK shores. Every national newspaper was worth nothing unless it had a new sudoku or three buried inside its pages, and having a long-term affinity with numbers and grid-based organisation, I was in!

I'd scribble those 20 lines on a scrap of paper or in a notepad and fill in the pre-determined numbers

Then it was just a matter of seeing which numbers were missing from each row, each column and each square until the job was done.

Efficiency drive

So, having a laser printer to hand, the first, most obvious efficiency I could make was printing out grids in advance. I could get six on a single sheet of A4, and using some DTP software I could draw quality lines of different thicknesses, just like the real thing:

All I needed to do was copy the numbers from the paper (or website more likely) and I was on my way to another hit of "aren't I clever?"

I'm not sure how long any of these stages lasted, it was a long time ago, but shortly thereafter I made a further efficiency in my pre-printed grid. At the top of every square I added the numbers 1 to 9:

These represented every number that could possibly be the correct one for the box in which it was contained. All I had to do was cross out the ones which were definitely ruled out by existing numbers in the grid, and if I ever crossed out 8 of the 9 numbers then I knew the answer was the one remaining, and that would mean it was possible to scratch off up to 19 other numbers from the same row, column or square resulting in a potential cascade of number filling. Oftimes I'd end up with pairs of the same numbers in the same row. That meant I could cross those numbers off from any of the other boxes in the same row (or square or column - you get the idea

That was it, that's all there was to it. Cross the numbers off and it would practically solve itself. There was no skill involved, no great intelligence required, nothing could go wrong...

...except with the 'hard' or 'fiendish' sudoku, you'd eventually reach an impasse. It wasn't possible to complete the puzzle entirely, too many ambiguities remained. Reading on the internet abut how to solve these, you'll come across "Ariadne's Thread". That's how you solve these hard puzzles, using an ancient technique from folklore (or something), you would insert one of the two possibilities in a given square and play it out to resolution, except if it didn't work you'd just wind back "the thread" and try again using the other possibility.

What? That's it? That's trial and error. Any schmuck can use trial and error to solve it. Sure, there might be several junctions along the way to the solution where you were required to branch the thread again and keep going but that's all it boils down to. This is no proof of a higher intelligence, beyond perhaps being able to do a few steps along the thread in your head and perhaps realising you needed to choose the other option. All that's required is a pencil eraser or more grids of paper to start back at the previous crossroads.

It was, needless to say, at this point that I realised I was basically just carrying out a manual computer algorithm of elimination and guesswork. I wasn't exercising my brain. It wasn't much more challenging than a word-search, and I'd given up on those when I was about 11. Utterly pointless. I stopped doing sudoku immediately.

The fact that they are solvable at all using simple computer algorithms, means they aren't worth artificially taxing your human mind with. They're compiled by computers for computers.