feat(phpshell): run inline php-shell code

plugins/modules/pfsense_phpshell.py

@@ -0,0 +1,126 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2023, Martin Müller <[email protected]>
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = """
+---
+module: pfsense_phpshell
+version_added: X
+author: Martin Müller
+short_description: PHP Shell
+description:
+  - Run a php shell
+options:
+  cmd:
+    description: PHP Code to run
+    required: true
+    type: str
+"""
+
+EXAMPLES = """
+- name: run phpshell with code pfSense config.xml
+  pfsense_phpshell:
+    cmd: |
+      require_once("filter.inc");
+      require_once("squid.inc");
+      squid_resync("yes");
+"""
+
+RETURN = """
+rc:
+  description: Status code after run php-shell (could be changed using `exit(x)`)
+  returned: always
+  type: int
+  sample:
+    - 0
+stdout:
+  description: Output of the php-shell (include your code)
+  returned: always
+  type: string
+  sample:
+    - "pfSense shell: global $debug;
+       pfSense shell: $debug = 1;
+       pfSense shell: require_once(\"filter.inc\");
+       pfSense shell: require_once(\"squid.inc\");
+       pfSense shell: squid_resync(\"yes\");
+       pfSense shell: 
+       pfSense shell: exec
+       pfSense shell: exit"
+
+stdout:
+  description: Output on error of the php-shell
+  returned: always
+  type: string
+  sample: []
+changed:
+  description: It returns always true (you could overwrite with changed_when)
+  returned: always
+  type: bool
+failed:
+  description: rc is not 0 or stderr contains output (you still could overwrite with failed_when)
+  returned: failure
+  type: bool
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.pfsensible.core.plugins.module_utils.module_base import PFSenseModuleBase
+
+
+PHP_SHELL_ARGUMENT_SPEC = dict(
+    cmd=dict(required=True, type='str')
+)
+
+class PFSensePHPShellModule(PFSenseModuleBase):
+    """ module run php code on pfsense """
+
+    @staticmethod
+    def get_argument_spec():
+        """ return argument spec """
+        return PHP_SHELL_ARGUMENT_SPEC
+
+    ##############################
+    # init
+    #
+    def __init__(self, module, pfsense=None):
+        super(PFSensePHPShellModule, self).__init__(module, pfsense)
+        self.name = "pfsense_phpshell"
+        self.result['changed'] = True
+
+    ##############################
+    # run
+    #
+    def run(self, params):
+        (rc, stdout, stderr) = self.pfsense.phpshell(params['cmd'])
+        self.result.update({
+            'rc': rc,
+            'stdout': stdout,
+            'stderr': stderr,
+        })
+
+        if int(rc) != 0 or len(stderr) > 0:
+            self.module.failed_json('rc is not 0 or stderr contains output (you still could overwrite with failed_when)', **self.result)
+        else:
+            self.module.exit_json(**self.result)
+
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=PHP_SHELL_ARGUMENT_SPEC,
+        supports_check_mode=True)
+
+    pfmodule = PFSensePHPShellModule(module)
+    pfmodule.run(module.params)
+
+
+if __name__ == '__main__':
+    main()