Virion library framework

I know that someone is going to suggest Composer. Please, just forget it. Composer doesn't solve all problems, and isn't always suitable for all situations in PocketMine plugin development, at least for now.

Virion Library Framework is a system that allows injection of libraries into plugins. The unique advantage is that it adds a random string to the library namespaces, so whenever a Virion is injected into a plugin, the code in the plugin that uses classes from the Virion will be refactored, and the code from the Virion is refactored too before being copied to the phar. This ensures that even if multiple plugins are using different versions of the same Virion species (same namespace), they can still work together gracefully.
A Virion can be distributed as a phar, making it a portable object that can be deployed into a plugin phar file just by executing the phar.

Here is its proposal:

Spoiler: Proposal

How it works
How a Virion is developed

• The library is identified by a species, which is a namespace unique to the library. The namespace must not be a super-namespace for other libraries or plugins in the future. The species should contain the author name (or organization name), a namespace separator (backslash \), then the library name. For the library name, the longer the better.
• All classes, namespace constants and namespace functions declared by the library must be under the namespace of the species, or its sub-namespaces.
• Use of global variables is strongly discouraged, except for temporary global variables (where the global variable can be safely deleted or overwritten when another plugin executes something).
• How to support use of resource files in libraries is not finalized yet.

How a Virion is debugged

• Place the directory of the Virion in libs/ of a PocketMine installation (in the PocketMine data path, i.e. next to the plugins/ directory), such that there is a pocketmineDataPath/libs/any_random_name_for_this_library/src/Virion_species_name/ directory containing all your source files
• Install a Virion debugger plugin: Sterilizer (name yet to be confirmed).
• Write a plugin that tests against the Virion features, and set the softdepend of the plugin to Sterilizer. softdepend: [Sterilizer]

How a Virion is built into a phar
Note: Poggit-CI should add support to compile source into Virion .phar

• Basically, all source files in src/ will be copied to the same relative path in src/ in the phar.
• A .virus.yml (yet to be renamed) will be created in the phar, specifying the library name (trivial name), species and version.
• The library_stub.php in poggit will be set as the stub for all libraries.

1. Library is compiled into a Virion .phar file (Poggit-CI should add support for this)

• Basically, all source files in src/ will be copied to the same relative path in src/ in the phar.
• A .virus.yml (yet to be renamed) will be created in the phar, specifying the library name (trivial name), species and version.
• The library_stub.php in poggit will be set as the stub for all libraries.

1. Users can now download this Virion .phar file.

How a plugin using Virion is debugged
See How a Virion is debugged, except that instead of placing a directory any_random_name_for_this_library/, you place the phar of the Virion instead: pocketmineDataPath/libs/any_random_name_for_this_library.phar
How a plugin using Virion is built
Notes:

1. Poggit-CI should add support to build plugins with Virion injection
2. Poggit-CI will not directly run the stub file from the Virion, but use a version adapted for web servers without starting a separate PHP process.
3. If the library is:

• built with Poggit-CI, in the same GitHub repo (another build project) as the plugin: There should be support to add the library directly by specifying the project name, see README of poggit repo for example
• built with Poggit-CI, in a different GitHub repo from the plugin: There should be support to load (public repos only!) and add libraries directly by specifying the fully qualified project path (owner+repo+project), see README of poggit repo for example.
• not built with Poggit-CI: Poggit-CI should load and add libraries located in the libs/ directory under the project directory.
• Build the plugin into a standard .phar plugin. The phar may be having problems because the library is not yet injected.
• Run the Virion .phar with PHP directly, with the new plugin .phar file as the first argument: php ../libs/any_random_name_for_this_library.phar myPlugin.phar

You may find a link to this proposal on GitHub: https://github.com/poggit/poggit/issues/14

I am creating this thread to look for comments about this framework.

May I emphasize again: It's perfectly OK to compare this with Composer, but please don't ask "Why use this instead of Composer"! This framework is only designed to build libraries only for PocketMine plugins.

Also note: This is only for discussion. This is not an official release note for anything.

 

This is an example: https://github.com/poggit/libasynql
Some can get really useful. At least using them is easier than writing them.
Moreover, along with Poggit, it is easy to release Virion-infected plugins.

After all, deployment of virions is really simple.
Want to run your plugin that uses a virion? Drag it into your virions/ folder in the server data path.
Want to release your plugin that uses a virion? Run a phar, providing the path to your plugin phar file as a CLI argument or input it via STDIN. Done.

 

By the way, Virion is a planned feature in Poggit v2.0, which is quite distant. Therefore, suggestions on structural improvements are still welcome.

 

I would use stdClass for common data objects. If you have a class for it, it means that your classes have declared fields. Who knows if these data objects would change in structure one day?