Tutorial Updating a Plugin to Work with Different APIs (The Manual Way)

Discussion in 'Resources' started by FiberglassCivic, Aug 27, 2017.

  1. FiberglassCivic

    FiberglassCivic Spider Jockey

    Messages:
    39
    GitHub:
    95civicsi
    Updating a plugin to be compatible with a new API can be as easy as changing/adding the version number in the plugin.yml file or as complicated as having to rewrite major sections of the plugin code (possibly all of it). So far, most of the plugins that I have updated to work with 3.0.0-ALPHA7 have needed some small changes, but nothing major. There are some tools available that can automate parts of this process but it's not likely to find one which can completely fix all compatibility problems with every bit of code.

    Requirements
    There are some things that you need and things to be familiar with before attempting these instructions. Otherwise, you may find this very difficult.

    • How to access your PMMP server's console
    • How to move files between your computer and your PMMP server
    • How to get plugin source code from GitHub (or other locations)
    • Some exposure to PHP programming (or some other Object Oriented program language)
    • A copy of the DevTools plugin (source found here)
    • A good text editor (I use Notepad++)


    Getting Started
    Prepare your server environment for testing. If your server is constantly populated with other players, then it may be best to setup a test environment that only you have access to as this process will cause the server to stop and start several times.

    You will need to know the API version number for the server software you are using. At the time of writing, the master branch was at 3.0.0-ALPHA7. You can find this by starting your server or using the /version command if your server is already running.

    vInfo.PNG

    Note: The larger the gap is between the API version of your plugin and the API version of your server software, the more likely it is that this process will be more difficult.

    Once you have the version information for your server software, you need to install the appropriate version of DevTools from the source above. This will save a lot of time while you are debugging. (Thanks for this info Thunder33345)

    Next you will need a copy of the contents of the plugin's phar file. You can typically get this by downloading the source from GitHub. This needs to be on your local machine so that you can edit the files. I will be updating SimpleHG by Kaleb Wasmuth (source code is here).

    First Plugin Changes
    To make an outdated plugin load with your current API, you will need to change a line in plugin.yml that says api. This does not guarantee that the plugin will work. For example, to get a plugin to load with API 3.0.0-ALPHA7 your api line would need to look like this:

    Code:
    api: [3.0.0-ALPHA7]
    For SimpleHG, this is found on line 21
    SimpleHG_API_old.PNG

    The updated version looks like this:
    SimpleHG_API_updated.PNG


    Start/Restart the Server
    At this point we are ready to see what happens when the plugin loads. Start/Restart your server and watch the console output to see if the plugin actually loads.

    PluginLoadConsole.PNG

    Notice that my DevTools plugin has the "Incompatible API version" error but SimpleHG does not.

    Handling Errors
    Next you need to watch for any errors caused by the plugin. With SimpleHG an error was immediately generated after loading the plugin.

    PluginLoadError.PNG

    This is where things can get tricky but don't let this overwhelm you. Many times, the error you receive will actually tell you what's wrong instead of leaving you out to dry. Here we are told that there is a problem with something in the Main.php file. We can see this at the end of the Fatal error message.
    Code:
    in phar:///etc/pmmp/plugins/SimpleHG.phar/src/SimpleHG/Main.php on line 58
    
    Each error message will be a bit different and you will need to decipher each problem independently. When you have a "crash" like this, a log file is generated in a folder called crashdumps. You can look at this log to get a clearer understanding of the error.

    ErrorLog.PNG

    If we look more closely at the error message on line 3, it tells us that:

    Code:
    Declaration of SimpleHG\Main::onCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, $label, array $args) must be compatible with pocketmine\command\CommandExecutor::onCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool
    This is where being familiar with php and/or other object oriented languages will be useful. With this specific error, the problem is that the plugin is trying to do something with a function that is defined in the PMMP source, specifically the 'onCommand' function. If we search through Main.php of the SimpleHG plugin, we find that on line 640, there is a declaration of the onCommand function. Let's look at our error message again, specifically the second half.

    Code:
    must be compatible with pocketmine\command\CommandExecutor::onCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool
    The error is telling us that something with how this function is written, is not compatible with the function in the PMMP source and that the declaration of this function should look like this:

    Code:
    public function onCommand(CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool
    But the one in Main.php looks like this:

    Code:
    public function onCommand(CommandSender $sender, Command $command, $label, array $args)
    Careful comparison shows that we are missing the word 'string' before '$label' and ': bool' after the closing parenthesis. If we change our code to match it should look like this:

    SimpleHG_Main_Updated.PNG

    Once you make changes to fix an error, you need to:
    • Upload your plugin changes
    • Start/Restart the server
    • Look for more errors
    After restarting the server, with SimpleHG you will get something like this:
    SimpleHG_Enabled.PNG

    Notice that SimpleHG was enabled and that the server is still running. At this point, you should be able to connect to your server from the game.

    We're done...... Right?
    Unfortunately, no. If you haven't gained an appreciation for plugin developers by this point, then the next part should help you with that. Now you get to do it all over again with each of the plugin's functions. This means that you have to try using all of the plugins features and see if anything is broken or causes the server to crash.

    This process can be long and tedious or short and sweet depending on the plugin. With SimpleHG this will require that you setup an area for the match, update the config.yml file, and try playing several games with all the different options enabled/disabled.

    Hint: SimpleHG still has a problem.

    As you find each error, you will need to take similar steps to resolving them. In some cases, you may find that entire sections of code need to be rewritten. Don't be discouraged though. This process gets easier each time you go through it.

    Create the Plugin.phar file
    To do this, you will need the DevTools plugin installed on your server. This information can be found in the DevTools ReadMe but has been included here for ease of access.

    The Easy Way
    While your server is started, run the /makeplugin command. For example, to build the SimpleHG plugin you would use this:

    Code:
    /makeplugin SimpleHG
    When DevTools is finished, the phar file will be in the plugins/DevTools folder

    The Hard Way
    If you have not installed the DevTools plugin, or you don't want to make your plugin from inside the server, the other way is to use the ConsoleScript.php file from the DevTools source code. It can be found in the src/DevTools folder. Upload this file to your server then change the file paths in the following command and execute it outside of the PMMP software:

    Code:
    php -dphar.readonly=0 path/to/ConsoleScript.php --make path/to/your/plugin/sourcecode --out path/to/put/your/plugin.phar


    For example, my test server has the PMMP server in /etc/pmmp and I have a copy of the ConsoleScript.php file at /etc/pmmp/plugins/DevTools.​

    Code:
    php -dphar.readonly=0 /etc/pmmp/plugins/DevTools/ConsoleScript.php --make /etc/pmmp/plugins/SimpleHG --out /etc/pmmp/plugins/SimpleHG.phar
    Note: If you are having trouble with this, check the README for DevTools.
     
    Last edited: Aug 27, 2017
  2. Thunder33345

    Thunder33345 Moderator Staff Member Verified

    Messages:
    2,156
    GitHub:
    Thunder33345
    if you have a working dev tools there's no need to turn it into phar dev tools will load the folder with no problem thus saving some time doing unnecessary work
     
  3. Sandertv

    Sandertv Skeleton Poggit Reviewer

    Messages:
    802
    GitHub:
    Sandertv
    Wow, you really put some amazing effort in this thread. Bravo. You've made a great tutorial on this, finally someone who explains that updating a plugin is not just changing an Api number and boom, done. Honestly, Very well done on this. Good job.
     
  4. FiberglassCivic

    FiberglassCivic Spider Jockey

    Messages:
    39
    GitHub:
    95civicsi
    I was not aware of that feature in DevTools. I will definitely add that info shortly.
     
  5. Megalunchbox

    Megalunchbox Spider

    Messages:
    7
    Thanks for this, i don't really know how to code using someone else's api but this made it very easy to understand. Will most of it just be fixing functions in the plugins?
     
  6. FiberglassCivic

    FiberglassCivic Spider Jockey

    Messages:
    39
    GitHub:
    95civicsi
    There is no straight answer to your question. Each plugin will need to be evaluated on an individual basis and there are several factors that will affect what will be necessary to complete the process.

    The first factor to consider is how much of a gap there is between the API version the plugin was written for and the API version of your server. If this is a significant difference (eg. Plugin API is v1.0.0 and server API version is 3.0.0-ALPHA5) you may be better off just writing the plugin from scratch or looking for another plugin that performs similar function.

    The next factor is how large the plugin is. The more code there is in a plugin, the more likely you are to have problems. Extensive plugins may also make use of more features from the API which is more potential for problems.

    While there are some other things that can affect what changes will be necessary, those two factors are (IMHO) the two largest. If you hit a snag, you can always ask in the plugin development forums for help. If you do, make sure to post what you have already tried and the code you are having problems with.
     
    BluetigerESW, Sandertv and SOFe like this.
  7. Megalunchbox

    Megalunchbox Spider

    Messages:
    7
    I don't understand why isn't this working..

    Declaration of ServerAuth\Commands\Commands::eek:nCommand($sender, $command, string $label, array $args): bool must be compatible with pocketmine\command\CommandExecutor::eek:nCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool
    File: ServerAuth_v2.13.phar/src/ServerAuth/Commands/Commands
    Line: 24
    Type: E_COMPILE_ERROR

    I did replace the code exactly as it said, but it does not work and I'm confused, i tried copy and pasting the exactly as it said as well and it didnt work.

    [15] use pocketmine\command\CommandExecutor;
    [16] use pocketmine\command\CommandSender;
    [17] use pocketmine\Player;
    [18] use pocketmine\Server;
    [19] use pocketmine\plugin\PluginBase;
    [20]
    [21] use ServerAuth\ServerAuth;
    [22] use ServerAuth\Tasks\MySQLTask;
    [23]
    [24] class Commands extends PluginBase implements CommandExecutor {
    [25]
    [26] public function __construct(ServerAuth $plugin){
    [27] $this->plugin = $plugin;
    [28] }
    [29]
    [30] public function onCommand($sender, $command, string $label, array $args): bool {
    [31] $fcmd = strtolower($cmd->getName());
    [32] switch($fcmd){
    [33] case "serverauth":
    [34] if(isset($args[0])){
     
  8. Thunder33345

    Thunder33345 Moderator Staff Member Verified

    Messages:
    2,156
    GitHub:
    Thunder33345
    try to re read the error, this time read every single phrase,
    $sender, $command, string $label, array $args
    is not compatible with
    pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args
     
  9. Megalunchbox

    Megalunchbox Spider

    Messages:
    7

    I did that as well, it didn't work. I said that when i posted my problems. The problem is that the return type changes and I am used to java so i didnt know what that was and ignored it lol.
     
    Last edited: Aug 28, 2017
  10. dktapps

    dktapps Administrator Staff Member PMMP Team

    Messages:
    730
    GitHub:
    dktapps
    If you have a good IDE like PhpStorm, you can also create a project from the plugin files, add the server source as a Source content root, and then run a code inspection on the plugin source. That'll tell you exactly what's broken and where for method signature changes.
     
  11. RousselCrft

    RousselCrft Spider

    Messages:
    10
    Lmao! I have Android device and for update the API version i use this aplications from Play Store:

    - AIDE Web (For edit Code)
    -Phar (For compile phar)

    For extract phar i use a devtools plugin.
    Too search diferent phar versions of pocketmine with diferent API
    Example: 3.0.0-ALPHA4 or 3.0.0-ALPHA5 etc etc for extract the phar.
    It work fine for me.
     
  12. HimbeersaftLP

    HimbeersaftLP Chicken

    Messages:
    1,526
    GitHub:
    HimbeersaftLP
    No, that's just a really outdated plugin
     
  13. hexmor

    hexmor Baby Zombie

    Messages:
    137
    I have 100 plugins
    how can i update all of them ?
    there isn't any automatic updator ? (sry for bad english )
     
  14. QuiverlyRivalry

    QuiverlyRivalry Zombie Pigman

    Messages:
    488
    GitHub:
    quiverlyrivalry
    There is 1 way, but I gurantee I am gonna get hate for saying it :p and you shouldnt really use it. Its good to learn the manual way. I was like you when I came, I aksed the same thing xD. But now I learnt and could update an API as my life depended on it xD
     
  15. hexmor

    hexmor Baby Zombie

    Messages:
    137
    I need a auto api plugin updator help meeee
     
  16. Thunder33345

    Thunder33345 Moderator Staff Member Verified

    Messages:
    2,156
    GitHub:
    Thunder33345
    you cant, you just cant
    there's so many changes that you need to make for it to work
    also please stop going offtopic
     
    FiberglassCivic likes this.
  17. QuiverlyRivalry

    QuiverlyRivalry Zombie Pigman

    Messages:
    488
    GitHub:
    quiverlyrivalry
    Wouldn't recommend this... But if your plugin is small and has less features just use DevTools
     
    Last edited by a moderator: Nov 11, 2017

Share This Page

  1. This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
    By continuing to use this site, you are consenting to our use of cookies.