Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added information #145

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .vscode/settings.json
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Forgot to add .vscode to .gitignore obviously xD sorry.

Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"esbonio.sphinx.confDir": ""
}
73 changes: 72 additions & 1 deletion source/plugins/guidelines.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ Guidelines
Directories structure
^^^^^^^^^^^^^^^^^^^^^

PRE GLPI 10
++++++++++

Real structure will depend of what your plugin propose. See :doc:`requirements <requirements>` to find out what is needed. You may also want to :ref:`take a look at GLPI File Hierarchy Standard <fhs>`.

.. warning::
Expand Down Expand Up @@ -50,12 +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 <http://plugins.glpi-project.org>`_,
* the required `setup.php` and `hook.php` files.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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\`.

Copy link
Author

@DonutsNL DonutsNL Jul 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct. Documenting this with the folder structure feels like a more natural place. Maybe place a reference back to the plugin structure paragraph somewhere in the 'adding and managing' objects paragraph.

I also tried to make it a bit more verbose for readers to understand whats going on so they are less likely to make typo mistakes and open issues because of this. Sorry for my roughly typed english ;-)


+-------------+------------------------------------------------------------+
| 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

<?php

namespace GlpiPlugin\MyPlugin;

class Test extends CommonDBTM
{
\\ Your class code...
}

?>

GLPI_ROOT/marketplace/myplugin/src/ChildClass/ResultOutcomes.php

.. code-block:: php

<?php

namespace GlpiPlugin\MyPlugin\ChildClass;

class ResultOutcomes extends CommonDBTM
{
\\ Your class code...
}

?>

GLPI_ROOT/marketplace/myplugin/setup.php

.. code-block:: php

<?php

use GlpiPlugin\MyPlugin\Test;
use GlpiPlugin\Myplugin\ChildClass\ResultOutcomes;

function usingTest() : void
{
$t = new Test();
$r = new ResultOutcomes();
}

?>


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).

Expand Down