Biblioteka PHP do obsługi LVL UP API v4

Jebanany | 2020-08-07 13:37:21 UTC | #1

lvlup-php-sdk

Chciałbym Wam przestawić moją bibliotekę PHP służącą do obsługi API v4 https://api.lvlup.pro/v4 oraz https://api.sandbox.lvlup.pro/v4

Więcej o API v4 przeczytacie w tym wątku

https://forum.lvlup.pro/t/panel-klienta-lvlup-pro-api-v4/14111

Github

https://github.com/Jebanany/lvlup-sdk-php

Wymagania

PHP 7+
curl (opcjonalnie)

Instalacja

Aby zainstalować bibliotekę należy użyć Composera:

composer require jebanany/lvlup

Użycie

Pierwsze kroki

use Jebanany\Lvlup\ApiClient;
require_once('vendor/autoload.php');

// Normalne używanie
$lvlup = new ApiClient('apikey');
// bez używania cURL
$lvlup = new ApiClient('apikey', false, false);

// Sandbox
$lvlup = new ApiClient('sandboxapikey', true);
// bez używania cURL
$lvlup = new ApiClient('sandboxapikey', true, false);

Przykłady

1. Korzystanie z Sandboxa
Generowanie nowego konta w Sandboxie, tworzenie płatności, sprawdzenie statusu, zmiana statusu, ponowne sprawdzenie statusu.

use Jebanany\Lvlup\ApiClient;

require_once('vendor/autoload.php');

try {
    // Pobieramy nowe dane do konta sandbox
    // zachowaj te dane do swoich następnych testów; nie generuj ich za każdym razem!
    $lvlupSandbox = new ApiClient(false, true);
    $sanboxUser = $lvlupSandbox->sandboxAccountCreate();

    echo "<pre>";
    echo "Dane dostępowe";
    echo "\n ID: " . $sanboxUser->id;
    echo "\n Username: " . $sanboxUser->username;
    echo "\n Password: " . $sanboxUser->password;
    echo "\n Email: " . $sanboxUser->email;
    echo "\n APIkey: " . $sanboxUser->apiKey;
    // zachowaj te dane do swoich następnych testów; nie generuj ich za każdym razem!

    // Mając dane konta sandbox tworzymy nową instancję, tym razem z APIkey
    $lvlupSandbox = new ApiClient($sanboxUser->apiKey, true);

    // Generujemy nową płatność
    $payment = $lvlupSandbox->paymentsCreate(25.00);

    echo "\nDane o wygenerowanej płatności";
    echo "\n url: " . $payment->url;
    echo "\n id: " . $payment->id;

    // Sprawdzamy status płatności
    $status = $lvlupSandbox->paymentsStatus($payment->id);

    echo "\nStatus płatności przed opłaceniem";
    echo "\n payed: " . ($status->payed ? 'true' : 'false'); // false
    echo "\n amountStr: " . $status->amountStr;
    echo "\n amountInt: " . $status->amountInt;
    echo "\n amountWithFeeStr: " . $status->amountWithFeeStr;
    echo "\n amountWithFeeInt: " . $status->amountWithFeeInt;

    // Zmieniamy status płatności - opłacamy / ustawiamy jako opłacone
    $lvlupSandbox->sandboxPaymentAccept($payment->id);

    // Sprawdzamy status płatności ponownie
    $status = $lvlupSandbox->paymentsStatus($payment->id);
    echo "\nStatus płatności po opłaceniu";
    echo "\n payed: " . ($status->payed ? 'true' : 'false'); // true
    echo "\n amountStr: " . $status->amountStr;
    echo "\n amountInt: " . $status->amountInt;
    echo "\n amountWithFeeStr: " . $status->amountWithFeeStr;
    echo "\n amountWithFeeInt: " . $status->amountWithFeeInt;
    echo "</pre>";

} catch (Exception $e) {
    echo 'Kod błędu: <b>' . $e->getCode() . '</b> treść błędu: <b>' . $e->getMessage() . '</b>';
} catch (TypeError $e) {
    echo 'Kod błędu: <b>' . $e->getCode() . '</b> <br>treść błędu: <b>' . $e->getMessage() . '</b>';
}

2. Używanie bloków catch i try
W przypadku niepowodzenia zostaną wygenerowane Exception (błędy różne) lub TypeError (tj. inne niż wymagane rodzaje parametry metody np. string zamiast int).

W przypadku błędów Exception dostępna jest pomocnicza wiadomość getMessage() i kod odpowiedzi HTTP getCode() - jeśli zapytanie w ogóle wystąpiło, jeśli nie, getCode() zwróci 0.

use Jebanany\Lvlup\ApiClient;

require_once('vendor/autoload.php');

try {
    // Bez APIkey
    $lvlup = new ApiClient(false);
    $sanboxUser = $lvlup->userMe(); // generuje Exception

} catch (Exception $e) {
    echo 'Kod błędu: <b>' . $e->getCode() . '</b> treść błędu: <b>' . $e->getMessage() . '</b>';
   // 
   // Kod błędu: 401 treść błędu: Unauthorized Error (Probably invalid API key)
   // 
} catch (TypeError $e) {
    echo 'Kod błędu: <b>' . $e->getCode() . '</b> <br>treść błędu: <b>' . $e->getMessage() . '</b>';
}

Dostępne metody

grafanaPing()
grafanaRawQuery(array $rawDataQuery)
grafanaTimeseriesList()
grafanaTablesList()
ordersList(int $limit = null, int $afterId = null, int $beforeId = null)
partnerIpInfo(int $id)
paymentsBalance()
paymentsCreate(int $amount, string $redirectUrl = '', string $webhookUrl = '')
paymentsList(int $limit = null, int $afterId = null, int $beforeId = null)
paymentsStatus($paymentId)
reportPerformanceCreate($description = '')
sandboxAccountCreate()
sandboxPaymentAccept($paymentId)
servicesAttacksList(int $vpsIds, int $limit = null, int $afterId = null, int $beforeId = null)
servicesList()
servicesProxmoxGenerateCredentials(int $vpsId)
servicesUdpFilterStatus(int $vpsId)
servicesUdpFilterStatusSet(int $vpsId, bool $changeTo)
servicesUdpFilterWhitelist(int $vpsId)
servicesUdpFilterWhitelistRuleAdd(int $vpsId, int $portFrom, int $portTo, string $protocol)
servicesUdpFilterWhitelistRuleDel(int $vpsId, int $ruleId)
servicesVpsStart(int $vpsId)
servicesVpsState(int $vpsId)
servicesVpsStop(int $vpsId)
userMe()
userLogList(int $limit = null, int $afterId = null, int $beforeId = null)
userReferralCreate()
userReferralList()

Opis metod z ich wykorzystaniem

[details=”Rozwiń opisy metod”]
Grafana
* grafanaPing()
Zwraca “OK”, jeśli Grafana odpowiada
* grafanaRawQuery(array $rawDataQuery)
Metryki kompatybilne z Grafana

grafanaTimeseriesList()
Dostępne serie czasowe
grafanaTablesList()
Dostępne tabele

Orders

ordersList
Lista zamówień z paginacją

// ordersList(int $limit =null, int $afterId = null, int $beforeId = null)
// return object
$lvlup->orderList(); //return object

Partner

partnerIpInfo

// partnerIpInfo($ip)
// return object
$lvlup->partnerIpInfo('203.0.113.24');

Payments

paymentsBalance
Saldo portfela

// paymentsBalance()
// return object
$lvlup->partnerIpInfo(); //object

paymentsCreate
Wygenerowanie nowej płatności

// paymentsCreate(int $amount, string $redirectUrl = '', string $webhookUrl = '')
// return object
$lvlup->paymentsCreate(1.50); 
$lvlup->paymentsCreate('1.50'); // string jako kwota również działa
$lvlup->paymentsCreate(17, 'http://example.com/redirect', 'http://example.com/webhook');

paymentsList
Lista przyjętych płatności

// paymentsList(int $limit = null, int $afterId = null, int $beforeId = null)
// return object
$lvlup->paymentsList(); 
$lvlup->paymentsList(50, 5); 
$lvlup->paymentsList(50, null, 5);

paymentsStatus
Status istniejącej płatności

// paymentsStatus($paymentId)
// return object
$lvlup->paymentsStatus('paymentId');

Report
* reportPerformanceCreate
Wysłanie raportu o nieprawidłowym działaniu usługi

// reportPerformanceCreate($description = '')
// return NULL
$lvlup->reportPerformanceCreate('Problems with MC server. TPS: 9/20'); 
$lvlup->reportPerformanceCreate('TS packetloss: 24%');

Sandbox
* sandboxAccountCreate
Utworzenie nowego konta sandbox

// sandboxAccountCreate()
// return object
$lvlup->sandboxAccountCreate();

sandboxPaymentAccept
Zmiana statusu płatności na opłacone

// sandboxPaymentAccept($paymentId)
// return NULL
$lvlup->sandboxPaymentAccept('paymentId');

Services
* servicesAttacksList
Lista ataków

// servicesAttacksList(int $vpsIds, int $limit = null, int $afterId = null, int $beforeId = null)
// return object
$lvlup->servicesAttacksList(123); 
$lvlup->servicesAttacksList(123, 50); 
// etc

servicesList
Lista usług

// servicesList()
// return object
$lvlup->servicesList();

servicesProxmoxGenerateCredentials
Generowanie danych dostępowych do panelu Proxmox

// servicesProxmoxGenerateCredentials($vpsId)
// return object
$lvlup->servicesProxmoxGenerateCredentials(123);

servicesUdpFilterStatus
Aktualny status filtrowania UDP

// servicesUdpFilterStatus($vpsId)
// return object
$lvlup->servicesUdpFilterStatus(123);

servicesUdpFilterStatusSet
Ustawienie aktualnego statusu filtrowania UDP

// servicesUdpFilterStatusSet(int $vpsId, bool $changeTo)
// return object
$lvlup->servicesUdpFilterStatusSet(123, true); //true - on; false - off

servicesUdpFilterWhitelist
Wyjątki filtrowania UDP

// servicesUdpFilterWhitelist(int $vpsId)
// return object
$lvlup->servicesUdpFilterWhitelist(123);

servicesUdpFilterWhitelistRuleAdd
Nowy wyjątek filtrowania UDP

// servicesUdpFilterWhitelistRuleAdd(int $vpsId, int $portFrom, int $portTo, string $protocol)
// $allowedProtocols = ['arkSurvivalEvolved', 'arma', 'gtaMultiTheftAutoSanAndreas', 'gtaSanAndreasMultiplayerMod', 'hl2Source', 'minecraftPocketEdition', 'minecraftQuery', 'mumble', 'rust', 'teamspeak2', 'teamspeak3', 'trackmaniaShootmania', 'other'];
// return object
$lvlup->servicesUdpFilterWhitelistRuleAdd(123, 9987, 9987, 'teamspeak3');
$lvlup->servicesUdpFilterWhitelistRuleAdd(123, 9526, 10465, 'other');

servicesUdpFilterWhitelistRuleDel
Usunięcie wyjątku filtrowania UDP

// servicesUdpFilterWhitelistRuleDel(int $vpsId, int $ruleId)
// return object
$lvlup->servicesUdpFilterWhitelist(123, 456);

servicesVpsStart
Wystartuj VPS

// servicesVpsStart(int $vpsId)
// return object
$lvlup->servicesVpsStart(123);

servicesVpsState
Aktualny status VPS

// servicesVpsState(int $vpsId)
// return object
$lvlup->servicesVpsState(123);

servicesVpsStop
Zatrzymaj VPS

// servicesVpsStop(int $vpsId)
// return object
$lvlup->servicesVpsStop(123);

User
* userMe
Informacja o aktualnym użytkowniku APIkey

// userMe()
// return object
$lvlup->userMe();

userLogList

// userLogList(int $limit = null, int $afterId = null, int $beforeId = null)
// return object
$lvlup->userLogList();
$lvlup->userLogList(50);
// etc

userReferralCreate
Wygenerowanie nowego kodu polecającego

// userReferralCreate()
// return object
$lvlup->userReferralCreate();

userReferralList
Lista kodów polecających

// userReferralList()
// return object
$lvlup->userReferralList();

[/details]

To wszystko!

Zapraszam gorąco do dyskusji, propozycji, zgłaszania błędów w tym wątku.
(Zakładka issues na Github’ie jest obecnie wyłączona).

Nieznajomy11 | 2020-04-24 04:46:29 UTC | #2

[quote=”Jebanany, post:1, topic:14461”]
use jebanany\lvlup\ApiClient;
[/quote]

Taki namespace, to chyba niezgodne z PSR. :facewithmonocle:

MTGmati | 2020-04-24 18:38:32 UTC | #3

reportPerformanceCreate($description = '')

This endpoint doesn't need auth but must be called from IP which belongs to VPS in lvlup.pro

Warto dodać że tą funkcję wykonujemy na VPS gdzie występują problemy.

SystemZ | 2020-04-24 14:45:21 UTC | #4

[quote=”Nieznajomy11, post:2, topic:14461”]
Taki namespace, to chyba niezgodne z PSR.
[/quote]

Jak powinno to wyglądać?
W sumie podyskutowałbym ale już trochę nie siedzę w tym ekosystemie PHP

riko.dev | 2020-04-24 15:55:29 UTC | #5

[quote=”SystemZ, post:4, topic:14461”]
Jak powinno to wyglądać?
[/quote]

Pierwsza litera każdego słowa oddzielonego backslash’em powinna zaczynać się wielką literą. :slight_smile:

use Jebanany\Lvlup\ApiClient;

https://www.php-fig.org/psr/psr-12/#21-basic-coding-standard

Jebanany | 2020-04-24 19:26:21 UTC | #6

[quote=”Nieznajomy11, post:2, topic:14461”]
Taki namespace, to chyba niezgodne z PSR. :facewithmonocle:
[/quote]

[quote=”riko.dev, post:5, topic:14461”]

use Jebanany\Lvlup\ApiClient;

[/quote]
Słusznie, w następnym commicie zostaną zawarte te zmiany. Dzięki!

[quote=”MTGmati, post:3, topic:14461, full:true”]

reportPerformanceCreate($description = '')

This endpoint doesn't need auth but must be called from IP which belongs to VPS in lvlup.pro

Warto dodać że tą funkcję wykonujemy na VPS gdzie występują problemy.
[/quote]

Bardzo cenna uwaga. Wydaje mi się, żeby tę kwestię pozostawić użytkownikowi biblioteki, zakładając, że korzysta z niej również z użyciem dokumentacji API. Dodam tę informację gdzieś w README.md, ale warto pamiętać, że to biblioteka do konkretnego API z dokumentacją.

Jebanany | 2020-04-24 20:54:11 UTC | #7

Namespace został poprawiony zgodnie z dobrymi praktykami w v1.0.1.

Jebanany | 2020-04-29 21:17:38 UTC | #8

Fix w metodzie paymentsCreate (zaokrąglanie kwoty) v1.0.2. Dzięki @riko.dev

Jebanany | 2020-04-30 03:30:26 UTC | #9

Fix w metodzie servicesUdpFilterWhitelistRuleAdd w v1.0.3

Jebanany | 2020-05-10 21:26:25 UTC | #10

Po drodze zmiany w README.md - dzięki @riko.dev.

Fix w metodzie partnerIpInfo w v1.0.4

Jebanany | 2020-08-07 13:46:27 UTC | #11

Update dotyczący zmiany linku api-sandbox (dzięki @riko.dev) w v1.0.5.

:warning: Warto zaktualizować - bez tego nie będzie działać sandbox

Grabi | 2020-10-27 19:34:09 UTC | #12

Pomocne :)

Jebanany | 2021-04-25 19:34:13 UTC | #13

Ten temat został automatycznie zamknięty 180 dni po ostatnim wpisie. Tworzenie nowych odpowiedzi nie jest już możliwe.