Events

Overview

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

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:

• Sharing listings on Pinterest using Zapier

Available Events

• Wildcard
• Listings
• Reviews
• Owner Replies
• Review Discussions
• Media
• Reports
• Search
• ListingResources Add-on
• MyLists Add-on

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.