extends Base_Object
Represents a single scheduled event in the Groundhogg event queue. Every time a contact moves through a funnel step, an event record is created to track it. Events have a status lifecycle: waiting → in_progress → complete (or failed, skipped, cancelled, paused).
Methods
| Method | Returns | Description |
|---|---|---|
get_id() | int | Returns the event ID. |
get_contact_id() | int | Returns the contact ID this event is for. |
get_contact() | Contact | Returns the Contact object. |
get_step_id() | int | Returns the step ID associated with this event. |
get_step() | Step | Returns the Step object. |
get_funnel_id() | int | Returns the funnel ID, or 0 for standalone events. |
get_funnel() | Funnel|false | Returns the Funnel object, or false for standalone events. |
get_email() | Email|false | Returns the Email object if this is an email event. |
get_time() | int | Returns the scheduled Unix timestamp. |
get_status() | string | Returns the current status string. |
get_failure_reason() | string | Returns the human-readable failure reason if the event failed. |
get_error_code() | string | Returns the error code if the event failed. |
get_error_message() | string | Returns the error message if the event failed. |
is_waiting() | bool | Returns true if the event is waiting to be processed. |
is_complete() | bool | Returns true if the event completed successfully. |
is_time() | bool | Returns true if the scheduled time has passed and the event is ready to run. |
is_funnel_event() | bool | Returns true if this event is part of a funnel. |
is_broadcast_event() | bool | Returns true if this event is part of a broadcast. |
run() | bool|WP_Error | Executes the event immediately. Returns true on success. |
queue() | bool | Sets the event status to waiting. |
cancel() | bool | Cancels the event. |
skip( $args = [] ) | bool | Marks the event as skipped and advances the contact. |
fail() | bool | Marks the event as failed. |
complete() | bool | Marks the event as complete. |
pause() | bool | Pauses the event. |
in_progress() | bool | Marks the event as in-progress. |
get_arg( string $arg, $default = false ) | mixed | Returns a named arg attached to this event (see add_event_args()). |
set_args( array $args ) | bool | Sets all args on this event at once. |
Usage
Here’s a pseudo code example for a hypothetical event monitoring integration.
<?php
add_action( 'groundhogg/event/failed', 'my_plugin_handle_failed_event' );
/**
* Alert the funnel owner when an event fails.
*
* @param \Groundhogg\Event $event
*
* @return void
*/
function my_plugin_handle_failed_event( $event ) {
$contact = $event->get_contact();
$step = $event->get_step();
if ( ! $contact || ! $step ) {
return;
}
$funnel = $step->get_funnel();
$owner = \Groundhogg\get_primary_owner();
if ( ! $owner ) {
return;
}
\Groundhogg\gh_mail(
$owner->user_email,
'Funnel event failed',
sprintf(
'Event for %s failed at step "%s" in funnel "%s". Reason: %s',
$contact->get_email(),
$step->get_title(),
$funnel ? $funnel->get_title() : 'unknown',
$event->get_failure_reason()
)
);
}
Was this helpful?
Let us know if this document answered your question. That’s the only way we can improve.