Events

Events are fired after specific user actions and will pass event data to listeners, which in turn can execute code without returning any data, similar to action hooks. However, unlike hooks, event listeners can also run asynchronously when paired with the Queue Add-on.

Overview

Development & Support
Customizations are not included with support. We provide this information to make it easier for developers to extend the functionality. From time to time we may have some availability for custom work. Get in touch to see if there's an opportunity to work together.

An event is an action that typically takes place after some user interaction. Each event can have one or more listeners that react to the event. Events do not modify or return data, they only pass information over to event listeners.

For example, when a user submits a review, this fires the ReviewWasCreated event and existing listeners react to the event to:

  • Send e-email notifications
  • Post the review on Twitter
  • Post the review on Facebook
  • Post the review to the EasySocial or JomSocial activity streams (Joomla)
  • Trigger native Joomla plugin events or WordPress hooks

Event listeners run syncronously, one after the other, so this can delay the request response time after a user performs an action, especially if any of the events send out notifications, or require communicating with external APIs like for posting to Twitter or Facebook.

To improve performance, the Queue Add-on allows listeners to execute asyncrously, independent of the main program flow.

You can find a list of all the available events at the end of this article.

Getting Started

To start using events and listeners you need to create:

  1. A listener class that reacts to an existing event
  2. A listener provider to associated an existing event with your new listener

For example, to execute some logic when a listing search is performed, like storing the search terms, we create a new listener SaveListingSearchData that reacts to the ListingSearchWasPerformed event.

First, create the new listener SaveListingSearchData.

Joomla

templates/jreviews_overrides/events/listeners/save_listing_search_data.php

WordPress

jreviews_overrides/events/listeners/save_listing_search_data.php
<?php
namespace JReviews\Listeners;

defined( 'MVC_FRAMEWORK') or die;

use JReviews\Listeners\Traits\ListenerSetting;
use Clickfwd\Listener\QueueableListener;
use League\Event\EventInterface;

\S2App::import('ListenerTrait','listener_setting','jreviews');

class SaveListingSearchData extends QueueableListener
{
    use ListenerSetting;

    protected $queue = false;

    public function handle(EventInterface $event)
    {
		$payload = $event->getPayload();

		// Do something with the search terms, user id, etc.

		// Dump $payload to screen
		dd($payload);
    }
}

Next, create the listener provider.

Joomla

templates/jreviews_overrides/events/providers/custom_listener_provider.php

WordPress

jreviews_overrides/events/providers/custom_listener_provider.php

Clear Cache & File Registry
Clear the registry in the JReviews admin CP after creating new files in overrides.

Within a provider you can register listeners for several events, and also multiple listeners for a single event. In this example, we have one listener for one event.

<?php
defined( 'MVC_FRAMEWORK') or die;

use Clickfwd\Listener\ListenerProvider;

class CustomListenerProvider extends ListenerProvider
{
	protected $listen = [
		'JReviews\Events\ListingSearchWasPerformed' => [
			'JReviews\Listeners\SaveListingSearchData',
		]
	];
}

This example is for illustration purposes, so it doesn't do anything with the search data. Instead we dump the event payload to the screen and that looks like this:

array [
  "event_user_id" => "31"
  "event_ipaddress" => "127.0.0.1"
  "event_source" => "site"
  "data" => [
    "keywords" => "New York Hotels"
  ]
]

The payload is an associative array and in this case you can find the search data in the data key. It also includes other useful event-related information that can be used inside the listener.

There are other public methods available in the $event object that can come in handy when writing custom listeners.

Event Public Methods

The following is a list of public methods available in the EventInterface $event object that is passed to the handle method in all listeners:

  • $event->getPayload() → includes data and all other information available in the event
  • $event->get($key) → retrieves the value for $key in the data array
  • $event->getName() → event name
  • $event->getData() → the data array
  • $event->getEventUserId() → the ID of the user that initiated the action
  • $event->getEventIpAddress() → the IP address of the user that initiated the action
  • $event->getEventLocale() → the locale used at the action was initiated
  • $event->getEventSource() → the source of the event, site or admin

Depending on the type of event, you can also use additional public methods from the $event object to conviniently retrieve the listing, review, etc. related to that specific event.

  • $event->getListing() → retrieves the listing array
  • $event->getReview() → retrieves the review array
  • $event->getListingFromReview($review) → given the $review array, retrieves the listing array
  • $event->getMedia() → retrieves the media array
  • $event->getOwnerReply() → retrieves the owner reply array
  • $event->getPost() → retrieves the review discussion (comment) array

To get a better sense of how these can be used, you can look at the code for existing listeners and check some of the tutorials.

Examples & Tutorials

You can find examples to use as reference within the JReviews and Add-ons source code. In JReviews you can look in the following directories.

Joomla

components/com_jreviews/jreviews/events/listeners/
components/com_jreviews/jreviews/cms_compat/joomla/events/listeners/
components/com_jreviews/jreviews/events/providers/jreviews_listener_provider.php
components/com_jreviews/jreviews/cms_compat/joomla/events/providers/jreviews_joomla_listener_provider.php

WordPress

wp-content/plulgins/jreviews/jreviews/events/listeners/
wp-content/plulgins/jreviews/jreviews/cms_compat/wordpress/events/listeners/
wp-content/plugins/jreviews/jreviews/events/providers/jreviews_listener_provider.php
wp-content/plugins/jreviews/jreviews/cms_compat/wordpress/events/providers/jreviews_wordpress_listener_provider.php

You can also find development tutorials in our blog:

Available Events

Wildcard

The wildcard event allows you to listen to any fired event. You can use a wildcard "*" as the event name in your listener provider. Like this:

class CustomListenerProvider extends ListenerProvider
{
	protected $listen = [
		'*' => [
			'JReviews\Listeners\CustomListener'
		],
	];
}

Then, inside your listener, you can check for specific events being fired using the $event->getName() method. This event is useful for debugging purposes or if you want to execute the same code for multiple events. You can check the event name and only execute the code if it matches one of the desired events.

Listings
JReviews\Events\ListingWasCreated
JReviews\Events\ListingWasUpdated
JReviews\Events\ListingWasStored
JReviews\Events\ListingWasFirstPublished
JReviews\Events\ListingWasDeleted
JReviews\Events\ListingWasAddedToFavorites
JReviews\Events\ListingWasRemovedFromFavorites
JReviews\Events\ListingWasFeatured
JReviews\Events\ListingWasUnfeatured
JReviews\Events\ListingWasHeldInModeration
JReviews\Events\ListingWasAcceptedInModeration
JReviews\Events\ListingWasRejectedInModeration
JReviews\Events\ListingInquiryWasCreated
JReviews\Events\ClaimWasCreated
JReviews\Events\ClaimWasAcceptedInModeration
JReviews\Events\ClaimWasHeldInModeration
JReviews\Events\ClaimWasRejectedInModeration
Reviews
JReviews\Events\ReviewWasCreated
JReviews\Events\ReviewWasUpdated
JReviews\Events\ReviewWasFirstPublished
JReviews\Events\ReviewWasDeleted
JReviews\Events\ReviewWasUpvoted
JReviews\Events\ReviewWasDownvoted
JReviews\Events\ReviewWasHeldInModeration
JReviews\Events\ReviewWasAcceptedInModeration
JReviews\Events\ReviewWasRejectedInModeration
Owner Replies to Reviews
JReviews\Events\OwnerReplyWasCreated
JReviews\Events\OwnerReplyWasUpdated
JReviews\Events\OwnerReplyWasFirstPublished
JReviews\Events\OwnerReplyWasDeleted
JReviews\Events\OwnerReplyWasHeldInModeration
JReviews\Events\OwnerReplyWasAcceptedInModeration
JReviews\Events\OwnerReplyWasRejectedInModeration
Review Discussions
JReviews\Events\ReviewDiscussionWasCreated
JReviews\Events\ReviewDiscussionWasUpdated
JReviews\Events\ReviewDiscussionWasFirstPublished
JReviews\Events\ReviewDiscussionWasDeleted
JReviews\Events\ReviewDiscussionWasHeldInModeration
JReviews\Events\ReviewDiscussionWasAcceptedInModeration
JReviews\Events\ReviewDiscussionWasRejectedInModeration
Media
JReviews\Events\MediaWasUploaded
JReviews\Events\MediaWasFirstPublished
JReviews\Events\MediaWasDeleted
JReviews\Events\MediaWasUpdated
JReviews\Events\MediaEncodingWasCompleted
JReviews\Events\MediaWasLiked
JReviews\Events\MediaWasDisliked
JReviews\Events\MediaWasHeldInModeration
JReviews\Events\MediaWasAcceptedInModeration
JReviews\Events\MediaWasRejectedInModeration
JReviews\Events\ListingMediaWasUploaded
JReviews\Events\ReviewMediaWasUploaded
JReviews\Events\ListingPhotoWasFirstPublished
JReviews\Events\ListingVideoWasFirstPublished
JReviews\Events\ListingAttachmentWasFirstPublished
JReviews\Events\ListingAudioWasFirstPublished
JReviews\Events\ReviewPhotoWasFirstPublished
JReviews\Events\ReviewVideoWasFirstPublished
JReviews\Events\ReviewAttachmentWasFirstPublished
JReviews\Events\ReviewAudioWasFirstPublished
Reports
JReviews\Events\ReviewWasReported
JReviews\Events\ReviewDiscussionWasReported
JReviews\Events\MediaWasReported
Search
JReviews\Events\ListingSearchWasPerformed
JReviews\Events\ReviewSearchWasPerformed
ListingResources Add-on
JReviews\Events\ListingResourceWasCreated
JReviews\Events\ListingResourceWasUpdated
MyLists Add-on
JReviews\Events\ListingWasAddedToList (since 3.0.0)
JReviews\Events\ListingWasRemovedFromList (since 3.0.0)