Technology Sharing

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

original:SOAP with TrinityCore | TrinityCore MMo Project Wiki

 

How to use SOAP to interact with TC

SOAP stands for Simple Object Access Protocol and is an older form of standards-based web service access protocol similar to REST. As long as the necessary configuration is in place, you can use SOAP to send commands to the TrinityCore server.
A good way to understand SOAP is to compare it to its contemporary REST. The following article explains this very well - https://smartbear.com/blog/soap-vs-rest-whats-the-difference/.
The main difference between the two is that SOAP relies entirely on XML to provide responses and accept payloads. PHP provides some methods to make this process easier, but depending on your use case, you may need to become familiar with XML.

Configuration

worldserver.conf
Make sure the settings in the configuration file are set correctly.

#    SOAP.Enable
#        Description: Enable soap service.
#        Default:     0 - (Disabled)
#                     1 - (Enabled)
SOAP.Enabled = 1
 
#    SOAP.IP
#        Description: Bind SOAP service to IP/hostname.
#        Default:     "127.0.0.1" - (Bind to localhost)
SOAP.IP = "127.0.0.1"
 
#    SOAP.Port
#        Description: TCP port to reach the SOAP service.
#        Default:     7878
SOAP.Port = 7878

Given your specific RBAC access configuration, you'll also need a user account that has permissions to use GM commands. It's probably a good idea to create a limited-access account specifically for this purpose, rather than one that one person uses.

NOTE: At the time of writing, TC 335a only supports HTTP, so be careful not to send secrets (passwords, etc.) this way. Assume that anything passed is in clear text and can be read by anyone.
If you plan on connecting remotely via SOAP, you should definitely take steps to ensure a secure connection. One potential approach is to go through a reverse SSL proxy via apache or nginx. However, this is outside the scope of this guide and will not be covered.

HTTP client for prototyping

There are a few clients that can quickly establish a connection and test console commands:
Postman: https://www.postman.com/ (network, desktop agent/client)
insomnia：https://insomnia.rest/
Nightingale: https://nightingale.rest/
They all provide various details but ultimately work in much the same way. Thanks to Jackpoz for the specific steps for Postman - https://www.postman.com/.
Postman comes in two flavors: a web interface (along with a proxy that can be installed to do localhost requests) and a fully client-side desktop application. The instructions are the same in both cases.
Under "My Workspace", find the "Import" button. You will use the Raw Text option.
Copy and paste the following JSON into the text box. Make sure to update the credentials under item.request.auth.basic to the GM user mentioned earlier.

{
  "info": {
    "name": "TC SOAP",
    "schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
  },
  "item": [
    {
      "name": "server info",
      "request": {
        "auth": {
          "type": "basic",
          "basic": {
            "username": "CHANGEME",
            "password": "CHANGEME",
            "showPassword": false
          }
        },
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "<?xml version="1.0" encoding="utf-8"?>rn<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:TC">rn<SOAP-ENV:Body>rn<ns1:executeCommand>rn<command>server info</command>rn</ns1:executeCommand>rn</SOAP-ENV:Body>rn</SOAP-ENV:Envelope>",
          "options": {
            "raw": {
              "language": "xml"
            }
          }
        },
        "url": "http://127.0.0.1:7878"
      },
      "response": []
    }
  ]
}

You should see TC SOAP as a collection to import. Click Import.
This will populate a new collection with the correct HTTP method (POST) and the details under the Authorization and Body tabs.
Under the Body tab, notice the XML payload and the Server Information commands that are pre-populated for you.
Clicking the "Send" button will submit the request and provide an XML response.
On the right side of the Postman interface, a</> symbol will open a code snippet that can translate the request into the language of your choice.
¶ Using PHP
To interact with TrinityCore using PHP, you need to make sure you have the PHP-soap extension installed. Also make sure you are using a version of PHP that is still actively supported. The code samples were tested on PHP 7.4 to PHP 8.1.
In all of these examples, the urn:TC URI is a required parameter because we do not provide a WSDL document.
SoapClient-https://www.php.net/manual/en/class.soapclient.php

$command  = 'server info';
 
$opts = [
    'http' => [
        'header' => "Authorization: Basic " . base64_encode("USERNAME:PASSWORD")
    ]];
 
$client = new SoapClient($wsdl = null, [
    'stream_context' => stream_context_create($opts),
    'location' => 'http://127.0.0.1:7878',
    'uri' => 'urn:TC',
]);
 
try {
    $result = $client->executeCommand(new SoapParam($command, 'command'));
} catch (Exception $e) {
    die($e->getMessage());
}
 
echo $result;

Note that we are passing a HTTP basic authorization header with base64 encoded username and password (separated by a colon). Alternatively, you could omit the stream_context parameter, and instead include a (login) username and password in your SoapClient configuration.

$command  = 'server info';
 
$client = new SoapClient($wsdl = null, [
    'location' => 'http://127.0.0.1:7878',
    'uri' => 'urn:TC',
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
]);
 
try {
    $result = $client->executeCommand(new SoapParam($command, 'command'));
} catch (Exception $e) {
    die($e->getMessage());
}
 
echo $result;

Either approach is fine - but don't be fooled! Base 64 encoding does not inherently make it more secure.

Remember that the SOAP client can only recognize failures to connect, or misconfigurations. It will not know if you've provided an invalid command. So it's up to you to parse the results and decide if the intended result was a success or not. Output will be just as if you performed the command on the console.

Lastly, if you'd rather not rely on the SOAP extension or client, you can form the XML payload and parse the resulting XML response yourself. You'll still need the cURL extension, but this is usually available if not enabled by default.

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns1="urn:TC">
    <SOAP-ENV:Body>
        <ns1:executeCommand>
            <command>server info</command>
        </ns1:executeCommand>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

$curl = curl_init();
 
curl_setopt_array($curl, [
    CURLOPT_POSTFIELDS => $payload, // $payload is the XML provided above
    CURLOPT_URL => 'http://127.0.0.1:7878',
    CURLOPT_TIMEOUT => 0,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        "Authorization: Basic " . base64_encode("{$user}:{$pass}"),
        'Content-Type: application/xml',
    ],
]);
 
$response = curl_exec($curl);
curl_close($curl);
echo $response;