#coding stadnards

New Post has been published on http://mocco.sk/the-wordpress-coding-standards-database-queries-and-formatting-sql-queries/

The WordPress Coding Standards: Database Queries and Formatting SQL Queries

Aside from the summary that we’re going to be providing as the last article in this series, this is the last explication of the WordPress Coding Standards that we’re going to be covering in this series.

We’re going to be covering the nuances of database queries and how to format SQL within the context of your code.

Of course, this wouldn’t be without its own set of caveats: Generally speaking, there are APIs that are already available that can prevent us from needing to write SQL on our own; however, these APIs don’t catch every single case that we actually need.

After all, how can developers implementing APIs know exactly what and how we’re going to build something?

To that end, we’re going to take a look at the APIs that are available for executing database queries, how to use them, and then how to define our own queries when the APIs fall short.

Database Queries in WordPress

As mentioned in the introduction of this article, there are a number of APIs that make it possible for us to craft our own queries without needing to write SQL.

The reason that it’s important to become familiar and to learn these APIs is so that the code that you write will be written on top of the level of abstraction provided by WordPress to make sure the queries are as optimized as possible (given the current version).

Additionally, it increases the likelihood that any code that you write today will be compatible with future versions of WordPress primarily because, again, it’s written against the level of abstraction provided by WordPress.

If the table schema changes, parameters map to different clauses in the SQL, or so on, you don’t have to worry about it because the API will take care of it for you.

What Are the Query APIs?

So what are the query APIs that WordPress defines?

WP_Query is intended to be used to query information about any post type and its related author, category, taxonomies, type, status, and so on attributes.

WP_User_Query is intended to be used when we need to retrieve information from the user table and the usermeta table. It also allows us to work with roles, custom fields, and more.

There are also other WordPress API methods that make it really easy to grab stuff from various database tables some of which don’t even require a significant number of arguments:

get_post_meta retrieves meta data associated with a given post ID. It can retrieve all of the meta data or the value for a specific key.

get_comment_meta retrieves meta data associated with a given comment ID. It can retrieve all of the meta data or the value for a specific key.

get_user_meta retrieves meta data associated with a given user ID (are you starting to see a theme here?). It can retrieve all of the meta data or the value for a specific key.

Note that the purpose of this article isn’t to take a deep dive into each of these APIs (and there are more of them) – only to make them known to those of you who haven’t previously used them, and to given a short definition as to when they can be used.

Ultimately, these are the APIs that you should examine first before writing your own SQL. For what it’s worth, I’m speaking from experience here: There have been times where I’ve written code (or even blog posts) that have been busted because they weren’t using the best practices for querying the database.

But, as previously mentioned, these APIs can’t predict all cases in which we need to write our database queries. In those situations, WordPress provides an object that allows us to directly interact with the database.

All About $wpdb

That brings us to $wpdb. Essentially, $wpdb is an object that’s available in WordPress that allows us to interface directly with the database. This means that we’re able to write raw SQL and have it execute against the underlying database.

On top of that, we can select how we want the data returned: arrays, objects, sometimes single values, and so on. In fact, the object offers the ability to perform the following functions:

SELECT variables, rows, columns, and generic results

INSERT rows

UPDATE existing rows

Perhaps the largest concern when introducing raw SQL into your project is that you’re opening your project up to potential malicious behavior. Though you could make this case for any database logic, the truth is that APIs should do a good job of protecting us from anything like that.

Generally speaking, they do.

But $wpdb isn’t exempt from that either. There are specific ways to interface with the database so that you can protect your queries against SQL injection.

To reiterate a point from the the Coding Standards:

If you must touch the database, get in touch with some developers by posting a message to the wp-hackers mailing list. They may want to consider creating a function for the next WordPress version to cover the functionality you wanted.

So, in short, if the API falls short of what you need, then $wpdb may be your best option, but I recommend only using it if you’ve exhausted the rest of your options.

Conclusion

At this point, we’ve examined the Coding Standards in a level of detail that I hope equips you with information that you did not previously have when starting this series.

To conclude this particular post, the biggest take away that I want everyone to have is this:

Check the API before writing inline SQL. Even though writing direct SQL queries may be easiest, especially for those who are accomplished with database systems, resist the urge! Check the API documentation first.

If you can’t find an API function to do your work, then write SQL. If you must write SQL, make sure that you take all things necessary into account – how you want your data returned, you’ve properly prepared your queries, and you’re properly handling the data when it’s returned.

If you do that, then you should have your bases covered.

In the final article in this series, we’ll have a quick guide summarizing everything that we’ve discussed throughout the series.

Other parts in this series:

New Post has been published on http://mocco.sk/the-wordpress-coding-standards-the-ternary-operator-and-yoda-conditions/

The WordPress Coding Standards: The Ternary Operator and Yoda Conditions

At this point in the series, we’ve covered a lot of ground. Up to now, we’ve discussed the following topics:

Naming Conventions and Function Arguments

The Use of Single Quotes and Double Quotes

Indentation, Space Usage, and Trailing Spaces

Brace Style, Regular Expressions, and PHP Tags

Lots of stuff, right?

In this particular article, I thought we’d take it a bit easier before jumping into the final topic. As such, we’re going to cover two really simple topics (that are often either ignored or overcomplicated).

Specifically, we’re going to talk about the ternary operator and we’re going to talk about Yoda conditions.

A Word About WordPress Conditionals

When it comes to writing WordPress-based code, the Coding Standards strictly say that we should aim for readability first. Straight from the Codex:

In general, readability is more important than cleverness or brevity.

But there is a bit of a nuance to this. Some developers consider the ternary operator to be a bit at odds with this particular principle specifically because it’s yet-another-way of writing an if/else statement, and if the developer isn’t familiar with writing or reading the ternary operator then it’s in violation of this principle.

We’ll take a look at this more in depth in a moment.

The Ternary Operator

First, for those who are not familiar, the ternary operator is a simplified way of writing an if/else conditional statement. It’s typically used only when the conditional is of the simplest form and only when there is a single if and a single else block.

For example, let’s say that we have a conditional like this:

$uses_gasoline = null; if ( 'hybrid' == $car_type ) { $uses_gasoline = false; } else { $uses_gasoline = true; } echo $uses_gasoline;

Sure, this is a bit of a contrived example, but you get the point. After all, I’m simply trying to demonstrate how to convert a conditional like this into a form used by the ternary operator.

In keeping with the example above, you can do the following:

$uses_gasoline = 'hybrid' == $car_type ? false : true; echo $uses_gasoline;

Make sense? An important thing to notice: the ternary operator is testing for true (rather than false, obviously).

For what it’s worth, I find this to be a lot like reading a sentence. The first clause is asking a question (obviously punctuated by a question mark), with the two possible answers returned based on the evaluation of the conditional.

There is one caveat for checking for true all of which is documented in the Codex:

An exception would be using ! empty(), as testing for false here is generally more intuitive.

In my experience, that’s been the only time to use a negative evaluation in the conditional. All of the times that I’ve spent working with the ternary operator, I’ve found that testing for false often makes the ternary evaluation more difficult to decipher.

Additionally, I’ve found that it’s best to provide a single evaluation and maybe two evaluations under very simple, clear circumstances.

Other than that, that’s how you can use the ternary operator in your day-to-day WordPress work

Yoda Conditions

If you were following along closely, you’ll notice that I did something that most programming languages (or even PHP-based platforms outside of WordPress) don’t regularly do:

The conditional’s comparison was done by comparing the value to the variable; not the other way around.

Traditionally, we’d see something like this:

$uses_gasoline = null; if ( $car_type == 'hybrid' ) { $uses_gasoline = false; } else { $uses_gasoline = true; } echo $uses_gasoline;

And the corresponding ternary operator would look something like this:

$uses_gasoline = $car_type == 'hybrid' ? false : true; echo $uses_gasoline;

So if the majority of programming languages and platforms don’t use Yoda conditions, then why does WordPress?

According to the Codex:

In the above example, if you omit an equals sign (admit it, it happens even to the most seasoned of us), you’ll get a parse error, because you can’t assign to a constant like true. If the statement were the other way around ( $the_force = true ), the assignment would be perfectly valid, returning 1, causing the if statement to evaluate to true, and you could be chasing that bug for a while.

In my opinion, this is a really, really good explanation for performing comparisons like this especially within dynamically typed languages such as PHP and JavaScript.

Regardless of if you agree with this approach or not, it is part of the standard and you are going to see this used through WordPress core, themes, plugins, articles, and more.

To that end, I highly recommend beginning to implement in your own work.

Conclusion

As I mentioned at the beginning, this particular post was going to be much simpler and straightforward than some of the other material that we’ve covered in the series thus far.

At this point, we only have one more major topic to cover: Database Queries.

After that, we’ll be doing a review of all of the topics that we’ve outlined throughout this series in order to summarize the principles we’ve detailed from the Coding Standards.

But first, on to Database Queries.

Other parts in this series:The WordPress Coding Standards: Indentation, Space Usage, and Trailing SpacesThe WordPress Coding Standards: Braces, Regular Expressions, and PHP Tags