Code Hooks allow you to extend any class within the IPS Community Suite or an application installed. You can create Code Hooks in the Plugin Developer Center.
You'll notice that throughout the code, classes are defined beginning with an underscore, but called without. For example, in /system/Member/Member.php, the declaration for is:
namespace IPS; class _Member extends \IPS\Patterns\ActiveRecord
Yet throughout the code, \IPS\Member is called rather than \IPS\_Member. This is a technicality in how code hooks are facilitated through a strategy known as Monkey Patching. When creating your code hook, specify the class you want to extend without the underscore. When you're actually editing the code, it will say "extends _HOOK_CLASS_" - this is because the actual class it will extend will vary if more than one hook is overloading the same class.
You can edit code hooks either in the Plugin Developer Center or by manually editing the file which will have been created in /plugins/<your plugin>/hooks. Using the Plugin Developer Center has the benefit that all the properties and methods of the class you're extending (and classes that class extends) are shown in the sidebar, and clicking on any one will insert the declaration with the doc-comment into the editor.
Important things to remember when creating code hooks:
- The first line in the class that is created is //<?php - this is so if you want to edit the file in your own editor that syntax highlighting works properly, however the <?php tag should not be used uncommented.
- Your hook will specify that it extends _HOOK_CLASS_ - though this is syntactically wrong, this should not be changed. The system will automatically change it to the correct class which may vary if there is more than one hook on a single class.
- If your code causes a PHP error or throws a RuntimeException, your hook will be ignored and the system will revert to the default class. If you need to deliberately throw an exception, throw an object of an appropriate exception class.
- When overriding a method, you MUST call the parent method so that ultimately you are inserting your code at the beginning or end of the method. This is necessary for allowing hooks on the same method to work.
- When overriding a method, you MUST NOT copy code from the original method into your hook. This is necessary to ensure that your hook does not interfere with any bug fixes or changes made to the original class in future versions. Also, it is against the terms of the IPS Community Suite license to distribute any code within it.
Report Document