PHP SDK: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (Added community python SDK)
No edit summary
Line 1: Line 1:
__NOTOC__
__NOTOC__
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]]. PHP can do this very easily.
= MTA:SA PHP SDK =


This SDK provides one function ''call'' that will allow you to call any exported script functions on any server that you have access to.
You can access the MTA Web Interface from almost any programming language that can request web pages. PHP can do this very easily.


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.
This SDK provides one function call that will allow you to call any exported script functions on any server that you have access to.


If you use this and make any improvements, feel free to send us a copy and we can host it for others to benefit from.
See the [https://wiki.multitheftauto.com/wiki/PHP_SDK official wiki page] for further information.


==Functions==
== Installation ==
===call===
This function calls an exported function in a specific resource.


'''Syntax:'''
=== Prerequisites ===
<syntaxhighlight lang="php">
 
$mtaServer = new mta( $hostname, $port, $username, $password );
This SDK requires PHP 7.1 or greater.
$resource = $mtaServer->getResource ( $resourceName );
 
$returns[] = $resource->call ( "functionName" [,args...] );
=== HTTPlug client abstraction ===
</syntaxhighlight>
 
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 ==


===getInput===
There are three ways to call an MTA server’s exported functions, as shown in the following example:
This function is for use with web pages that are called by [[callRemote]].


'''Syntax:'''
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
$inputData = mta::getInput();
<?php
</syntaxhighlight>


===doReturn===
require_once('vendor/autoload.php');
Use this function when you want to return data when a page is called with [[callRemote]]. You should '''NOT''' output any other data to the page, e.g. using ''echo'' as this will cause the return to fail.


'''Syntax:'''
use MultiTheftAuto\Sdk\Mta;
<syntaxhighlight lang="php">
use MultiTheftAuto\Sdk\Model\Server;
mta::doReturn( argument1, argument2 ... argumentN );
use MultiTheftAuto\Sdk\Model\Authentication;
</syntaxhighlight>


==Examples==
$server = new Server('127.0.0.1', 22005);
<syntaxhighlight lang="php">
$auth = new Authentication('myUser', 'myPassword');
include( "mta_sdk.php" );
$mta = new Mta($server, $auth);
$mtaServer = new mta("bastage.net", 33004);
$resource = $mtaServer->getResource ( "echobot" );
$retn = $resource->call ( "getThisResource" ); // $retn is an array containing the values the function returned
$resourceElement = $retn[0]; // the first returned value is the resource
$retn = $resource->call ( "getResourceName", $resourceElement );  
$resourceName = $retn[0]; // contains the name of the resource 'echobot'
</syntaxhighlight>


==Authentication==
$response = $mta->getResource('someResource')->call('callableFunction', $arg1, $arg2, $arg3, ...);
If the server you are accessing requires authentication, you must pass the ''http_username'' and ''http_password'' variables to your instantiated instance of the mta() class.
// or
$response = $mta->getResource('someResource')->call->callableFunction($arg1, $arg2, $arg3, ...);


'''Example:'''
var_dump($response);
<syntaxhighlight lang="php">
include( "mta_sdk.php" );
$mtaServer = new mta("example.com", 33004, "myUsername", "myPassword" );
$mtaServer->getResource("someResource")->call("someFunction");
</syntaxhighlight>
</syntaxhighlight>


Line 61: Line 54:
'''PHP:''' (for the page that LUA expects to be at ''<nowiki>http://www.example.com/page.php</nowiki>'')
'''PHP:''' (for the page that LUA expects to be at ''<nowiki>http://www.example.com/page.php</nowiki>'')
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
include( "mta_sdk.php" );
<?php
$input = mta::getInput();
 
mta::doReturn($input[0] + $input[1]);
require_once('vendor/autoload.php');
 
$input = Mta::getInput();
Mta::doReturn($input[0] + $input[1]);
</syntaxhighlight>
</syntaxhighlight>
'''LUA:'''
'''LUA:'''
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 77: Line 74:
</syntaxhighlight>
</syntaxhighlight>


==Caveats==
== Releases ==
* This only works with PHP 5.0 and above.
* You cannot currently compare two Element instances that you expect to be identical - you need to do a "deep compare", comparing the "id" fields.
 
==Download==
=== Note for version 0.4 ===
On line 80 in mta_sdk.php you will find the string:
<syntaxhighlight lang="php">
echo $json_output;
</syntaxhighlight>
 
Replace that one with:
<syntaxhighlight lang="php">
//echo $json_output;
</syntaxhighlight>
 
Or remove it completly!
 
=== Note for PHP 7.2.10 (and upwards) ===
 
Methods with the same name as their class will not be constructors in a future version of PHP (7.0.x)+
 
Using PHP 7.2.10 this seems to break completely
 
On line 211 and 227 in mta_sdk.php find the following:
 
<syntaxhighlight lang="php">
line 211: class Element
line 227: class Resource
</syntaxhighlight>
 
Change these to:
 
<syntaxhighlight lang="php">
line 211: class ElementClass
line 227: class ResourceClass
</syntaxhighlight>
 
Now on line 42 and 99 find the following:
 
<syntaxhighlight lang="php">
line 42: $res = new Resource ( $resourceName, $this );
line 99: $item = new Element( substr( $item, 3 ) );
</syntaxhighlight>
 
Change these to:
 
<syntaxhighlight lang="php">
line 42: $res = new ResourceClass ( $resourceName, $this );
line 99: $item = new ElementClass( substr( $item, 3 ) );
</syntaxhighlight>
 
Now finally, on line 121, change this:
 
<syntaxhighlight lang="php">
if ( get_class($item) == "Element" || get_class($item) == "Resource" )
</syntaxhighlight>
 
To this:
 
<syntaxhighlight lang="php">
if ( get_class($item) == "ElementClass" || get_class($item) == "ResourceClass" )
</syntaxhighlight>
 
All fixed!


Visit [https://github.com/multitheftauto/mtasa-php-sdk/releases the releases page on GitHub] to download the SDK.
Visit [https://github.com/multitheftauto/mtasa-php-sdk/releases the releases page on GitHub] to download the SDK.
Line 151: Line 84:
== Version History ==
== Version History ==


* Version 0.4 - Renamed ''public function mta(..)'' to ''public function __construct(..)''.
You can see in the [https://github.com/multitheftauto/mtasa-php-sdk/blob/master/CHANGELOG.md repository changelog file] the changes applied.
* Version 0.3-fix - make call work with args
* Version 0.3 - Neater syntax, support functions for [[callRemote]] (this version is lost)
* Version 0.2 -  ''Deprecated - Syntax differs from examples shown above.'' - Adds authentication support.
* Version 0.1 - ''Deprecated - Syntax differs from examples shown above.''


[[Category:Tutorials]]
[[Category:Tutorials]]

Revision as of 01:30, 4 October 2019

MTA:SA PHP SDK

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');

$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.

Retrieved from "https://wiki.multitheftauto.com/wiki/PHP_SDK?oldid=64470"