\Patami\IPS\IOWebHookIOModule

Abstract base class for IPS WebHook modules.

This class extends the functionality provided by the Module class to handle requests sent via IPS' WebHook interface.

Summary

Methods
Properties
Constants
__construct()
Create()
Destroy()
GetConfigurationForm()
ApplyChanges()
GetId()
GetInstance()
GetModuleId()
GetModuleName()
GetModuleInstances()
IsValid()
GetParentId()
IsParentActive()
MessageSink()
SendEncodedDataToParent()
SendEncodedDataToChildren()
RegisterVariableBoolean()
RegisterVariableBooleanEx()
RegisterVariableFloat()
RegisterVariableFloatEx()
RegisterVariableInteger()
RegisterVariableIntegerEx()
RegisterVariableString()
RegisterVariableStringEx()
ShowSupportInfo()
Debug()
DebugEx()
GetWebHookSubPath()
GetWebHookPath()
GetURL()
ShowURL()
No public properties found
STATUS_INSTANCE_CREATING
STATUS_INSTANCE_ACTIVE
STATUS_INSTANCE_DELETING
STATUS_INSTANCE_INACTIVE
STATUS_INSTANCE_NOT_CREATED
DEBUG_TEXT
DEBUG_HEX
STATUS_ERROR_WEBHOOK_PATH_INVALID
STATUS_ERROR_WEBHOOK_INSTANCE_NOT_FOUND
STATUS_ERROR_WEBHOOK_ALREADY_REGISTERED
WEBHOOK_MODULE_ID
ProcessData()
ReadRequest()
ProcessRequest()
SendResponse()
GetClassFileName()
GetModuleDirectory()
GetModuleInfoFileName()
GetLibraryName()
GetConfigurationFormData()
Configure()
GetModuleFileInfo()
GetModulePrefix()
IsPrivate()
ListenForInstanceReloads()
OnKernelStarted()
OnKernelShutdown()
OnInstanceConnect()
OnMessage()
GetEncodedData()
GetSupportInfo()
GetLicenseUrl()
GetNewIssueUrl()
GetDocumentationUrl()
GetReleaseNotesUrl()
GetWebHookLabel()
GetDefaultWebHookSubPath()
RegisterHook()
UnregisterHook()
ProcessHookData()
$library
N/A
No private methods found
No private properties found
N/A

Constants

STATUS_INSTANCE_CREATING

STATUS_INSTANCE_CREATING

Instance is being created.

STATUS_INSTANCE_ACTIVE

STATUS_INSTANCE_ACTIVE

Instance is active and configuration is valid.

STATUS_INSTANCE_DELETING

STATUS_INSTANCE_DELETING

Instance is being deleted.

STATUS_INSTANCE_INACTIVE

STATUS_INSTANCE_INACTIVE

Instance is inactive (ie. disabled).

STATUS_INSTANCE_NOT_CREATED

STATUS_INSTANCE_NOT_CREATED

Instance is not yet created.

DEBUG_TEXT

DEBUG_TEXT

Use plain text for debug message.

DEBUG_HEX

DEBUG_HEX

Use hex for debug message.

STATUS_ERROR_WEBHOOK_PATH_INVALID

STATUS_ERROR_WEBHOOK_PATH_INVALID

WebHook path is invalid.

STATUS_ERROR_WEBHOOK_INSTANCE_NOT_FOUND

STATUS_ERROR_WEBHOOK_INSTANCE_NOT_FOUND

WebHook instance could not be found.

STATUS_ERROR_WEBHOOK_ALREADY_REGISTERED

STATUS_ERROR_WEBHOOK_ALREADY_REGISTERED

The same WebHook path is already registered by another instance or script.

WEBHOOK_MODULE_ID

WEBHOOK_MODULE_ID

IPS module GUID of the WebHook instance.

Properties

$library

$library : \Patami\IPS\Libraries\Library

Type

\Patami\IPS\Libraries\Library — IPS library object instance to which this module belongs to.

Methods

__construct()

__construct(integer  $instanceId) 

Module constructor.

Creates a new object of the IPS module instance. This method is automatically called by IPS when one of the registered functions are called or when the instance is used by IPS in any other way (eg. when creating the instance or when opening the configuration form).

Parameters

integer $instanceId

IPS object ID of the instance.

Create()

Create() 

Destroy()

Destroy() 

GetConfigurationForm()

GetConfigurationForm() : string

Returns the IPS module configuration form data as a JSON-encoded array.

This method will call Module::GetConfigurationFormData(), which returns an array with the configuration form elements, actions and translations. The array returned by the method is JSON-encoded and returned to IPS. The method adds a couple of form fields to the form, including module information and copyright information and two buttons which open the module documentation and release notes web pages.

Returns

string —

JSON-encoded configuration form data.

ApplyChanges()

ApplyChanges() 

Performs actions required when the configuration of this instance was saved.

It is automatically called by IPS when the use presses the apply button on the instance's configuration page and calls the Module::Configure() method which can be overridden by your own modules.

GetId()

GetId() : integer

Returns the IPS object ID of the instance.

Returns

integer —

IPS object ID of the instance.

GetInstance()

GetInstance() : \Patami\IPS\Objects\Instance

Returns an Instance object for the module instance.

Returns

\Patami\IPS\Objects\Instance

Instance object for the instance.

GetModuleId()

GetModuleId() : string

Returns the IPS module GUID of the module.

Returns

string —

IPS module GUID.

GetModuleName()

GetModuleName() : string

Returns the name of the module.

Returns

string —

Name of the module.

GetModuleInstances()

GetModuleInstances() : array

Returns a list of all IPS object IDs of all instances of the module.

Returns

array —

IPS object IDs of all instances of the module.

IsValid()

IsValid() : boolean

Checks if the instance if valid / active.

Returns

boolean —

True if the instance is active.

GetParentId()

GetParentId() : integer

Returns the IPS object ID of the parent IPS instance.

The parent instance is not the instance above the current instance in the IPS object tree, but the instance to which this instance is connected to.

Returns

integer —

IPS object ID of the parent instance.

IsParentActive()

IsParentActive() : boolean

Checks if the parent IPS instance is active.

Returns

boolean —

True if the parent IPS instance is active.

MessageSink()

MessageSink(integer  $timestamp, integer  $senderId, integer  $messageId, array  $data) 

Processes IPS messages.

This method is called by IPS for registered messages when they are triggered.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

integer $senderId

IPS object ID of the object that that triggered the message.

integer $messageId

ID of the message.

array $data

Event data.

SendEncodedDataToParent()

SendEncodedDataToParent(string  $dataId, array|mixed  $data) : string|null

Sends data to the parent IPS instance.

The data is received by the parent instance's IPSModule::ForwardData() method.

Parameters

string $dataId

GUID of the data packet type.

array|mixed $data

Data which should be encoded in the data packet.

Returns

string|null —

Result returned from the IPSModule::ForwardData() method.

SendEncodedDataToChildren()

SendEncodedDataToChildren(string  $dataId, array|mixed  $data) 

Sends data to all child IPS instances.

The data is received by the child instance's IPSModule::ReceiveData() method.

Parameters

string $dataId

GUID of the data packet type.

array|mixed $data

Data which should be encoded in the data packet.

RegisterVariableBoolean()

RegisterVariableBoolean(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new boolean status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableBooleanEx()

RegisterVariableBooleanEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new boolean status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableFloat()

RegisterVariableFloat(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new float status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableFloatEx()

RegisterVariableFloatEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new float status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableInteger()

RegisterVariableInteger(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new integer status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableIntegerEx()

RegisterVariableIntegerEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new integer status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableString()

RegisterVariableString(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new string status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the variable profile and the position of the variable, but not its name.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

RegisterVariableStringEx()

RegisterVariableStringEx(string  $ident, string  $name, string  $profile = '', integer  $position) : integer

Creates a new string status variable below the module instance.

This method should be called in the ApplyChanges() or Configure() methods. It will update the name, the variable profile and the position of the variable.

Parameters

string $ident

Ident of the status variable.

string $name

Name of the status variable.

string $profile

Variable profile name or an empty string for no variable profile.

integer $position

Relative position compared to the other objects below the module instance.

Returns

integer —

IPS object ID of the new status variable.

ShowSupportInfo()

ShowSupportInfo() 

Displays support info to the user.

Debug()

Debug(  $tag,   $message, array  $data = null) 

Parameters

$tag
$message
array $data

DebugEx()

DebugEx(string  $tag, string  $message, array|null  $data = null) : $this

Sends an extended debug message to the log.

Parameters

string $tag

Name of the sender of the log (can be used as a category or similar).

string $message

The log message.

array|null $data

Optional data to be added to the log entry.

Returns

$this —

Fluent interface.

GetWebHookSubPath()

GetWebHookSubPath() : string

Returns the configured WebHook sub path.

Returns

string —

WebHook sub path.

GetWebHookPath()

GetWebHookPath() : string

Returns the WebHook path.

All custom IPS WebHook paths are prefixed with /hook/.

Returns

string —

WebHook path.

GetURL()

GetURL() : string

Returns the IP Symcon Connect URL of the WebHook instance.

Returns

string —

URL of the instance.

ShowURL()

ShowURL() 

Displays the IP Symcon Connect URL of the WebHook instance.

ProcessData()

ProcessData() 

Processes a request.

This method is automatically called by the child class when a WebHook or WebOAuth is received. It reads the request, calls IOModule::ProcessRequest() to handle the request and sends the response returned by the handler to the remote client. The IOModule::ProcessRequest() implementation must not output anything. All output generated will be captured and logged in the module's debug log. The WebHookIOModule implementation of the method logs the client's IP address found in the HTTP_X_FORWARDED_FOR header, which is set by the IP-Symcon Connect reverse proxy.

ReadRequest()

ReadRequest() : string

Reads the incoming request from the raw HTTP request.

Returns

string —

Text of the incoming request.

ProcessRequest()

ProcessRequest(string  $text) : \Patami\IPS\IO\ResponseInterface

Processes the request received from the remote client and generates the response.

This method must be implemented by concrete child classes to implement the specific communication protocol.

Parameters

string $text

Text received from the remote client.

Returns

\Patami\IPS\IO\ResponseInterface

Response to be sent to the remote client.

SendResponse()

SendResponse(\Patami\IPS\IO\ResponseInterface  $response) 

Sends the response to the remote client.

Parameters

\Patami\IPS\IO\ResponseInterface $response

Response to be sent to the remote client.

GetClassFileName()

GetClassFileName() : string

Returns the file name of the class.

It always returns the name of the called class.

Returns

string —

File name of the class.

GetModuleDirectory()

GetModuleDirectory() : string

Returns the directory name of the module class file.

Returns

string —

Directory name of the class.

GetModuleInfoFileName()

GetModuleInfoFileName() 

GetLibraryName()

GetLibraryName() : string

Returns the key of the library to which the module belongs to.

Returns

string —

Key of the library.

GetConfigurationFormData()

GetConfigurationFormData() 

Returns the IPS module configuration form data.

{@inheritDoc} The WebHookIOModule implementation adds status codes, translations and a configuration form field to configure the WebHook path.

Configure()

Configure() 

Validates the WebHook path and registers it.

GetModuleFileInfo()

GetModuleFileInfo() : array

Returns information about the module from the module.json file.

Returns

array —

Attributes of the module.

GetModulePrefix()

GetModulePrefix() : string

Returns the prefix used by IPS to register the public module methods / functions.

Returns

string —

Function prefix.

IsPrivate()

IsPrivate() : boolean

Checks if the module is private.

A module is regarded as being private if its library is not loaded anonymously.

Returns

boolean —

True if the module is private.

ListenForInstanceReloads()

ListenForInstanceReloads(integer  $instanceId) 

Registers an instance to listen for reload events.

Parameters

integer $instanceId

IPS object ID of the other instance.

OnKernelStarted()

OnKernelStarted(integer  $timestamp, array  $data) 

Event handler called when the IPS kernel started.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

array $data

Event data.

OnKernelShutdown()

OnKernelShutdown(integer  $timestamp, array  $data) 

Event handler called when the IPS kernel is about to shutdown.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

array $data

Event data.

OnInstanceConnect()

OnInstanceConnect(integer  $timestamp, integer  $senderId, array  $data) 

Event handler called when another instance interface is connected.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

integer $senderId

IPS object ID of the object that that triggered the message.

array $data

Event data.

OnMessage()

OnMessage(integer  $timestamp, integer  $senderId, integer  $messageId, array  $data) 

Processes IPS messages.

This method is called by the frameork for registered messages when they are triggered.

Parameters

integer $timestamp

Unix timestamp when the message was triggered.

integer $senderId

IPS object ID of the object that that triggered the message.

integer $messageId

ID of the message.

array $data

Event data.

GetEncodedData()

GetEncodedData(string  $dataId, array  $data) : string

Encodes data to be send to child or parent IPS instances.

Parameters

string $dataId

GUID of the data packet type.

array $data

Data which should be encoded in the data packet.

Returns

string —

JSON-encoded data to be sent to child or parent IPS instances.

GetSupportInfo()

GetSupportInfo() : array

Returns support info to be displayed to the user.

Returns

array —

Key value pairs with support info.

GetLicenseUrl()

GetLicenseUrl() : string|null

Returns the URL the the module's license web page.

Override this method in your module to link to your own license.

Returns

string|null —

URL to the module's license web page or null if the button to open the web page should not be displayed in the module's configuration form.

GetNewIssueUrl()

GetNewIssueUrl() : string|null

Returns the URL to open a new issue in the module's issue tracker.

Override this method in your module to link to your issue tracker.

Returns

string|null —

URL to the create issue web page of your issue tracker or null if the button to open a new issue should not be displaxed in the module's configuration form.

GetDocumentationUrl()

GetDocumentationUrl() : string|null

Returns the URL to the module's documentation web page.

Override this method in your module to link to your own documentation.

Returns

string|null —

URL to the module's documentation web page or null if the button to open the web page should not be displayed in the module's configuration form.

GetReleaseNotesUrl()

GetReleaseNotesUrl() : string|null

Returns the URL to the module's release notes web page.

Override this method in your module to link to your own release notes.

Returns

string|null —

URL to the module's release notes web page or null if the button to open the web page should not be displayed in the module's configuration form.

GetWebHookLabel()

GetWebHookLabel() : string

Returns the translated label for the WebHook configuration field.

Returns

string —

WebHook configuration field label.

GetDefaultWebHookSubPath()

GetDefaultWebHookSubPath() : string

Returns the default WebHook sub path.

Returns

string —

Default WebHook sub path.

RegisterHook()

RegisterHook() : boolean

Registers the WebHook.

The method uses the configured WebHook sub path to register the WebHook with the IPS WebHook Control instance. IPS will call WebHookIOModule::ProcessHookData() when a request is received from a remote client.

Returns

boolean —

True if the WebHook was successfully registered.

UnregisterHook()

UnregisterHook(boolean  $setSummary = true) 

Unregisters the WebHook.

The method unregisters the WebHook from the IPS WebHook Control instance. It is automatically called when the module is deleted.

Parameters

boolean $setSummary

True if the summary text should be set.

ProcessHookData()

ProcessHookData() 

Processes a WebHook request.

This method is automatically called by the IPS WebHook Control instance.