Question

I’ve got a datasource that has a bunch of insert functions. Each function takes a list of items that should be inserted into the DB. Each of these items can either be successfully inserted or not. If they are not successfully inserted, I would like to know the reason why.

Are there best practices around what should be returned from a datasource insert function?

Initial thoughts:

Boolean Success: Doesn’t give me any reason on failure

Custom Response Object with Boolean Success and String Reason: Can’t handle >1 insert response

List of Custom Response Objects: Seems to do what I want…

Answer 1

If it were me, I would setup my API to throw exceptions if a row was not inserted correctly.

Would look something like (demonstrative only):

$dbo = new Database();

foreach ($items as $item) {

    try {
        $dbo->insert($item);

        Log::toLogfile('Row was successfully inserted');

    } catch (Exception $e) {

        // If an exception failed upon insert, I can log the message and move on
        error_log($e->getMessage());
    }
}

class Database
{
    public function insert(array $item) {

        // Here you can add any number of validators
        if (empty($item)) {
            throw new Exception(sprintf('Invalid $item array (%s)', serialize($item));
        }

        elseif (!array_key_exists('id', $item)) {
            throw new Exception(sprintf('Invalid $item[id] (%s)', serialize(item));
        }

        // Making a call to php function which returns bool
        //  No problem, we test for return value and throw exception accordingly
        if (!$this->dbo->insert($item)) {
            throw new Exception(sprintf('Row was not inserted (%s)', serialize($item));
        }

        // If we made it this far, we have successfully inserted a row
        //  And code resumes back up after call to this function was made
    }

Throwing exceptions is the best way to get a message back to the calling code, and it forces the calling code to handle the exception. By wrapping our $dbo->insert($item) call within a try / catch block, we can catch the exception, log it, and move onto the next item in the array.