README

This php script allows easy using of the Bukkit plugin Votifier

Project

master-branch (alias stable, latest)

develop-branch (alias nightly)

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 the Votifier plugin

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/download/v3.0.0-rc/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 to us.

Versioning

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

Authors

Manuele Vaccari - D3strukt0r - Initial work

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

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE.txt file for details

Acknowledgments

Hat tip to anyone whose code was used
Inspiration
etc

d3strukt0r / votifier-client

Maintainers

Details