From 17cc55c7d3648e982e5ac827695bcc6426722b69 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 12:07:01 +0200 Subject: [PATCH 1/9] Update guidelines.rst Added some additional information on using the Composer autoloader and /src/ in the Directory structure. Please review my interpretation maybe add something on LTS, will old /inc/ be deprecated in the future? --- source/plugins/guidelines.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index 7a7d785..ddf5cc5 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -6,6 +6,9 @@ Guidelines Directories structure ^^^^^^^^^^^^^^^^^^^^^ +PRE GLPI10 +++++++++++ + Real structure will depend of what your plugin propose. See :doc:`requirements ` to find out what is needed. You may also want to :ref:`take a look at GLPI File Hierarchy Standard `. .. warning:: @@ -50,6 +53,20 @@ The plugin directory structure should look like the following: * `MyPlugin.xml` and `MyPlugin.png` can be used to reference your plugin on the `plugins directory website `_, * the required `setup.php` and `hook.php` files. +POST GLPI10 ++++++++++++ + +In GLPI 10 and newer installations you are adviced to use namespaces and composer autoloader. Objectfiles using namespaces are no longer loaded by the old autoload.function.php but by the newer Composer autoloader. In order to use the composer autoloader in your plugin must place your classfiles in the `src/` directory instead of the `inc/`. In this scenario the `/inc` directory should no longer be present in the plugin folder structure. + +The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `src` directory simply add them using the ucfirst convention. i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. + +Namespace mapping table: +|GlpiPlugin\|/plugins/ or /marketplace/| +|MyPlugin| /myplugin/src/ `strtolower`| +|ClassName | /ClassName.php `original`| +|SubFolder | /SubFolder `original`| + + Where to write files? +++++++++++++++++++++ From 62bfa2136ec14019388e83560191cd380fc997f4 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 16:16:58 +0200 Subject: [PATCH 2/9] Update guidelines.rst Created an actual RST table :S and added code examples --- source/plugins/guidelines.rst | 41 ++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index ddf5cc5..ac69b21 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -60,12 +60,41 @@ In GLPI 10 and newer installations you are adviced to use namespaces and compose The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `src` directory simply add them using the ucfirst convention. i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. -Namespace mapping table: -|GlpiPlugin\|/plugins/ or /marketplace/| -|MyPlugin| /myplugin/src/ `strtolower`| -|ClassName | /ClassName.php `original`| -|SubFolder | /SubFolder `original`| - +Namespace & use mapping table: +.. list-table:: Title + :widths: 50 50 + :header-rows: 1 +* - Namespace element + - Compose path mapping +* - GlpiPlugin\ + - Maps to `/plugins` or `/marketplace/` +* - MyPlugin\ + - Maps to /myplugin/src in `strtolower` +* - SubFolder\ + - Maps to: /SubFolder in provided case +* - ClassName + - Maps to: ClassName.php in provided case + +Examples: +`GLPI_ROOT/marketplace/myplugin/src/Test.php` +code-block:: php + + +`GLPI_ROOT/marketplace/myplugin/setup.php` +code-block:: php + Where to write files? +++++++++++++++++++++ From 9bc04d0119e08809b7ac7bc077b25bde64ccc0d7 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 16:18:35 +0200 Subject: [PATCH 3/9] Update guidelines.rst ... --- source/plugins/guidelines.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index ac69b21..b35a8e4 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -60,8 +60,7 @@ In GLPI 10 and newer installations you are adviced to use namespaces and compose The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `src` directory simply add them using the ucfirst convention. i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. -Namespace & use mapping table: -.. list-table:: Title +.. list-table:: Namespace & use mapping table :widths: 50 50 :header-rows: 1 * - Namespace element From e01450582d807edbbb6c76edd40d6364ade69973 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 16:19:12 +0200 Subject: [PATCH 4/9] Update guidelines.rst --- source/plugins/guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index b35a8e4..9b8ab46 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -60,7 +60,7 @@ In GLPI 10 and newer installations you are adviced to use namespaces and compose The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `src` directory simply add them using the ucfirst convention. i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. -.. list-table:: Namespace & use mapping table +.. list-table:: "Namespace & use mapping table" :widths: 50 50 :header-rows: 1 * - Namespace element From 294fd15372077226cd1efee97f922b17a9768b52 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 16:19:35 +0200 Subject: [PATCH 5/9] Update guidelines.rst --- source/plugins/guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index 9b8ab46..46e75a3 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -60,7 +60,7 @@ In GLPI 10 and newer installations you are adviced to use namespaces and compose The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `src` directory simply add them using the ucfirst convention. i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. -.. list-table:: "Namespace & use mapping table" +.. list-table:: "mapping" :widths: 50 50 :header-rows: 1 * - Namespace element From 011b1a26c6cc07c5a7ae6907bfc411ed6a001ab5 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 17:41:16 +0200 Subject: [PATCH 6/9] Corrected the RST directives and text. --- .vscode/settings.json | 3 + source/plugins/guidelines.rst | 108 +++++++++++++++++++++------------- 2 files changed, 70 insertions(+), 41 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..a7d0fc7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "esbonio.sphinx.confDir": "" +} \ No newline at end of file diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index 46e75a3..adb6738 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -6,7 +6,7 @@ Guidelines Directories structure ^^^^^^^^^^^^^^^^^^^^^ -PRE GLPI10 +PRE GLPI 10 ++++++++++ Real structure will depend of what your plugin propose. See :doc:`requirements ` to find out what is needed. You may also want to :ref:`take a look at GLPI File Hierarchy Standard `. @@ -53,54 +53,80 @@ The plugin directory structure should look like the following: * `MyPlugin.xml` and `MyPlugin.png` can be used to reference your plugin on the `plugins directory website `_, * the required `setup.php` and `hook.php` files. -POST GLPI10 +POST GLPI 10 +++++++++++ -In GLPI 10 and newer installations you are adviced to use namespaces and composer autoloader. Objectfiles using namespaces are no longer loaded by the old autoload.function.php but by the newer Composer autoloader. In order to use the composer autoloader in your plugin must place your classfiles in the `src/` directory instead of the `inc/`. In this scenario the `/inc` directory should no longer be present in the plugin folder structure. - -The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `src` directory simply add them using the ucfirst convention. i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. - -.. list-table:: "mapping" - :widths: 50 50 - :header-rows: 1 -* - Namespace element - - Compose path mapping -* - GlpiPlugin\ - - Maps to `/plugins` or `/marketplace/` -* - MyPlugin\ - - Maps to /myplugin/src in `strtolower` -* - SubFolder\ - - Maps to: /SubFolder in provided case -* - ClassName - - Maps to: ClassName.php in provided case - -Examples: -`GLPI_ROOT/marketplace/myplugin/src/Test.php` -code-block:: php - - -`GLPI_ROOT/marketplace/myplugin/setup.php` -code-block:: php - +In GLPI 10 and newer installations you are adviced to use namespaces and composer autoloader. Objectfiles using namespaces are no longer loaded by the old autoload.function.php but by the newer Composer autoloader. In order to use the composer autoloader in your plugin must place your classfiles in the `/src` directory instead of the `/inc`. In this scenario the `/inc` directory should no longer be present in the plugin folder structure. + +The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `/src` directory simply add them to your namespace and use keywords i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. + ++-------------+------------------------------------------------------------+ +| Directive | Composer mapping | ++=============+============================================================+ +| \GlpiPlugin | maps to /plugins or /marketplace | ++-------------+------------------------------------------------------------+ +| \MyPlugin | maps to: /myplugin/src converted strtolower | ++-------------+------------------------------------------------------------+ +| \SubFolder | maps to /src/SubFolder/ using provided case | ++-------------+------------------------------------------------------------+ +| \ClassName | maps to ../ClassName.php using provided case apending .php | ++-------------+------------------------------------------------------------+ + + +GLPI_ROOT/marketplace/myplugin/src/Test.php + +.. code-block:: php + + + +GLPI_ROOT/marketplace/myplugin/src/ChildClass/ResultOutcomes.php + +.. code-block:: php + + + +GLPI_ROOT/marketplace/myplugin/setup.php + +.. code-block:: php + + + Where to write files? +++++++++++++++++++++ .. warning:: - Plugins my never ask user to give them write access on their own directory! + Plugins may never ask user to give them write access on their own directory! The GLPI installation already ask for administrator to get write access on its ``files`` directory; just use ``GLPI_PLUGIN_DOC_DIR/{plugin_name}`` (that would resolve to ``glpi_dir/files/_plugins/{plugin_name}`` in default basic installations). From 4a64691c4ea2baa6e816a85812975683cd6ba984 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 6 Jul 2023 17:59:18 +0200 Subject: [PATCH 7/9] Delete settings.json Should not be in the pull request. --- .vscode/settings.json | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index a7d0fc7..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "esbonio.sphinx.confDir": "" -} \ No newline at end of file From a163ac8b6cf377e83ba291352d2503c070ad666b Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 21 Aug 2025 18:40:15 +0200 Subject: [PATCH 8/9] Update guidelines.rst Co-authored-by: Curtis Conard --- source/plugins/guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index adb6738..905feaf 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -56,7 +56,7 @@ The plugin directory structure should look like the following: POST GLPI 10 +++++++++++ -In GLPI 10 and newer installations you are adviced to use namespaces and composer autoloader. Objectfiles using namespaces are no longer loaded by the old autoload.function.php but by the newer Composer autoloader. In order to use the composer autoloader in your plugin must place your classfiles in the `/src` directory instead of the `/inc`. In this scenario the `/inc` directory should no longer be present in the plugin folder structure. +In GLPI 10 and newer installations you are advised to use namespaces and the Composer PSR-4 autoloader. Classes using namespaces are no longer loaded by the old autoload.function.php but by the newer Composer autoloader. In order to use the Composer autoloader in your plugin, must place your PHP class files in the `/src` directory instead of `/inc`. In this scenario the `/inc` directory should no longer be present in the plugin folder structure. The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `/src` directory simply add them to your namespace and use keywords i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. From 88864f050a0b0cd8a2eb7b0dc75c86f7f62285d8 Mon Sep 17 00:00:00 2001 From: DonutsNL <97617761+DonutsNL@users.noreply.github.com> Date: Thu, 21 Aug 2025 18:40:20 +0200 Subject: [PATCH 9/9] Update guidelines.rst Co-authored-by: Curtis Conard --- source/plugins/guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/plugins/guidelines.rst b/source/plugins/guidelines.rst index 905feaf..ddf2eae 100644 --- a/source/plugins/guidelines.rst +++ b/source/plugins/guidelines.rst @@ -58,7 +58,7 @@ POST GLPI 10 In GLPI 10 and newer installations you are advised to use namespaces and the Composer PSR-4 autoloader. Classes using namespaces are no longer loaded by the old autoload.function.php but by the newer Composer autoloader. In order to use the Composer autoloader in your plugin, must place your PHP class files in the `/src` directory instead of `/inc`. In this scenario the `/inc` directory should no longer be present in the plugin folder structure. -The the convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every classfile in the `/src` directory and should be PHP convention be placed in the top of your classfile. Classfiles using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\Plugins\myplugin\src\ClassName.php`. To include folders inside the `/src` directory simply add them to your namespace and use keywords i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load `GLPI_ROOT\Plugins\myplugin\src\SubFolder\ClassName.php`. +The convention to be used is (Case sensitive): `namespace GlpiPlugin\Myplugin;`. The namespace should be added to every class in the `/src` directory and per the PSR-12 PHP convention be placed in the top of your class. Classes using the `GlpiPlugin\Myplugin\` namespaces will be loaded from: `GLPI_ROOT\plugins\myplugin\src\`. To include folders inside the `/src` directory simply add them to your namespace and use keywords i.e. `namespace GlpiPlugin\Myplugin\SubFolder\` will load from `GLPI_ROOT\plugins\myplugin\src\SubFolder\`. +-------------+------------------------------------------------------------+ | Directive | Composer mapping |