trunk/obj/module.class.php

<?php

/**
 * Le namespace auxquels tous les modules doivent appartenir
 */
namespace Module;

use \RuntimeException;
use \InvalidArgumentException;

require_once __DIR__.'/utils.class.php';
use \application;

require_once __DIR__.'/lien_module.class.php';
use \lien_module;

require_once __DIR__.'/om_dbform.class.php';
use \om_dbform;


/**
 * Classe (abstraite) représentant un module
 */
abstract class module {

    /**
     * Une instance du framework openmairie
     *
     * @var application
     */
    protected application $framework;

    /**
     * Le chemin vers le répertoire contenant ce module
     * @var string
     */
    public string $dir;

    /**
     * Une configuration statique
     */
    public array $conf = array();

    /**
     * Une liste de paramètres dynamiques
     */
    public array $params = array();

    /**
     * Une instance du lien avec l'objet auquel est associé ce module
     */
    public ?lien_module $object_link_instance = null;

    /**
     * Une instance de l'objet métier auquel est associé ce module
     */
    public ?om_dbform $object = null;

    /**
     * Renvoie la description du module (type libellé)
     *
     * @return string
     */
    abstract public function get_description();

    /**
     * Installe le module.
     *
     * @return bool  'true' si l'installation s'est bien passée, 'false' sinon
     */
    abstract public function install();

    /**
     * Désinstalle le module.
     *
     * @return bool  'true' si la désinstallation s'est bien passée, 'false' sinon
     */
    abstract public function uninstall();

    /**
     * Créer une instance de module
     *
     * @param  string          $dir  Le répertoire contenant le module
     * @param  application  $framework             Une instance du framework openmairie
     * @param  lien_module     $object_link_instance  Une instance d'objet lien
     * @param  om_dbform       $object  Une instance d'objet métier
     *
     * @return module
     */
    public function __construct(string $dir, application $framework, ?lien_module $object_link_instance = null, ?om_dbform $object = null) {
        $this->framework = $framework;
        $this->log(__METHOD__, '');
        $this->dir = $dir;
        $this->object_link_instance = $object_link_instance;
        $this->object = $object;
        $this->load_conf();
    }

    /**
     * Renvoie une représentation en "string" du module
     *
     * @return string
     */
    public function to_string() {
        $str = sprintf(
            '%s (id:%s, ordre:%s)',
            $this->get_short_name(),
            $this->get_object_link_instance_id(),
            $this->object_link_instance->getVal('ordre'));
        if (empty($this->object_link_instance)) {
            $str = sprintf(
                '%s (no object_link)',
                $this->get_short_name());
        }
        return $str;
    }

    /**
     * Permet d'effectuer des actions lors de l'instanciation
     *
     * @return void
     */
    public function setup() {
        $this->log(__METHOD__, 'BEGIN');
        $this->log(__METHOD__, 'END');
    }

    /**
     * Charge la configuration statique
     *
     * @return void
     */
    public function load_conf() {
        $conf_path = $this->get_conf_path();
        if (is_file($conf_path)) {
            $conf_path_ext = pathinfo($conf_path, PATHINFO_EXTENSION);
            switch($conf_path_ext) {
                case 'php':
                    $this->conf = include $conf_path;
                    break;
                case 'ini':
                    $this->conf = parse_ini_file($conf_path);
                    break;
                case 'json':
                    $this->conf = json_decode(
                        file_get_contents($conf_path), true,
                        512, JSON_THROW_ON_ERROR);
                    break;
            }
        }
    }

    /**
     * Renvoie le chemin vers la configuration statique du module
     *
     * @return string
     */
    protected function get_conf_path() {
        $this->log(__METHOD__, 'BEGIN');
        $module_name = $this->get_short_name();
        $ret = $this->dir."/$module_name.conf.php";
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie le nom court du module
     *
     * @return string
     */
    public function get_short_name() {
        $ref = new \ReflectionClass($this);
        return $ref->getShortName();
    }

    /**
     * Renvoie une URL (ou partie d'URL) pointant vers le répertoire contenant les "assets"
     * (ressources publiques) du module
     *
     * @return string
     */
    public function get_url_assets_path_base() {
        $this->log(__METHOD__, 'BEGIN');
        $base_dir = $this->dir;
        $app_dir = dirname(__DIR__);
        if (strpos($base_dir, $app_dir) !== 0) {
            throw new RuntimeException(
                "Invalid module directory '$base_dir' or application directory '$app_dir'"
            );
        }
        $base_url = str_replace($app_dir, '', $base_dir);
        $url = "../$base_url";
        $url_encoded = implode(
            '/', array_map(
                function ($v) { return rawurlencode($v); },
                explode('/', $url)));
        $ret = $url_encoded;
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Récupère la valeur d'une directive de configuration
     *
     * @param  string  $key  Le nom de la directive de configuration dont on veut la valeur
     *
     * @return mixed
     */
    protected function conf(string $key) {
        return $this->conf[$key] ?? null;
    }

    /**
     * Assigne/Enregistre les paramètres du modules.
     * Les formats d'entrée supportés sont INI et JSON.
     *
     * @param  string  $raw_params  Une chaine contenant les paramètres dans un format supporté
     * @param  string  $format      Le nom du format de la chaine des paramètres
     *
     * @return void
     */
    public function set_parameters(string $raw_params, string $format = 'INI') {
        $this->log(__METHOD__, "($format) BEGIN");
        switch(strtoupper($format)) {
            case 'INI':
                $this->log(__METHOD__, "parsing INI string:");
                $this->log(__METHOD__, var_export($raw_params, true));
                $params = parse_ini_string($raw_params);
                if ($params === false) {
                    $this->log(__METHOD__, "Failed to parse INI string: '$raw_params'", 'WARNING');
                }
                if (is_array($params)) {
                    $this->params = $params;
                }
                break;
            case 'JSON':
                $this->log(__METHOD__, "parsing JSON string:");
                $this->log(__METHOD__, var_export($raw_params, true));
                $params = json_decode(
                    $raw_params, true, 512/*, JSON_THROW_ON_ERROR*/);
                if (json_last_error() !== JSON_ERROR_NONE) {
                    $this->log(__METHOD__, var_export(json_last_error_msg(), true), 'WARNING');
                }
                if (is_array($params)) {
                    $this->params = $params;
                }
                break;
        }
        $this->log(__METHOD__, 'END');
    }

    /**
     * Renvoi le nom d'une méthode principale du module.
     * Celle-ci sera appelée à chaque hook et aurait en argument:
     * - le nom du hook
     * - l'objet courant
     * - les données du contaxte
     *
     * @return string|null
     */
    public function get_main_method() {
        $this->log(__METHOD__, 'BEGIN');
        $ret = null;
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie une liste d'action de portlet
     *
     * @return array
     */
    public function get_actions() {
        $this->log(__METHOD__, 'BEGIN');
        $ret = array();
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie la liste des déclencheurs (hooks) supporté par ce module
     *
     * @param  boolean  $in_business_term  'true' pour renvoyer la liste avec des termes business
     *
     * @return array
     */
    public function get_supported_hooks(bool $in_business_term = false) {
        $this->log(__METHOD__, 'BEGIN');
        $ret = array();
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie la liste des scripts Javascript a inclure dans la balise HTML <head>
     *
     * @return array
     */
    public function get_header_scripts_js() {
        $this->log(__METHOD__, 'BEGIN');
        $ret = array();
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie la liste des scripts Javascript a inclure dans le code HTML inline
     *
     * @param  string  $position  'top' pour inclure au début et 'bottom' à la fin
     *
     * @return array
     */
    public function get_inline_scripts_js(string $position) {
        $this->log(__METHOD__, "($position) BEGIN");
        if (! in_array($position, array('top', 'bottom'))) {
            throw InvalidArgumentException("Invalid position '$position' (must be: 'top' or 'bottom')");
        }
        $ret = array();
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie la liste des styles CSS a inclure dans la balise HTML <head>
     *
     * @return array
     */
    public function get_header_styles_css() {
        $this->log(__METHOD__, 'BEGIN');
        $ret = array();
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie la liste des styles CSS a inclure dans le code HTML inline
     *
     * @param  string  $position  'top' pour inclure au début et 'bottom' à la fin
     *
     * @return array
     */
    public function get_inline_styles_css(string $position) {
        $this->log(__METHOD__, "($position) BEGIN");
        if (! in_array($position, array('top', 'bottom'))) {
            throw InvalidArgumentException("Invalid position '$position' (must be: 'top' or 'bottom')");
        }
        $ret = array();
        $this->log(__METHOD__, 'return: '.var_export($ret, true));
        $this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Renvoie l'identifiant de la classe de l'objet lien, ou
     * null s'il n'y a pas d'objet lien
     *
     * @return int|null
     */
    public function get_object_link_instance_id() {
        //$this->log(__METHOD__, 'BEGIN');
        if (! empty($this->object_link_instance)) {
            $id_key = $this->object_link_instance->clePrimaire;
            $ret = $this->object_link_instance->getVal($id_key);
            //$this->log(__METHOD__, 'return: '.var_export($ret, true));
            //$this->log(__METHOD__, 'END');
            return $ret;
        }
        $ret = null;
        //$this->log(__METHOD__, 'return: '.var_export($ret, true));
        //$this->log(__METHOD__, 'END');
        return $ret;
    }

    /**
     * Log un message en lui ajoutant un préfixe.
     *
     * @param  string  $method   La méthode d'où provient le message (càd: __METHOD__)
     * @param  string  $message  Le message à écire dans le ficheir de logs
     * @param  string  $level    Le niveau de log
     *
     * @return void
     */
    protected function log(string $method, string $message, string $level = 'DEBUG') {

        // remplace la classe parente par la classe courante
        $ref = new \ReflectionClass($this);
        $parent_class_escaped = str_replace('\\', '\\\\', $ref->getParentClass()->getName());
        $method = preg_replace(
            '/^'.$parent_class_escaped.'/',
            $ref->getName(),
            $method);

        $namespace_escaped = str_replace('\\', '\\\\', $ref->getNamespaceName());
        $method_short = preg_replace('/^'.$namespace_escaped.'\\\\/', '', $method);

        $this->framework->log($method_short, $message, $level);
        //$this->framework->log($method_short, $message, $level, 'modules');
    }
}
1	mbideau	17302	<?php
2
3			/**
4			* Le namespace auxquels tous les modules doivent appartenir
5			*/
6			namespace Module;
7
8	mbideau	17460	use \RuntimeException;
9			use \InvalidArgumentException;
10
11	mbideau	17302	require_once __DIR__.'/utils.class.php';
12			use \application;
13
14			require_once __DIR__.'/lien_module.class.php';
15			use \lien_module;
16
17			require_once __DIR__.'/om_dbform.class.php';
18			use \om_dbform;
19
20
21			/**
22			* Classe (abstraite) représentant un module
23			*/
24			abstract class module {
25
26			/**
27			* Une instance du framework openmairie
28			*
29			* @var application
30			*/
31			protected application $framework;
32
33			/**
34			* Le chemin vers le répertoire contenant ce module
35			* @var string
36			*/
37	mbideau	17345	public string $dir;
38	mbideau	17302
39			/**
40			* Une configuration statique
41			*/
42	mbideau	17345	public array $conf = array();
43	mbideau	17302
44			/**
45			* Une liste de paramètres dynamiques
46			*/
47	mbideau	17345	public array $params = array();
48	mbideau	17302
49			/**
50			* Une instance du lien avec l'objet auquel est associé ce module
51			*/
52	mbideau	17345	public ?lien_module $object_link_instance = null;
53	mbideau	17302
54			/**
55			* Une instance de l'objet métier auquel est associé ce module
56			*/
57	mbideau	17345	public ?om_dbform $object = null;
58	mbideau	17302
59			/**
60			* Renvoie la description du module (type libellé)
61			*
62			* @return string
63			*/
64			abstract public function get_description();
65
66			/**
67			* Installe le module.
68			*
69			* @return bool 'true' si l'installation s'est bien passée, 'false' sinon
70			*/
71			abstract public function install();
72
73			/**
74			* Désinstalle le module.
75			*
76			* @return bool 'true' si la désinstallation s'est bien passée, 'false' sinon
77			*/
78			abstract public function uninstall();
79
80			/**
81			* Créer une instance de module
82			*
83			* @param string $dir Le répertoire contenant le module
84			* @param application $framework Une instance du framework openmairie
85			* @param lien_module $object_link_instance Une instance d'objet lien
86			* @param om_dbform $object Une instance d'objet métier
87			*
88			* @return module
89			*/
90			public function __construct(string $dir, application $framework, ?lien_module $object_link_instance = null, ?om_dbform $object = null) {
91	mbideau	17442	$this->framework = $framework;
92	mbideau	17302	$this->log(__METHOD__, '');
93			$this->dir = $dir;
94			$this->object_link_instance = $object_link_instance;
95			$this->object = $object;
96			$this->load_conf();
97			}
98
99			/**
100			* Renvoie une représentation en "string" du module
101			*
102			* @return string
103			*/
104			public function to_string() {
105			$str = sprintf(
106			'%s (id:%s, ordre:%s)',
107			$this->get_short_name(),
108			$this->get_object_link_instance_id(),
109			$this->object_link_instance->getVal('ordre'));
110			if (empty($this->object_link_instance)) {
111			$str = sprintf(
112			'%s (no object_link)',
113			$this->get_short_name());
114			}
115			return $str;
116			}
117
118			/**
119			* Permet d'effectuer des actions lors de l'instanciation
120			*
121			* @return void
122			*/
123			public function setup() {
124			$this->log(__METHOD__, 'BEGIN');
125			$this->log(__METHOD__, 'END');
126			}
127
128			/**
129			* Charge la configuration statique
130			*
131			* @return void
132			*/
133			public function load_conf() {
134			$conf_path = $this->get_conf_path();
135			if (is_file($conf_path)) {
136			$conf_path_ext = pathinfo($conf_path, PATHINFO_EXTENSION);
137			switch($conf_path_ext) {
138			case 'php':
139			$this->conf = include $conf_path;
140			break;
141			case 'ini':
142			$this->conf = parse_ini_file($conf_path);
143			break;
144			case 'json':
145			$this->conf = json_decode(
146			file_get_contents($conf_path), true,
147			512, JSON_THROW_ON_ERROR);
148			break;
149			}
150			}
151			}
152
153			/**
154			* Renvoie le chemin vers la configuration statique du module
155			*
156			* @return string
157			*/
158			protected function get_conf_path() {
159			$this->log(__METHOD__, 'BEGIN');
160			$module_name = $this->get_short_name();
161			$ret = $this->dir."/$module_name.conf.php";
162			$this->log(__METHOD__, 'return: '.var_export($ret, true));
163			$this->log(__METHOD__, 'END');
164			return $ret;
165			}
166
167			/**
168			* Renvoie le nom court du module
169			*
170			* @return string
171			*/
172			public function get_short_name() {
173			$ref = new \ReflectionClass($this);
174			return $ref->getShortName();
175			}
176
177			/**
178			* Renvoie une URL (ou partie d'URL) pointant vers le répertoire contenant les "assets"
179			* (ressources publiques) du module
180			*
181			* @return string
182			*/
183			public function get_url_assets_path_base() {
184			$this->log(__METHOD__, 'BEGIN');
185			$base_dir = $this->dir;
186			$app_dir = dirname(__DIR__);
187			if (strpos($base_dir, $app_dir) !== 0) {
188	mbideau	17460	throw new RuntimeException(
189	mbideau	17302	"Invalid module directory '$base_dir' or application directory '$app_dir'"
190			);
191			}
192			$base_url = str_replace($app_dir, '', $base_dir);
193			$url = "../$base_url";
194			$url_encoded = implode(
195			'/', array_map(
196			function ($v) { return rawurlencode($v); },
197			explode('/', $url)));
198			$ret = $url_encoded;
199			$this->log(__METHOD__, 'return: '.var_export($ret, true));
200			$this->log(__METHOD__, 'END');
201			return $ret;
202			}
203
204			/**
205			* Récupère la valeur d'une directive de configuration
206			*
207			* @param string $key Le nom de la directive de configuration dont on veut la valeur
208			*
209			* @return mixed
210			*/
211			protected function conf(string $key) {
212			return $this->conf[$key] ?? null;
213			}
214
215			/**
216			* Assigne/Enregistre les paramètres du modules.
217			* Les formats d'entrée supportés sont INI et JSON.
218			*
219			* @param string $raw_params Une chaine contenant les paramètres dans un format supporté
220			* @param string $format Le nom du format de la chaine des paramètres
221			*
222			* @return void
223			*/
224			public function set_parameters(string $raw_params, string $format = 'INI') {
225			$this->log(__METHOD__, "($format) BEGIN");
226			switch(strtoupper($format)) {
227			case 'INI':
228			$this->log(__METHOD__, "parsing INI string:");
229			$this->log(__METHOD__, var_export($raw_params, true));
230	mbideau	17426	$params = parse_ini_string($raw_params);
231			if ($params === false) {
232	mbideau	17444	$this->log(__METHOD__, "Failed to parse INI string: '$raw_params'", 'WARNING');
233	mbideau	17426	}
234			if (is_array($params)) {
235			$this->params = $params;
236			}
237	mbideau	17302	break;
238			case 'JSON':
239			$this->log(__METHOD__, "parsing JSON string:");
240			$this->log(__METHOD__, var_export($raw_params, true));
241	mbideau	17426	$params = json_decode(
242	mbideau	17302	$raw_params, true, 512/, JSON_THROW_ON_ERROR/);
243			if (json_last_error() !== JSON_ERROR_NONE) {
244	mbideau	17444	$this->log(__METHOD__, var_export(json_last_error_msg(), true), 'WARNING');
245	mbideau	17302	}
246	mbideau	17426	if (is_array($params)) {
247			$this->params = $params;
248			}
249	mbideau	17302	break;
250			}
251			$this->log(__METHOD__, 'END');
252			}
253
254			/**
255			* Renvoi le nom d'une méthode principale du module.
256			* Celle-ci sera appelée à chaque hook et aurait en argument:
257			* - le nom du hook
258			* - l'objet courant
259			* - les données du contaxte
260			*
261			* @return string\|null
262			*/
263			public function get_main_method() {
264			$this->log(__METHOD__, 'BEGIN');
265			$ret = null;
266			$this->log(__METHOD__, 'return: '.var_export($ret, true));
267			$this->log(__METHOD__, 'END');
268			return $ret;
269			}
270
271			/**
272			* Renvoie une liste d'action de portlet
273			*
274			* @return array
275			*/
276			public function get_actions() {
277			$this->log(__METHOD__, 'BEGIN');
278			$ret = array();
279			$this->log(__METHOD__, 'return: '.var_export($ret, true));
280			$this->log(__METHOD__, 'END');
281			return $ret;
282			}
283
284			/**
285			* Renvoie la liste des déclencheurs (hooks) supporté par ce module
286			*
287			* @param boolean $in_business_term 'true' pour renvoyer la liste avec des termes business
288			*
289			* @return array
290			*/
291			public function get_supported_hooks(bool $in_business_term = false) {
292			$this->log(__METHOD__, 'BEGIN');
293			$ret = array();
294			$this->log(__METHOD__, 'return: '.var_export($ret, true));
295			$this->log(__METHOD__, 'END');
296			return $ret;
297			}
298
299			/**
300			* Renvoie la liste des scripts Javascript a inclure dans la balise HTML <head>
301			*
302			* @return array
303			*/
304			public function get_header_scripts_js() {
305			$this->log(__METHOD__, 'BEGIN');
306			$ret = array();
307			$this->log(__METHOD__, 'return: '.var_export($ret, true));
308			$this->log(__METHOD__, 'END');
309			return $ret;
310			}
311
312			/**
313			* Renvoie la liste des scripts Javascript a inclure dans le code HTML inline
314			*
315			* @param string $position 'top' pour inclure au début et 'bottom' à la fin
316			*
317			* @return array
318			*/
319			public function get_inline_scripts_js(string $position) {
320			$this->log(__METHOD__, "($position) BEGIN");
321			if (! in_array($position, array('top', 'bottom'))) {
322			throw InvalidArgumentException("Invalid position '$position' (must be: 'top' or 'bottom')");
323			}
324			$ret = array();
325			$this->log(__METHOD__, 'return: '.var_export($ret, true));
326			$this->log(__METHOD__, 'END');
327			return $ret;
328			}
329
330			/**
331			* Renvoie la liste des styles CSS a inclure dans la balise HTML <head>
332			*
333			* @return array
334			*/
335			public function get_header_styles_css() {
336			$this->log(__METHOD__, 'BEGIN');
337			$ret = array();
338			$this->log(__METHOD__, 'return: '.var_export($ret, true));
339			$this->log(__METHOD__, 'END');
340			return $ret;
341			}
342
343			/**
344			* Renvoie la liste des styles CSS a inclure dans le code HTML inline
345			*
346			* @param string $position 'top' pour inclure au début et 'bottom' à la fin
347			*
348			* @return array
349			*/
350			public function get_inline_styles_css(string $position) {
351			$this->log(__METHOD__, "($position) BEGIN");
352			if (! in_array($position, array('top', 'bottom'))) {
353			throw InvalidArgumentException("Invalid position '$position' (must be: 'top' or 'bottom')");
354			}
355			$ret = array();
356			$this->log(__METHOD__, 'return: '.var_export($ret, true));
357			$this->log(__METHOD__, 'END');
358			return $ret;
359			}
360
361			/**
362			* Renvoie l'identifiant de la classe de l'objet lien, ou
363			* null s'il n'y a pas d'objet lien
364			*
365			* @return int\|null
366			*/
367			public function get_object_link_instance_id() {
368			//$this->log(__METHOD__, 'BEGIN');
369			if (! empty($this->object_link_instance)) {
370			$id_key = $this->object_link_instance->clePrimaire;
371			$ret = $this->object_link_instance->getVal($id_key);
372			//$this->log(__METHOD__, 'return: '.var_export($ret, true));
373			//$this->log(__METHOD__, 'END');
374			return $ret;
375			}
376			$ret = null;
377			//$this->log(__METHOD__, 'return: '.var_export($ret, true));
378			//$this->log(__METHOD__, 'END');
379			return $ret;
380			}
381
382			/**
383	mbideau	17442	* Log un message en lui ajoutant un préfixe.
384	mbideau	17302	*
385	mbideau	17442	* @param string $method La méthode d'où provient le message (càd: __METHOD__)
386			* @param string $message Le message à écire dans le ficheir de logs
387			* @param string $level Le niveau de log
388	mbideau	17302	*
389	mbideau	17442	* @return void
390	mbideau	17302	*/
391	mbideau	17442	protected function log(string $method, string $message, string $level = 'DEBUG') {
392	mbideau	17302
393			// remplace la classe parente par la classe courante
394	mbideau	17442	$ref = new \ReflectionClass($this);
395	mbideau	17302	$parent_class_escaped = str_replace('\\', '\\\\', $ref->getParentClass()->getName());
396			$method = preg_replace(
397			'/^'.$parent_class_escaped.'/',
398			$ref->getName(),
399			$method);
400
401			$namespace_escaped = str_replace('\\', '\\\\', $ref->getNamespaceName());
402			$method_short = preg_replace('/^'.$namespace_escaped.'\\\\/', '', $method);
403
404	mbideau	17442	$this->framework->log($method_short, $message, $level);
405			//$this->framework->log($method_short, $message, $level, 'modules');
406	mbideau	17302	}
407			}