Additional SNMP library output formatting options

[eskyuu]

RFC: https://wiki.php.net/rfc/snmp_improvements_2026

The SNMP library has more formatting options than php-snmp allows. This PR adds some additional functions to control how the net-snmp library returns results to PHP.

[eskyuu]

The net-snmp library has quite a few options for controlling how OIDs and values are displayed. PHP already has a number of examples of these:
https://www.php.net/manual/en/function.snmp-set-oid-output-format.php

The base purpose of this PR is to extend the number of options available to include all options supported by the net-snmp library. The SNMP library configuration is stored in global memory, so some of the code takes care of handling the state of the library when using the PHP SNMP object.

The implementation is to add 3 new functions that control all options for MIB parsing, string output and value output. These do duplicate the existing functions like snmp_set_enum_print(), snmp_set_quick_print(), but having both doesn't cause any issues. I think the new interface is more flexible (we only need a new ENUM for each new options instead of a get/set), and there is no harm in having both functions available for existing options. There is an option to deprecate the old functions if you want to standardise the way people control the library (and also to add get functions to read the current state of a given option).

I also added all new options as parameters to the PHP SNMP object.

Whenever a SNMP query is run from a PHP SNMP object, the existing state of the net-snmp library needs to be saved, then updated to match what the SNMP object wants, and finally restored back to the original state. I have created 2 functions (save_snmplib_output_options() and set_snmplib_output_options()) to make it easier to save and restore the state.

I also discovered that changes to the SNMP library state were persisting across PHP-FPM requests. I did this by running a script that updated the state, then running another script many times that performed a SNMP query and printed the output. The query script would produce inconsistent output depending on which FPM process handles the request. This led me to add PHP_RINIT_FUNCTION() and PHP_RSHUTDOWN_FUNCTION() code into the SNMP module to save the state of the SNMP library before a FPM request, and then restore it at the end.

[Girgias]

Can these be combined? If not maybe an enum is better so there is type safety.

[eskyuu]

What do you mean by type safety? I've extended the original technique used in the php-snmp code to copy the NETSNMP* enums directly so I can use pass them through to the netsnmp library calls. All values are checked before being used.

[Girgias]

What I mean was to use a PHP enum that translates to the C values (by using and use Z_PARAM_ENUM), rather than passing an int. It's type safety for the end user writing PHP code.

But if those contants can be bitmasked, that technique doesn't work.

[eskyuu]

How does this look now?

The only issue I can see is that the proposal was to merge this into the next release for all current versions, but Z_PARAM_ENUM() is not implemented in PHP 8.4 (and 8.5?)