PHP SDK: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (Lua)
(39 intermediate revisions by 13 users not shown)
Line 1: Line 1:
You can access the MTA Web Interface from almost any programming language that can request web pages using HTTP POST and encode and decode [[JSON]].
__NOTOC__
You can access the MTA Web Interface from almost any programming language that can request web pages. PHP can do this very easily.


PHP can do this very easily! This SDK provides one function "callFunction" that will allow you to call any exported script functions on any server that you have access to.
This SDK provides one function call that will allow you to call any exported script functions on any server that you have access to.


The download below includes two example pages - one that shows a simple scoreboard, the other that shows the automatic handling of element and resource objects.
See the [https://wiki.multitheftauto.com/wiki/PHP_SDK official wiki page] for further information.


==Functions==
== Installation ==
===callFunction===
 
'''Syntax:'''
=== Prerequisites ===
<syntaxhighlight lang="lua">[php]
 
returns[] = callFunction ( "hostname:httpPort", "resourceName", "functionName" [,args...]);
This SDK requires PHP 7.1 or greater.
 
=== HTTPlug client abstraction ===
 
As this SDK uses HTTPlug, you will have to require some libraries for get it working. See [http://docs.php-http.org/en/latest/httplug/users.html “HTTPlug for library users”] for more info.
 
:warning: '''Note''': If you don’t follow this requirement before require the SDK, composer will throw you an error.
 
=== Setup ===
 
The only supported installation method is via [https://getcomposer.org Composer]. Run the following command to require this SDK in your project:
 
<pre>composer require multitheftauto/mtasa-php-sdk</pre>
== A simple example ==
 
There are three ways to call an MTA server’s exported functions, as shown in the following example:
 
<syntaxhighlight lang="php">
<?php
 
require_once('vendor/autoload.php');
 
use MultiTheftAuto\Sdk\Mta;
use MultiTheftAuto\Sdk\Model\Server;
use MultiTheftAuto\Sdk\Model\Authentication;
 
$server = new Server('127.0.0.1', 22005);
$auth = new Authentication('myUser', 'myPassword');
$mta = new Mta($server, $auth);
 
$response = $mta->getResource('someResource')->call('callableFunction', $arg1, $arg2, $arg3, ...);
// or
$response = $mta->getResource('someResource')->call->callableFunction($arg1, $arg2, $arg3, ...);
 
var_dump($response);
</syntaxhighlight>
</syntaxhighlight>


==Examples==
==A page that can be called by [[callRemote]]==
<syntaxhighlight lang="lua">[php]
This example just adds two numbers passed to it by a Lua script.
include ( "mta.php" );
 
$retn = callFunction ( "bastage.student.utwente.nl:33004", "echobot", "getThisResource" ); // $retn is an array containing the values the function returned
'''PHP:''' (for the page that Lua expects to be at ''<nowiki>http://www.example.com/page.php</nowiki>'')
$resource = $retn[0]; // the first returned value is the resource
<syntaxhighlight lang="php">
$retn = callFunction ( "bastage.student.utwente.nl:33004", "echobot", "getResourceName", $resource );
<?php  
$resourceName = $retn[0]; // contains the name of the resource 'echobot'
 
require_once('vendor/autoload.php');
 
use MultiTheftAuto\Sdk\Mta;
 
$input = Mta::getInput();
Mta::doReturn($input[0] + $input[1]);
</syntaxhighlight>
</syntaxhighlight>


==Caveats==
'''Lua:'''
* This only supports PHP 5.0.
<syntaxhighlight lang="lua">
* You cannot currently compare two Resource or Element instances that you expect to be identical - you need to do a "deep compare", comparing either the "id" fields or the "name" fields.
-- result is called when the function returns
function result(sum)
    outputChatBox(sum)
end
function addNumbers(number1, number2)
    callRemote ( "http://www.example.com/page.php", result, number1, number2 )
end
addNumbers ( 123, 456 ) -- call the function
</syntaxhighlight>
 
== Releases ==
 
Visit [https://github.com/multitheftauto/mtasa-php-sdk/releases the releases page on GitHub] to download the SDK.
 
=== Note for Python ===
 
There is a community made Python SDK with the same semantics on [https://gitlab.com/OwlGamingCommunity/mta-python-sdk the OwlGaming Gitlab] for use on Python projects.
 
== Version History ==
 
You can see in the [https://github.com/multitheftauto/mtasa-php-sdk/blob/master/CHANGELOG.md repository changelog file] the changes applied.


==Download==
[[Category:Tutorials]]
*[http://misc.opencoding.net/mta/mtaphpsdk_0.1.zip Download Version 0.1]

Revision as of 20:47, 4 October 2019

You can access the MTA Web Interface from almost any programming language that can request web pages. PHP can do this very easily.

This SDK provides one function call that will allow you to call any exported script functions on any server that you have access to.

See the official wiki page for further information.

Installation

Prerequisites

This SDK requires PHP 7.1 or greater.

HTTPlug client abstraction

As this SDK uses HTTPlug, you will have to require some libraries for get it working. See “HTTPlug for library users” for more info.

warning: Note: If you don’t follow this requirement before require the SDK, composer will throw you an error.

Setup

The only supported installation method is via Composer. Run the following command to require this SDK in your project:

composer require multitheftauto/mtasa-php-sdk

A simple example

There are three ways to call an MTA server’s exported functions, as shown in the following example:

<?php

require_once('vendor/autoload.php');

use MultiTheftAuto\Sdk\Mta;
use MultiTheftAuto\Sdk\Model\Server;
use MultiTheftAuto\Sdk\Model\Authentication;

$server = new Server('127.0.0.1', 22005);
$auth = new Authentication('myUser', 'myPassword');
$mta = new Mta($server, $auth);

$response = $mta->getResource('someResource')->call('callableFunction', $arg1, $arg2, $arg3, ...);
// or
$response = $mta->getResource('someResource')->call->callableFunction($arg1, $arg2, $arg3, ...);

var_dump($response);

A page that can be called by callRemote

This example just adds two numbers passed to it by a Lua script.

PHP: (for the page that Lua expects to be at http://www.example.com/page.php)

<?php 

require_once('vendor/autoload.php');

use MultiTheftAuto\Sdk\Mta;

$input = Mta::getInput();
Mta::doReturn($input[0] + $input[1]);

Lua:

-- result is called when the function returns
function result(sum)
    outputChatBox(sum)
end
function addNumbers(number1, number2)
    callRemote ( "http://www.example.com/page.php", result, number1, number2 )
end 
addNumbers ( 123, 456 ) -- call the function

Releases

Visit the releases page on GitHub to download the SDK.

Note for Python

There is a community made Python SDK with the same semantics on the OwlGaming Gitlab for use on Python projects.

Version History

You can see in the repository changelog file the changes applied.