Add a "parent" criteria to wp_get_object_terms()
|Reported by:||mikeschinkel||Owned by:|
Currently the core function wp_get_object_terms() does not allow the developer to filter by the parent field in the wp_term_taxonomy table.
I found this limitation while doing a code review on a client's code. I wanted to recommend elimination of direct SQL queries to minimize kittens crying but found that currently it's not possible to limit the results returned by the SQL query to only those taxonomy items with a given parent.
This patch adds a parent option for the $args parameter to wp_get_object_terms(). While I was in there I noticed several other things which I added to the patch:
1.) It updates the header documentation to be easier to scan and to fix some of the errors which appear have resulted in code updates without documentation updates.
2.) It adds DISTINCT for all but 'all_with_object_id'==$fields as per @scribu's suggestion on ticket #11003.
3.) It changes the code so that only one (1) SQL query is run when 'tt_ids'==$fields instead of running the standard query and then throwing away its results to run the query a second time. However, please check my logic to make sure I didn't introduce an unintentional error here.
4.) I added an options for 'fields' of both 'id=>name' and 'id=>term' because I've needed both of those use-cases several times in the past.
FYI, this patch should be considered a superset of #11003.