Function Return Values

[eluser]bhogg[/eluser]
Hi all,

I might be missing something obvious, but it seems many of the return values of functions like $this->db->update() are not explicitly specified anywhere in the documentation.

As an example for $this->db->query():

"The query() function returns a database result object when "read" type queries are run, which you can use to show your results. When "write" type queries are run it simply returns TRUE or FALSE depending on success or failure. When retrieving data you will typically assign the query to your own variable, like this:"

What about when a "read" type query is run and it fails, and assuming db debug is turned off? Does it return false? An empty object?

Things like $this->db->update() do not specify any return value in the documentation, so would need to test if doing something like:

Code:

if ($this->db->update('query...') !== FALSE)
{
   // show error
}

does what I would expect. Since it's not specified, it could return a boolean, throw an exception, return nothing at all, or depend on some other error() type function to be checked after the call is completed.

Just a thought to make things a bit more explicit for newcomers and people transitioning from other frameworks who want as much control over their code as possible.

Cheers,
Brian

[eluser]Phil Sturgeon[/eluser]
Each kind of SQL action has a different way to check if something is successful. It can be a little tricky and should be handled by default, but here is how I handle error/success.

Code:

// Insert - Did we get a new insert id
// returns: int/false
$this->db->insert('something', $data);
return $this->db->insert_id();

// update - Did it update, or was no change
// returns: true/false
return $this->db->update('something', $data, array('id'=>$id));

// Returning delete - Did anything delete?
// returns: true/false
$this->db->delete('something', array('id'=>$id));
retrun $this->db->affected_rows() > 0;

[eluser]bhogg[/eluser]
Sound these return values not be documented in the main documentation? Would think every function (not just DB) should explicitly state what the possible return values are, perhaps underneath the function name in smaller text... it's a core part of the function definition.

I feel like I may be volunteering to do this!

Cheers,
Brian

[eluser]Rey Philip Regis[/eluser]
You're right about that. Maybe they should also post the return values in the manual.

[eluser]Michael Wales[/eluser]
Note: All of this is off of memory, I don't have an environment to test.

Returning values from some of these functions can be a bit "iffy" - it really comes down to what you want. For instance:

Code:

$this->db->delete('users', array('username' => 'walesmd'));

There are a lot of pieces of information I need to test for after executing this code. Was the server contacted, was the command run successfully, did it actually delete a row from the database? There are more questions than a simple TRUE/FALSE could return.

So, do we return TRUE/FALSE based on whether the command was run (which is how I believe it works now) or do we return TRUE/FALSE if a row was deleted? If we switch to the latter, how do we know if the command wasn't run (for instance, there is no username row in the table).

I think the way CodeIgniter currently handles this is perfect but I do agree that the returned values could be documented better.

A piece of code like this usually works for me as it gives me the flexibility as a developer to log any issues, handle them gracefully so the user is not affected, and return useful data to the Controller.

Code:

function delete($username = NULL) {
  if ($username !== NULL) {
    if ($this->db->delete('users', array('username' => $username))) {
      if ($this->db->affected_rows() > 0) {
        return TRUE;
      }
    }
    log_message('error', 'Attempted to delete user ' . $username . ' failed (MySQL Error:' . mysql_error() . ')');
  }
  return FALSE;
}

[eluser]bhogg[/eluser]
Hi Michael,

I definitely agree, there's a lot of ways this could be handled. As long as whatever it does is documented, we can code against it and if there are any changes in future we'll know why.

Good memory by the way!

Cheers,
Brian

[eluser]gullah[/eluser]
bhogg if you are curious of what a lot of the magic behind it you can look at the core files. I've learned a lot by taking a peak in there and finding out what these magic functions do.

I'm not going to argue against more documentation though .

[eluser]Aken[/eluser]
Perhaps the Active Record commands could have a function that returns any necessary messages? $this->db->returned() or something similar, could contain an associative array of values, responding with things like if the server was contacted, if a row was deleted, etc.

I have no idea how the innards of the DB class work, so whether or not that's possible is beyond me. But it's a thought.