├── .gitattributes ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── composer.json ├── composer.lock ├── docker-compose.cli.yml ├── docker-compose.yml ├── docker └── Dockerfile ├── infection.json.dist └── src ├── Exception ├── AccessDeniedException.php ├── FunctionNotFoundException.php ├── MessageException.php ├── NotCallableResourceException.php └── NotFoundStatusException.php ├── Factory └── ElementFactory.php ├── Model ├── Authentication.php ├── Element.php ├── Resource.php ├── ResourceCall.php ├── Resources.php └── Server.php ├── Mta.php ├── Response └── HttpStatusValidator.php ├── Service └── MtaService.php ├── Transformer └── ElementTransformer.php └── Util └── Input.php /.gitattributes: -------------------------------------------------------------------------------- 1 | /examples export-ignore 2 | /tests export-ignore 3 | /.php_cs.dist export-ignore 4 | /phpstan.neon.dist export-ignore 5 | /phpunit.xml.dist export-ignore 6 | /.github export-ignore 7 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | vendor/ 3 | .php_cs.cache 4 | infection.log 5 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | All notable changes to this project will be documented in this file. 3 | 4 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 5 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 6 | 7 | ## [Unreleased] 8 | 9 | ## [1.1.0] - 2021-03-06 10 | ### Added 11 | - Support for PHP 8 12 | ### Changed 13 | - Updated dependencies 14 | 15 | ## [1.0.6] - 2020-11-20 16 | ### Changed 17 | - Updated dependencies 18 | 19 | ## [1.0.5] - 2020-09-25 20 | ### Fixed 21 | - Throw exception instead of getting a php warning when calling to non-running resource (Thanks to [@Daemant](https://github.com/Daemant) in [PR #42](https://github.com/multitheftauto/mtasa-php-sdk/pull/42)) 22 | 23 | ## [1.0.4] - 2020-07-25 24 | ### Changed 25 | - Use array unpackaging instead of using `call_user_func_array` in ResourceCall class 26 | - Updated dependencies 27 | 28 | ## [1.0.3] - 2020-03-14 29 | ### Fixed 30 | - Fix JSON extension compatibility with PHP 7.4 31 | 32 | ## [1.0.2] - 2019-10-07 33 | ### Fixed 34 | - Remove wrong scalar type declaration at resource call method (Thanks to [@MegaThorx](https://github.com/MegaThorx) in [PR #6](https://github.com/multitheftauto/mtasa-php-sdk/pull/6)) 35 | 36 | ## [1.0.1] - 2019-10-03 37 | ### Added 38 | - Add custom exceptions for server code errors 39 | 40 | ### Fixed 41 | - Return null if data from server is empty when calling to a server function 42 | 43 | ## [1.0.0] - 2019-09-05 44 | ### Added 45 | - Full rework of the SDK 46 | - Add server model for IP and port 47 | - Add authentication model for user and password 48 | - Add possibility of choosing the http client, request and stream factory 49 | - Add `call` property in `Resource` class to call functions 50 | 51 | ### Changed 52 | - Uppercase first character of mta class 53 | - Change parameter types of Mta class 54 | 55 | ## [0.4.0] - 2009-10-06 56 | ### Changed 57 | - Renamed `public function mta(..)` to `public function __construct(..)`. 58 | 59 | ## [0.3.0] - 2008-04-17 60 | ### Added 61 | - Neater syntax, support functions for callRemote (fix version makes call work with args) 62 | 63 | ## [0.2.0] - 2007-07-10 64 | ### Added 65 | - Add authentication support 66 | 67 | ## [0.1.0] - 2007-06-26 68 | ### Added 69 | - Initial release 70 | 71 | [Unreleased]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.1.0...HEAD 72 | [1.1.0]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.6...v.1.1.0 73 | [1.0.6]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.5...v.1.0.6 74 | [1.0.5]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.4...v.1.0.5 75 | [1.0.4]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.3...v1.0.4 76 | [1.0.3]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.2...v1.0.3 77 | [1.0.2]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.1...v1.0.2 78 | [1.0.1]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v1.0.0...v1.0.1 79 | [1.0.0]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v0.4.0...v1.0.0 80 | [0.4.0]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v0.3.0...v0.4.0 81 | [0.3.0]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v0.2.0...v0.3.0 82 | [0.2.0]: https://github.com/multitheftauto/mtasa-php-sdk/compare/v0.1.0...v0.2.0 83 | [0.1.0]: https://github.com/multitheftauto/mtasa-php-sdk/releases/tag/v0.1.0 84 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Multi Theft Auto 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # MTA:SA PHP SDK 2 | ![PHP Composer](https://github.com/multitheftauto/mtasa-php-sdk/workflows/PHP%20Composer/badge.svg?branch=master) 3 | 4 | You can access the MTA Web Interface from almost any programming language that can request web pages. PHP can do this very easily. 5 | 6 | This SDK provides one function call that will allow you to call any exported script functions on any server that you have access to. 7 | 8 | See the [official wiki page](https://wiki.multitheftauto.com/wiki/PHP_SDK) for further information. 9 | 10 | ## Installation 11 | 12 | ### Prerequisites 13 | 14 | This SDK requires PHP 7.4 or greater. 15 | 16 | ### HTTPlug client abstraction 17 | 18 | As this SDK uses HTTPlug, you will have to require some libraries for get it working. See ["HTTPlug for library users"](http://docs.php-http.org/en/latest/httplug/users.html) for more info. 19 | 20 | **Quick installation (Fixed from HTTPlug documentation)** 21 | ``` 22 | composer require php-http/curl-client guzzlehttp/psr7 php-http/message http-interop/http-factory-guzzle 23 | ``` 24 | 25 | :warning: **Note**: If you don't follow this requirement before require the SDK, composer will throw you an error. 26 | 27 | ### Setup 28 | 29 | The only supported installation method is via [Composer](https://getcomposer.org). Run the following command to require this SDK in your project: 30 | 31 | ``` 32 | composer require multitheftauto/mtasa-php-sdk 33 | ``` 34 | 35 | ## A simple example 36 | 37 | There are three ways to call an MTA server's exported functions, as shown in the following example: 38 | 39 | ```php 40 | getResource('someResource')->call('callableFunction', $arg1, $arg2, $arg3, ...); 53 | // or 54 | $response = $mta->getResource('someResource')->call->callableFunction($arg1, $arg2, $arg3, ...); 55 | 56 | var_dump($response); 57 | ``` 58 | 59 | # Development environment setup 60 | 61 | **Prerequisites**: 62 | - [docker-compose](https://docs.docker.com/compose/install/) 63 | 64 | First, we need to build the local docker image. To do this, run the following command: 65 | 66 | $ docker-compose build 67 | 68 | We will be using an alias for executing the development commands. 69 | 70 | $ alias dcli='docker-compose -f docker-compose.cli.yml run --rm' 71 | 72 | **Install dependencies**: 73 | 74 | $ dcli composer install 75 | 76 | ## Running tests 77 | 78 | To run the project tests and validate the coding standards: 79 | 80 | $ dcli composer test 81 | 82 | To run all unit tests you can use: 83 | 84 | $ dcli phpunit 85 | 86 | To run specific unit test you can use --filter option: 87 | 88 | $ dcli phpunit --filter=ClassName::MethodName 89 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "multitheftauto/mtasa-php-sdk", 3 | "description": "MTA SDK to interact with MTA's server.", 4 | "type": "library", 5 | "license": "MIT", 6 | "minimum-stability": "stable", 7 | "prefer-stable": true, 8 | "homepage": "https://multitheftauto.com/", 9 | "support": { 10 | "chat": "https://discord.com/invite/mtasa", 11 | "forum": "https://forum.multitheftauto.com", 12 | "wiki": "https://wiki.multitheftauto.com/wiki/PHP_SDK" 13 | }, 14 | "require": { 15 | "php": "^7.4 || ^8.0", 16 | "ext-json": "*", 17 | "php-http/client-implementation": "^1.0", 18 | "php-http/httplug": "^2.4", 19 | "psr/http-factory": "^1.0" 20 | }, 21 | "require-dev": { 22 | "composer/package-versions-deprecated": "1.11.99.5", 23 | "friendsofphp/php-cs-fixer": "^2.19", 24 | "guzzlehttp/psr7": "^2.5", 25 | "http-interop/http-factory-guzzle": "^1.2", 26 | "infection/infection": "^0.21.5", 27 | "php-http/mock-client": "^1.1", 28 | "phpspec/prophecy": "~1.17", 29 | "phpstan/phpstan": "^1.10", 30 | "phpunit/phpunit": "^9" 31 | }, 32 | "config": { 33 | "platform": { 34 | "php": "7.4" 35 | }, 36 | "preferred-install": { 37 | "*": "dist" 38 | }, 39 | "sort-packages": true, 40 | "allow-plugins": { 41 | "infection/extension-installer": true 42 | } 43 | }, 44 | "autoload": { 45 | "psr-4": { 46 | "MultiTheftAuto\\Sdk\\": "src/" 47 | } 48 | }, 49 | "scripts": { 50 | "infection": "infection", 51 | "lint": "php-cs-fixer fix --verbose --show-progress=estimating", 52 | "lint:check": [ 53 | "php-cs-fixer fix --dry-run --verbose --show-progress=estimating" 54 | ], 55 | "phpunit": "phpunit tests", 56 | "phpstan": "phpstan analyse", 57 | "test": [ 58 | "@lint:check", 59 | "@phpunit", 60 | "@phpstan" 61 | ] 62 | } 63 | } 64 | -------------------------------------------------------------------------------- /docker-compose.cli.yml: -------------------------------------------------------------------------------- 1 | version: '3.7' 2 | services: 3 | composer: 4 | image: multitheftauto/mtasa-php-sdk:latest 5 | init: true 6 | volumes: 7 | - .:/application 8 | - composer-cache:/root/.composer/cache 9 | entrypoint: composer 10 | 11 | phpunit: 12 | image: multitheftauto/mtasa-php-sdk:latest 13 | init: true 14 | volumes: 15 | - .:/application 16 | entrypoint: vendor/bin/phpunit 17 | 18 | php: 19 | image: multitheftauto/mtasa-php-sdk:latest 20 | init: true 21 | volumes: 22 | - .:/application 23 | 24 | volumes: 25 | composer-cache: 26 | name: composer-cache -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: '3.7' 2 | services: 3 | php: 4 | build: 5 | context: . 6 | dockerfile: docker/Dockerfile 7 | image: multitheftauto/mtasa-php-sdk:latest -------------------------------------------------------------------------------- /docker/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM php:7.4-cli 2 | 3 | RUN pecl install xdebug \ 4 | && docker-php-ext-enable xdebug 5 | 6 | # Install unzip for composer dependencies 7 | RUN apt-get update \ 8 | && apt-get install -y --no-install-recommends unzip \ 9 | && apt-get purge -y --autoremove 10 | 11 | ENV COMPOSER_ALLOW_SUPERUSER 1 12 | ENV COMPOSER_HOME /root/.composer 13 | 14 | COPY --from=composer:2.1.5 /usr/bin/composer /usr/bin/composer 15 | 16 | WORKDIR /application 17 | 18 | CMD ["php"] 19 | -------------------------------------------------------------------------------- /infection.json.dist: -------------------------------------------------------------------------------- 1 | { 2 | "timeout": 10, 3 | "source": { 4 | "directories": [ 5 | "src" 6 | ] 7 | }, 8 | "logs": { 9 | "text": "infection.log" 10 | }, 11 | "mutators": { 12 | "@default": true 13 | } 14 | } -------------------------------------------------------------------------------- /src/Exception/AccessDeniedException.php: -------------------------------------------------------------------------------- 1 | user = $user; 32 | $this->password = $password; 33 | } 34 | 35 | public function getUser(): string 36 | { 37 | return $this->user; 38 | } 39 | 40 | public function getPassword(): string 41 | { 42 | return $this->password; 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /src/Model/Element.php: -------------------------------------------------------------------------------- 1 | id = $id; 31 | } 32 | 33 | public static function fromServer(string $value): self 34 | { 35 | $id = substr($value, 3); 36 | 37 | return new static($id); 38 | } 39 | 40 | public function getId(): string 41 | { 42 | return $this->id; 43 | } 44 | 45 | public function jsonSerialize(): string 46 | { 47 | return self::SERVER_PREFIX . $this->id; 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /src/Model/Resource.php: -------------------------------------------------------------------------------- 1 | name = $name; 44 | $this->mtaService = $mtaService; 45 | $this->call = new ResourceCall($this); 46 | } 47 | 48 | public static function fromServer(string $value): self 49 | { 50 | $name = substr($value, 3); 51 | return new static($name); 52 | } 53 | 54 | public function getName(): string 55 | { 56 | return $this->name; 57 | } 58 | 59 | /** 60 | * @param mixed ...$arguments 61 | * 62 | * @throws \Http\Client\Exception 63 | * @return array|mixed[]|null 64 | */ 65 | public function call(string $function, ...$arguments) 66 | { 67 | if (!$this->mtaService) { 68 | throw new Exception(sprintf(self::UNDEFINED_SERVICE_EXCEPTION, $this->name)); 69 | } 70 | 71 | return $this->mtaService->callFunction($this->name, $function, $arguments); 72 | } 73 | 74 | public function jsonSerialize(): string 75 | { 76 | return self::SERVER_PREFIX . $this->name; 77 | } 78 | } 79 | -------------------------------------------------------------------------------- /src/Model/ResourceCall.php: -------------------------------------------------------------------------------- 1 | resource = $resource; 29 | } 30 | 31 | /** 32 | * @param mixed[] $arguments 33 | * 34 | * @throws \Http\Client\Exception 35 | * @return array|mixed[]|null 36 | */ 37 | public function __call(string $name, array $arguments) 38 | { 39 | return $this->resource->call($name, ...$arguments); 40 | } 41 | } 42 | -------------------------------------------------------------------------------- /src/Model/Resources.php: -------------------------------------------------------------------------------- 1 | resources, function(MtaResource $resource) use ($name) { 29 | return $resource->getName() == $name; 30 | }); 31 | 32 | $resource = current($found); 33 | return $resource? $resource : null; 34 | } 35 | 36 | public function add(MtaResource $resource): void 37 | { 38 | $this->resources[] = $resource; 39 | } 40 | 41 | /** 42 | * @return MtaResource[] 43 | */ 44 | public function all(): array 45 | { 46 | return $this->resources; 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /src/Model/Server.php: -------------------------------------------------------------------------------- 1 | host = $host; 38 | $this->httpPort = $httpPort; 39 | } 40 | 41 | public function getHost(): string 42 | { 43 | return $this->host; 44 | } 45 | 46 | public function getPort(): int 47 | { 48 | return $this->httpPort; 49 | } 50 | 51 | public function getEndpoint(): string 52 | { 53 | return sprintf('%s:%s', $this->host, $this->httpPort); 54 | } 55 | } 56 | -------------------------------------------------------------------------------- /src/Mta.php: -------------------------------------------------------------------------------- 1 | mtaService = new MtaService( 50 | $server, 51 | $auth, 52 | $httpClient ?? HttpClientDiscovery::find(), 53 | $requestFactory ?? Psr17FactoryDiscovery::findRequestFactory(), 54 | $streamFactory ?? Psr17FactoryDiscovery::findStreamFactory() 55 | ); 56 | 57 | $this->resources = new Resources(); 58 | } 59 | 60 | public function getService(): MtaService 61 | { 62 | return $this->mtaService; 63 | } 64 | 65 | public function getResource(string $resourceName): MtaResource 66 | { 67 | $resource = $this->resources->findByName($resourceName); 68 | 69 | if (empty($resource)) { 70 | $resource = new MtaResource($resourceName, $this->mtaService); 71 | $this->resources->add($resource); 72 | } 73 | 74 | return $resource; 75 | } 76 | 77 | public function getResourcesInstance(): Resources 78 | { 79 | return $this->resources; 80 | } 81 | 82 | /** 83 | * @codeCoverageIgnore 84 | * @return array|mixed[]|null 85 | */ 86 | public static function getInput(): ?array 87 | { 88 | return ElementTransformer::fromServer(Input::get()) ?? null; 89 | } 90 | 91 | /** 92 | * @param mixed ...$arguments 93 | */ 94 | public static function doReturn(...$arguments): void 95 | { 96 | echo ElementTransformer::toServer($arguments); 97 | } 98 | } 99 | -------------------------------------------------------------------------------- /src/Response/HttpStatusValidator.php: -------------------------------------------------------------------------------- 1 | response = $response; 36 | } 37 | 38 | /** 39 | * @throws Exception 40 | */ 41 | public function validate(): void 42 | { 43 | $statusCode = $this->response->getStatusCode(); 44 | 45 | switch ($statusCode) { 46 | case 401: 47 | { 48 | throw new AccessDeniedException(); 49 | } 50 | case 404: 51 | { 52 | throw new NotFoundStatusException(); 53 | } 54 | case 200: 55 | { 56 | if ($this->response->getBody() == self::ERROR_NOT_FOUND_BODY) { 57 | throw new FunctionNotFoundException(); 58 | } 59 | break; 60 | } 61 | default: 62 | { 63 | throw new Exception( 64 | sprintf( 65 | self::SOMETHING_WENT_WRONG, 66 | $statusCode, 67 | $this->response->getBody() 68 | ) 69 | ); 70 | } 71 | } 72 | } 73 | } 74 | -------------------------------------------------------------------------------- /src/Service/MtaService.php: -------------------------------------------------------------------------------- 1 | server = $server; 64 | $this->auth = $auth; 65 | $this->httpClient = $httpClient; 66 | $this->requestFactory = $requestFactory; 67 | $this->streamFactory = $streamFactory; 68 | } 69 | 70 | /** 71 | * @param mixed[] $arguments 72 | * 73 | * @throws \Http\Client\Exception 74 | * @throws \Exception 75 | * @return mixed[]|null 76 | */ 77 | public function callFunction(string $resourceName, string $functionName, array $arguments = []): ?array 78 | { 79 | $requestData = ElementTransformer::toServer($arguments); 80 | $streamBody = $this->streamFactory->createStream($requestData); 81 | 82 | $endpoint = $this->getEndpointToResourceFunction($resourceName, $functionName); 83 | $request = $this->requestFactory->createRequest(self::HTTP_METHOD, $endpoint); 84 | $request = $request->withBody($streamBody); 85 | 86 | $auth = new BasicAuth($this->auth->getUser(), $this->auth->getPassword()); 87 | $request = $auth->authenticate($request); 88 | 89 | $response = $this->httpClient->sendRequest($request); 90 | 91 | $statusValidator = new HttpStatusValidator($response); 92 | $statusValidator->validate(); 93 | 94 | $responseBody = (string) $response->getBody(); 95 | 96 | return ElementTransformer::fromServer($responseBody) ?? null; 97 | } 98 | 99 | private function getEndpointToResourceFunction(string $resourceName, string $functionName): string 100 | { 101 | return sprintf( 102 | self::MTA_RESOURCE_ENDPOINT, 103 | $this->server->getEndpoint(), 104 | $resourceName, 105 | $functionName 106 | ); 107 | } 108 | } 109 | -------------------------------------------------------------------------------- /src/Transformer/ElementTransformer.php: -------------------------------------------------------------------------------- 1 |