New in AffiliateWP 2.7: affwp_get_{component}_by functions

Starting in AffiliateWP 2.7, we have a host of new “get by” helper functions in the global namespace for third-party developers to use. These functions should make getting core objects on a relational basis much easier.

Why create “get by” functions?

The “get by” functions work exactly like a lot of WordPress core’s similar-styled functions. The idea is to get an object by matching one of its fields with a value.

We’ve technically already supported the base logic the new functions offer, though now the functionality is far more discoverable. There’s also two important differences in how these new wrappers operate vs the older method higher up in the stack. These new functions:

  1. On success, the new functions return fully-qualified objects instead of stdClass objects. This means access to all of the extra helper methods we decorate our objects with.
  2. On failure, the new functions return WP_Error objects instead of false. For obvious reasons this makes down-stack troubleshooting and logging quite a bit more dynamic.

Note: The new affwp_get_{component}_by() functions return WP_Error objects on failure instead of false.

Use cases

Take the new affwp_get_affiliate_by() function, for instance. In the past, affwp_get_affiliate() could be used to retrieve an affiliate object if you knew the affiliate ID or the username. If you didn’t have either of those fields, but had the user ID, you had to either call affiliate_wp()->affiliates->get_by( 'user_id', $user_id ) or call something else to get the affiliate ID or username to use with affwp_get_affiliate().

Now, affwp_get_affiliate_by( 'user_id', $user_id ) is a thing.

Another of the most common use-cases in AffiliateWP core is retrieving a referral object by its reference value. Previously, this was commonly accomplished using affiliate_wp()->referrals->get_by().

Now, affwp_get_referral_by( 'reference', $value ) is the preferred method.

If you’re wondering why we’ve introduced these new global functions instead of just using affiliate_wp()->component->get_by() everywhere, the answer is pretty simple. We eventually need the flexibility to refactor the database internals, and so we’re establishing usage of the affwp_get_{component}_by() functions as best practice starting now.

If you’re using affiliate_wp()->{component}->get_by() in your third party code, we highly encourage you to update to use the new affwp_get_{component}_by() wrappers instead.

Full list of new “get by” functions

Here’s the full list of new “get by” functions:

  • affwp_get_affiliate_by()
  • affwp_get_coupon_by()
  • affwp_get_creative_by()
  • affwp_get_customer_by()
  • affwp_get_payout_by()
  • affwp_get_referral_by()
  • affwp_get_sale_by()
  • affwp_get_visit_by()
  • affwp_get_rest_consumer_by()

Coming up in AffiliateWP

That’s about it in terms of new helper functions in AffiliateWP 2.7 and beyond. If you haven’t seen the recent updates here on the development blog, we’ll be releasing AffiliateWP 2.7 Beta 1 later today.

Please subscribe to the blog feed if you haven’t and if you’re interested in helping us test AffiliateWP 2.7 Beta 1, make sure to opt-in to beta releases in the Affiliates -> Settings -> Misc screen in your WordPress admin.

Leave a Reply

Your email address will not be published. Required fields are marked *