README

This php script allows easy using of the Bukkit plugin Votifier

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

The full documentation can be found here.

Prerequisites

What things you need to install the software and how to install them

• PHP Project (PHP 7.1+)
• Minecraft server with a Votifier plugin. NuVotifier is recommended — the classic Votifier plugin relies on javax.xml.bind.DatatypeConverter, which was removed from the JDK in Java 11, so it only runs on Java 8 and therefore only on Minecraft up to 1.16.5 (the last version that runs on Java 8; 1.17+ require Java 16+). On newer servers it fails to enable with NoClassDefFoundError: javax/xml/bind/DatatypeConverter. NuVotifier runs on current Java and is backwards compatible with the classic protocol.

Installing

Add the client using Composer.

composer require d3strukt0r/votifier-client

Usage

Simply create an object with all information

For the servers with the classic Votifier plugins:

<?php

use D3strukt0r\Votifier\Client\Server\Votifier;

$server = (new Votifier())
    ->setHost('127.0.0.1')
    ->setPublicKey('MIIBIjANBgkq...')
;

For the servers which use the NuVotifier plugin (v1 protocol) (HINT: It's NOT the same as method 1):

<?php

use D3strukt0r\Votifier\Client\Server\NuVotifier;

$server = (new NuVotifier())
    ->setHost('127.0.0.1')
    ->setPublicKey('MIIBIjANBgkq...')
;

For the servers which use the NuVotifier plugin with v2 protocol:

<?php

use D3strukt0r\Votifier\Client\Server\NuVotifier;

$server = (new NuVotifier())
    ->setHost('127.0.0.1')
    ->setProtocolV2(true)
    ->setToken('7j302r4n...')
;

Finally, just send it.

<?php

use D3strukt0r\Votifier\Client\Exception\NotVotifierException;
use D3strukt0r\Votifier\Client\Exception\NuVotifierChallengeInvalidException;
use D3strukt0r\Votifier\Client\Exception\NuVotifierException;
use D3strukt0r\Votifier\Client\Exception\NuVotifierSignatureInvalidException;
use D3strukt0r\Votifier\Client\Exception\NuVotifierUnknownServiceException;
use D3strukt0r\Votifier\Client\Exception\NuVotifierUsernameTooLongException;
use D3strukt0r\Votifier\Client\Exception\Socket\NoConnectionException;
use D3strukt0r\Votifier\Client\Exception\Socket\PackageNotReceivedException;
use D3strukt0r\Votifier\Client\Exception\Socket\PackageNotSentException;
use D3strukt0r\Votifier\Client\Server\ServerInterface;
use D3strukt0r\Votifier\Client\Vote\ClassicVote;

$vote = (new ClassicVote())
    ->setUsername($_GET['username'])
    ->setServiceName('Your vote list')
    ->setAddress($_SERVER['REMOTE_ADDR'])
;

try {
    /** @var ServerInterface $server */
    $server->sendVote($vote);
    // Connection created, and vote sent. Doesn't mean the server handled it correctly, but the client did.
} catch (InvalidArgumentException $e) {
    // Not all variables that are needed have been set. See $e->getMessage() for all errors.
} catch (NoConnectionException $e) {
    // Could not create a connection (socket) to the specified server
} catch (PackageNotReceivedException $e) {
    // If the package couldn't be received, for whatever reason.
} catch (PackageNotSentException $e) {
    // If the package couldn't be send, for whatever reason.
} catch (NotVotifierException $e) {
    // The server didn't give a standard Votifier response
} catch (NuVotifierChallengeInvalidException $e) {
    // Specific for NuVotifier: The challenge was invalid (Shouldn't happen by default, but it's here in case).
} catch (NuVotifierSignatureInvalidException $e) {
    // Specific for NuVotifier: The signature was invalid (Shouldn't happen by default, but it's here in case).
} catch (NuVotifierUnknownServiceException $e) {
    // Specific for NuVotifier: A token can be specific for a list, so if the list isn't supposed to use the given token, this message appears.
} catch (NuVotifierUsernameTooLongException $e) {
    // Specific for NuVotifier: A username cannot be over 16 characters (Why? Don't ask me)
} catch (NuVotifierException $e) {
    // In case there is a new error message that wasn't added to the library, this will take care of that.
}

Running the tests

Explain how to run the automated tests for this system

Break down into end-to-end tests

Run test scripts

./vendor/bin/phpunit

Coding style tests and fixes

To check if the code follows the PSR-12 standard, the library PHP_CodeSniffer has been add to the development environment, but you can also download it separately from here and here.

To see what mistakes exist in the code run:

./vendor/bin/phpcs

To fix the code:

./vendor/bin/phpcbf

This library already comes with php-cs-fixer but because it's impossible to set it up to follow the PSR-12 standard, it's not a requirement anymore. It's been left in the project only for additional styling information that might be applied. It can also be downloaded separately from here.

./vendor/bin/php-cs-fixer fix --diff --dry-run -v

Code documentation

Install Python v3 from here.

Install Sphinx as documented here.

pip install -U sphinx

To build the docs:

cd docs
pip install -r requirements.txt
make html

Old Code documentation

You can also create a documentation with phpDocumentor. For that please downloaded at least v3+ for to work from here. And then you can just run it

curl -fsSL -o /usr/local/bin/phpdoc https://github.com/phpDocumentor/phpDocumentor/releases/latest/download/phpDocumentor.phar
phpdoc

Built With

• PHP - Programming Language
• Composer - Dependency Management
• PHPUnit - Testing the code
• Github Actions - Automatic CI (Testing)
• Read the docs - Documentation

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

This project uses Conventional Commits.

Versioning

We use SemVer for versioning. For available versions, see the tags on this repository.

Authors

Special thanks for all the people who had helped this project so far

• Manuele - D3strukt0r

See also the full list of contributors who participated in this project.

I would like to join this list. How can I help the project?

We're currently looking for contributions for the following:

• Bug fixes
• Translations
• etc...

For more information, please refer to our CONTRIBUTING.md guide.

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Acknowledgments

• Hat tip to anyone whose code was used
• Inspiration
• etc