This plugin exists to make it easy to handle changes to component options (accessed by the “Options” button in the top right corner). Option changes are handled by Joomla and without a change handler, your component does not know they have happened. For some changes, this does not matter. But for others, you need to take some action when an option changes.

To make this easy, install the Option Changes Plugin and publish it. To make it work for you, add some code to your component install script. It is conveniently done as a method and you can use it with minimal changes:

private function registerWithOptionsHandler(): bool
{
	try
	{
		// Get the application
		$app = Factory::getApplication();
		
		// Register the component with the handler plugin
		$result = $app->triggerEvent('onRegisterComponent', [
			'com_yourcomponent',
			'YourNamespace\\Component\\YourComponent\\Administrator\\Helper\\OptionsHandler',
			'handleOptionsChange',
			true, // Call the method statically
			'com_config.component' // Context
		]);
		
		// Check if registration was successful
		if (isset($result[0]) && $result[0] === true)
		{
			// Registration successful
			Log::add(
				'Successfully registered com_yourcomponent with CompOptionsHandler plugin',
				Log::INFO,
				'com_yourcomponent'
			);
			
			return true;
		}
		else
		{
			// Registration failed or no plugin responded
			Log::add(
				'Failed to register com_yourcomponent with CompOptionsHandler plugin. Is the plugin installed and enabled?',
				Log::WARNING,
				'com_yourcomponent'
			);
			
			return false;
		}
	}
	catch (\Exception $e)
	{
		// Log any errors
		Log::add(
			'Error registering com_yourcomponent with CompOptionsHandler plugin: ' . $e->getMessage(),
			Log::ERROR,
			'com_yourcomponent'
		);
		
		return false;
	}
}

For example, UserPoints uses the following:

          'com_userpoints',
          OptionChange::class,
          'handleOptionsChange',
          true

which relies on the use statement:

   use BlackSheepResearch\Component\UserPoints\Site\Problems\OptionChange;

If you specify a static method, the plugin will simply call it. If you specify a non-static call, the plugin will create a new object - although this will not work if you use a class that requires parameters.

Once you have set this up, your method will be called if any of the options are changed through the Joomla administrator interface. This page tells you how to use the information provided, including a number of examples.