Jump to content

API docs for classDb.php


Wolfie

Recommended Posts

I remember there being a document at this URL:
http://community.invisionpower.com/resources/documentation/index.html/_/developer-resources/api-methods/classdb-r340

I really liked it as it made it easy to figure out how to use different DB calls. The one now, which looks to more teach about making a DB driver, looks like one long page of information and no 'sections' that are easy to spot when scrolling the page. For example in the older documentation, it was easy to scroll down and see titles for using buildAndFetch(), build(), exec(), etc.

Any chance the old link is still available (just hidden?) and can be restored? I can understand the need for one giving details for creating a new driver for compatibility, but for someone trying to look up the docs for learning the functions for creating a hook or app, it's unfriendly. Don't get me wrong, it's loaded with information, just hard to find what you need or to learn from it unless you already know half of what you're looking at.

Link to comment
Share on other sites

The section you'll find useful is entitled "Running Queries". That just deals with build, buildAndFetch, fetch, execute, etc.

That's like a small index compared to the page that used to be available. That little section is only useful to someone who is already familiar with the functions and just wants to make sure they're doing it right. Someone that's new to it will be as lost as before.
Link to comment
Share on other sites

The article linked to outlines every useful method in the driver - it is useful whether you're building your own, or just need to know everything the driver can do and what those functions are for.

I can't see value in having two similar articles on the database driver. It would probably just confuse most users trying to figure out "this one or that one".

Link to comment
Share on other sites

I can't see value in having two similar articles on the database driver. It would probably just confuse most users trying to figure out "this one or that one".


What about tweaking it some so it resembles the one that used to be available? What I liked about the other one is that the different functions were dumbed down some with examples and such. It helped me a lot and I'm sure could help others too. Even though I'm a bit more familiar with the functions, looking at it is still a bit intimidating. Imagine someone with even less knowledge (a hard as that can be) looking at it. They'd be scratching their head like a monkey doing a math problem.
Link to comment
Share on other sites

I liked the older article. It had specific examples like how to take your query and populate an array with it and how to do a query inside a foreach loop.

Made it easier to grasp what was being explain, right? I mean reading instructions is nice, but seeing simple to intermediate examples of how to use the functions (along with examples of things NOT to do) just helps. Heck I think I was actually able to read the code better than the actual instructions.
Link to comment
Share on other sites


Made it easier to grasp what was being explain, right? I mean reading instructions is nice, but seeing simple to intermediate examples of how to use the functions (along with examples of things NOT to do) just helps. Heck I think I was actually able to read the code better than the actual instructions.


Yeah. Examples change everything in terms of understanding. Like this post (http://community.invisionpower.com/topic/361437-creating-a-page-that-filters-by-custom-profile-field/#entry2259876) helped me to understand queries more than the docs did.
Link to comment
Share on other sites

Everything you guys are talking about is more or less there - sounds like you'd just like a handful of additional examples?

For instance, the section about fetch() shows building, executing a query and fetching the results. It doesn't assign the variable to another, but we could change the example to do that if it really helps.

I'm really just not all that keen on multiple documents on the same thing.

Link to comment
Share on other sites

sounds like you'd just like a handful of additional examples?


That's exactly it. If you want to keep it all in one document then that's fine, I don't see any problem with it. The documentation certainly helps and is informative, but having an example alongside everything makes it so much easier to understand. I don't know if you have the old documentation available, but that one was pretty well done in terms of examples.
Link to comment
Share on other sites

I'm really just not all that keen on multiple documents on the same thing.

I'm not saying to have multiple docs/pages about it. Assuming that the first one is just not publicly viewable, if you look at that one and the current public one, you'll see how the old one was not only much more informative, but also sort of 'walks you through' the process of understanding how to use each function individually. At least, that's how I remember it.

Heck, if I had a copy of the older one (and the newer one, both in source form), I'd be willing to try to piece them together in a way that keeps the benefits of the old content but inside of the new one, then I could send it to you and you could update it.
Link to comment
Share on other sites

  • 3 weeks later...

How about some lesser-known caveats?
anyone care to tell me *why* buildAndFetch has no implied LIMIT?


public function buildAndFetch( $data )

{

	 $this->build( $data );

	 $res = $this->execute();


	 if ( !empty($data['select']) )

	 {

	 return $this->fetch( $res );

	 }

}

Meaning SQL will happily scan the entire table for one result..... I have seen rare limit clauses on buildAndFetch, and now I know why, it returns but the one row, but selects all unless you specifically limit it.


public function buildAndFetch( $data )

{

if(empty($data['limit']))

{

$data['limit'] = array(0, 1);

}

	 $this->build( $data );

	 $res = $this->execute();


	 if ( !empty($data['select']) )

	 {

	 return $this->fetch( $res );

	 }

}

Seems more sane for general use, but documenting this hazard would be nice.... your example code assumes the same nonexistent limit is applied, or that the result set will only ever be one anyway.

As mentioned above, build() does not automatically execute the query. Quite commonly, the 'SELECT' query you are running is designed to return a single row and calling 3 methods to accomplish this is a lot of code in your application unnecessarily. In that instance, you can call buildAndFetch() exactly as you would for build(), and the first (or only) row is returned. Example:


$row = $this->DB->buildAndFetch( array( 'select' => '*', 'from' => 'mytable', 'where' => 'id=1' ) );


Unless the coder explicitly asks for more(in which case build should be used anyway), the first row should be the only row pulled.

Link to comment
Share on other sites

Archived

This topic is now archived and is closed to further replies.

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...