https://github.com/jaxkdev/composershader
Shade/Inject composer dependencies into PocketMine-MP plugins.
https://github.com/jaxkdev/composershader
Last synced: about 1 year ago
JSON representation
Shade/Inject composer dependencies into PocketMine-MP plugins.
- Host: GitHub
- URL: https://github.com/jaxkdev/composershader
- Owner: JaxkDev
- License: osl-3.0
- Created: 2021-04-14T15:39:16.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-05T09:10:28.000Z (almost 5 years ago)
- Last Synced: 2025-03-31T14:21:22.479Z (about 1 year ago)
- Language: PHP
- Size: 139 KB
- Stars: 9
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# ComposerShader
#### README for v0.2.0-dev
---
## Important Note:
This is not perfect, nor will it ever be,
with several checks for common uses of certain functions and namespacing we can attempt to shade these calls,
but a package may do some dynamic requiring/defining and break at runtime.
You can however fork the library/package you want and modify if possible the way it does the dynamic calls so it can be shaded.
## When not to shade:
Shading composer libs should only be done for internal plugin usage only, if you expose an API method f.e `$plugin->getSomething(string $something): Promise{}` this returns a Promise but will reference your shaded library, external plugins will have no guarenteed path for that class unless you always shade to the same place.
In simple it's not a solution for when you expose methods that include shaded usages.
## Why shade ?
As more advanced projects and plugins become readily available through github and poggit the chance of a namespace collision increases exponentially.
For example take the following structure
- plugin A (`JaxkDev\TestPlugin`)
- Promise v1.0 (`React\Promise`)
- plugin B (`AnotherPersons\TestPlugin`)
- Promise v2.0 (`React\Promise`)
Unshaded these plugins would collide, as you can see they both require React\Promise but two different versions.
So not only do they have conflicts in namespace they also differ in behaviour and cannot be shared between them.
And that's where shading comes in, like poggit's virion scheme all the composer dependencies for a plugin gets put into a unique namespace covered by the plugins main class namespace,
In this case plugin A's dependency would be shaded to `JaxkDev\TestPlugin\vendor12345678\React\Promise`
and plugin B's shaded to `AnotherPerson\TestPlugin\vendor87654321\React\Promise`
Now each plugin has its own version of the same library/package so the plugins are using exactly what they expect and behaviour is constant because
as you can see the namespaces no longer collide.
## Requirements
- PHP >= 8.0
- PHP extension yaml
- composer dependencies pre-installed (run `composer install`)
- plugin source code
## Usage & Docs
The script [shade.php](shade.php) should be run via CLI (outside of pmmp) in the directory of the plugin.
Usage: `php shade.php SHADE_PREFIX`
`SHADE_PREFIX` Optional, 4+ chars (a-Z, 0-9)
Examples:
`php shade.php somePrefixHere` shades to `YourPlugin\NameSpace\somePrefixHere\`
#### Usage in the plugin:
By default, it's more than likely shade.php will show:
`Plugin source does not require 'COMPOSER_AUTOLOAD' but XX autoload files have been found.`
This is because your plugin does not call: `require_once(\YourPlugin\NameSpace\COMPOSER_AUTOLOAD);`
If your plugin uses the dependencies on the main thread you should call this in the main class.
eg
*Main.php*
```php
composerPath = $composerPath;
//...
//Dont reference any composer libs here.
}
public function run(){
/** @noinspection PhpUndefinedConstantInspection */
require_once($this->composerPath);
//...
//Composer libs are now available for use/reference from here onwards.
}
}
```
*Main.php*
```php
start(PTHREADS_INHERIT_NONE);
```
`\YourPlugin\NameSpace\COMPOSER_AUTOLOAD` Is the namespace to the plugins main file.
eg *plugin.yml*
```yaml
main: Test\NameSpace\Main
# so here your namespace is \Test\NameSpace\COMPOSER_AUTOLOAD
# if main was: Hello\Another\NameSpace\ButLonger\MainClass
# It would be \Hello\Another\NameSpace\ButLonger\COMPOSER_AUTOLOAD
```