{"id":15688438,"url":"https://github.com/jaxkdev/composershader","last_synced_at":"2025-05-07T21:41:01.180Z","repository":{"id":104028721,"uuid":"357956990","full_name":"JaxkDev/ComposerShader","owner":"JaxkDev","description":"Shade/Inject composer dependencies into PocketMine-MP plugins.","archived":false,"fork":false,"pushed_at":"2021-08-05T09:10:28.000Z","size":142,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T14:21:22.479Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"osl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JaxkDev.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-14T15:39:16.000Z","updated_at":"2023-08-31T14:37:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"c7c0aa23-f9c2-4f12-8eb2-5bfafc1a2679","html_url":"https://github.com/JaxkDev/ComposerShader","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaxkDev%2FComposerShader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaxkDev%2FComposerShader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaxkDev%2FComposerShader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaxkDev%2FComposerShader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JaxkDev","download_url":"https://codeload.github.com/JaxkDev/ComposerShader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252961284,"owners_count":21832183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T18:00:00.689Z","updated_at":"2025-05-07T21:41:01.155Z","avatar_url":"https://github.com/JaxkDev.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ComposerShader\n\n#### README for v0.2.0-dev\n\n---\n\n## Important Note:\nThis is not perfect, nor will it ever be,\nwith several checks for common uses of certain functions and namespacing we can attempt to shade these calls,\nbut a package may do some dynamic requiring/defining and break at runtime.\n\nYou can however fork the library/package you want and modify if possible the way it does the dynamic calls so it can be shaded.\n\n## When not to shade:\nShading composer libs should only be done for internal plugin usage only, if you expose an API method f.e `$plugin-\u003egetSomething(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.\n\nIn simple it's not a solution for when you expose methods that include shaded usages.\n\n## Why shade ?\nAs more advanced projects and plugins become readily available through github and poggit the chance of a namespace collision increases exponentially.\n\nFor example take the following structure\n\n- plugin A (`JaxkDev\\TestPlugin`)\n  - Promise v1.0 (`React\\Promise`)\n\n\n- plugin B (`AnotherPersons\\TestPlugin`)\n  - Promise v2.0 (`React\\Promise`)\n\nUnshaded these plugins would collide, as you can see they both require React\\Promise but two different versions.\nSo not only do they have conflicts in namespace they also differ in behaviour and cannot be shared between them.\n\nAnd 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,\n\nIn this case plugin A's dependency would be shaded to `JaxkDev\\TestPlugin\\vendor12345678\\React\\Promise`\n\nand plugin B's shaded to `AnotherPerson\\TestPlugin\\vendor87654321\\React\\Promise`\n\nNow 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\nas you can see the namespaces no longer collide.\n\n## Requirements\n- PHP \u003e= 8.0\n- PHP extension yaml\n- composer dependencies pre-installed (run `composer install`)\n- plugin source code\n\n## Usage \u0026 Docs\n\nThe script [shade.php](shade.php) should be run via CLI (outside of pmmp) in the directory of the plugin.\n\nUsage: `php shade.php SHADE_PREFIX`\n\n`SHADE_PREFIX` Optional, 4+ chars (a-Z, 0-9)\n\nExamples:\n`php shade.php somePrefixHere` shades to `YourPlugin\\NameSpace\\somePrefixHere\\`\n\n#### Usage in the plugin:\n\nBy default, it's more than likely shade.php will show:\n`Plugin source does not require 'COMPOSER_AUTOLOAD' but XX autoload files have been found.`\n\nThis is because your plugin does not call: `require_once(\\YourPlugin\\NameSpace\\COMPOSER_AUTOLOAD);`\n\nIf your plugin uses the dependencies on the main thread you should call this in the main class.\neg\n\n*Main.php*\n\n```php\n\u003c?php /** @noinspection ALL */\n/*\n * License and notes here if applicable.\n */\n\nnamespace YourPlugin\\NameSpace;\n\n//Your IDE won't see this constant declared. so its ok to ignore the warning.\n/** @noinspection PhpUndefinedConstantInspection */\nrequire_once(\\YourPlugin\\NameSpace\\COMPOSER_AUTOLOAD);\n\nuse React\\Promise;  //Composer libs can be use'd anywhere in your plugin\n                    //see notes below for threading.\n\nclass Main extends PluginBase{\n\n}\n```\n\nIf you are using the composer libraries/packages in another Thread you must call the `require_once(\\YourPlugin\\NameSpace\\COMPOSER_AUTOLOAD);` inside the thread.\n\nNote the constant will only be available if the thread was started with `PTHREADS_INHERIT_CONSTANTS`.\n\nTo reduce possibility of duplicate constant definitions It's suggested to start threads with `PTHREADS_INHERIT_NONE` and\npass the constant/path through the constructor.\n\n*PluginsThread.php*\n```php\n\u003c?php  /** @noinspection ALL */\n\nnamespace YourPlugin\\NameSpace;\n\nclass PluginsThread extends Thread{\n\n    private $composerPath;\n\n    public function __construct(string $composerPath, ...){\n        $this-\u003ecomposerPath = $composerPath;\n        //...\n        //Dont reference any composer libs here.\n    }\n\n    public function run(){\n        /** @noinspection PhpUndefinedConstantInspection */\n        require_once($this-\u003ecomposerPath);\n        //...\n        //Composer libs are now available for use/reference from here onwards.\n    }\n}\n```\n\n*Main.php*\n```php\n\u003c?php /** @noinspection ALL */\n//Somewhere in your Main class where appropriate\n/** @noinspection PhpUndefinedConstantInspection */\n$thread = new PluginsThread(\\YourPlugin\\NameSpace\\COMPOSER_AUTOLOAD);\n$thread-\u003estart(PTHREADS_INHERIT_NONE);\n```\n\n`\\YourPlugin\\NameSpace\\COMPOSER_AUTOLOAD` Is the namespace to the plugins main file.\n\neg *plugin.yml*\n```yaml\nmain: Test\\NameSpace\\Main\n# so here your namespace is \\Test\\NameSpace\\COMPOSER_AUTOLOAD\n\n# if main was: Hello\\Another\\NameSpace\\ButLonger\\MainClass\n# It would be \\Hello\\Another\\NameSpace\\ButLonger\\COMPOSER_AUTOLOAD\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaxkdev%2Fcomposershader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaxkdev%2Fcomposershader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaxkdev%2Fcomposershader/lists"}