trunk/obj/module.class.php

<?php

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

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

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->log(__METHOD__, '');
        $this->dir = $dir;
        $this->framework = $framework;
        $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));
                $this->params = parse_ini_string($raw_params);
                break;
            case 'JSON':
                $this->log(__METHOD__, "parsing JSON string:");
                $this->log(__METHOD__, var_export($raw_params, true));
                $this->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));
                }
                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;
    }

    /**
     * Renvoie une méthode sans le namespace courant et tronquée à la longueur spécifiée.
     *
     * @param  string  $method  La méthode
     * @param     int  $length  La longueur max
     *
     * @return string
     */
    protected function shorten_method(string $method, int $length) {
        $ref = new \ReflectionClass($this);

        // remplace la classe parente par la classe courante
        $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);

        if (strlen($method_short) > ($length - 1)) {
            $method_short = substr($method_short, 0, $length - 1).'…';
        }

        return $method_short;
    }

    /**
     * Log un message en lui ajoutant un préfixe.
     *
     * @param  string  $message
     *
     * @return void
     */
    protected function log($method, $message, $type = DEBUG_MODE) {
        $logger = logger::instance();

        $logger->log($method." [] ".$message, $type);
        $method_len = 52;
        $method_short = $this->shorten_method($method, $method_len);

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