- Are you already familiar with our API and do you want to get started with the PHP library right away? Then see our Github page to get started.
- In the 'examples' folder in the PHP library you'll find additional examples for using the PHP library of our API.
In this tutorial, we show how to use the PHP library of the TransIP REST API using several simple examples. Before proceeding with this article, ensure that you have read the following guides:
- Enabling the API in your TransIP account & generate a private key for authentication
- Getting started with the PHP library and setting up authentication
The following PHP examples are covered in this tutorial:
- Retrieving a list of all your VPSs (including specifications)
- Stopping a VPS
- Starting a VPS
- Resetting a VPS
- Retrieving available VPS products
- Showing available operating systems
- Ordering a VPS
- Attach Big Storage to your VPS
- Retrieving a list of your domains
- List DNS entries for a domain
- Updating a single existing DNS record
- Adding a single DNS record to a domain
Retrieving an overview of your VPSs
In this example, we show you how to retrieve an overview of all VPSs in your TransIP account. This creates an Array that contains the following information:
- name
- description
- product name
- operatingSystem
- diskSize
- memorySize
- cpus
- status
- ipAddress
- macAddress
- currentSnapshots
- maxSnapshots
- isLocked
- isBlocked
- isCustomerLocked
- availabilityZone
- tags
Create a file containing the code below, for example, /var/www/html/example.com/vps/GetVpss.php
<?php
/**
* This is an example on how to retrieve and list all VPSs in your TransIP account.
*/
require_once (__DIR__ . '/../Authenticate.php');
// Get all VPSs in your account
$vpss = $api->vps()->getAll();
$vpss = print_r($vpss, true);
echo "<pre>{$vpss}</pre>";
Do you want to retrieve the specifications of a specific VPS? Then use getByName($vpsName) instead of getAll.
Stopping a VPS
With the stop action, you put the VPS in 'stopped' status. This function is equivalent to turning off a computer with the physical 'off / on' button. This is not a graceful stop of your VPS and it is important to save your work first.
If the VPS is in a power cycle (reset), this API call will fail because stopping the VPS is part of the power cycle process.
Replace 'example-vps' with the name (not the description) of your VPS.
<?php
/**
* Use this API call in order to stop your VPS
*/
require_once(__DIR__ . '/../Authenticate.php');
$vpsName = 'example-vps';
$api->vps()->stop($vpsName);
Starting a VPS
This API call starts a VPS that is switched off. This function is the same as turning on a computer with the physical 'off / on' button.
If the VPS is in a power cycle (reset), this API call will fail because starting the VPS is part of the power cycle process.
<?php
/**
* Use this API call in order to start your VPS
*/
require_once(__DIR__ . '/../Authenticate.php');
$vpsName = 'example-vps';
$api->vps()->start($vpsName);
Resetting a VPS
This function immediately restarts your VPS and is equivalent to resetting a computer with the physical 'reset' button. This is not a graceful reset of your VPS and it is important to first save your work.
<?php
/**
* Use this API call in order to restart your VPS with a reset command
*/
require_once(__DIR__ . '/../Authenticate.php');
$vpsName = 'example-vps';
$api->vps()->reset($vpsName);
Retrieving available VPS products
With the products API call, you display an overview of all available VPS products that can be ordered via the API. When new products are released, they will be included in the output.
<?php
/**
* This is an example on how to retrieve all available VPS products.
*/
require_once(__DIR__ . '/Authenticate.php');
// Get all available products
$products = $api->products()->getAll();
$products = print_r($products, true);
echo "<pre>{$products}</pre>";
Showing available operating systems
With the vpsOperatingSystems API-call, you display an overview of all available operating systems. When new products are released, they will be included in the output.
In this example, we assume that you place the file with the code below in the same folder as 'Authenticate.php'.
<?php /** * This is an example on how to retrieve all available VPS products. */ require_once(__DIR__ . '/../Authenticate.php'); // Get all available products $OperatingSystems = $api->vpsOperatingSystems()->getAll(); $products = print_r($OperatingSystems, true);
echo "<pre>{$OperatingSystems
}</pre>";
Ordering a VPS
You can order a VPS with the vps->order API-call. After ordering, the VPS is delivered and deployed automatically.
- You can optionally specify add-ons in an array that are then automatically ordered as well.
- If you do not specify an availability zone, your VPS will be delivered in Amsterdam.
- When you enter a hostname, the first 32 characters of this are used as a 'description' of your VPS (i.e. the own name / description that you can give to a VPS in the control panel).
- A hostname is required for cPanel.
- Do you not want to add addons, but do you want to provide a hostname, availability zone, and / or description? Then, define addons as an empty array with: $addons = [];
- You can provide an unattended installation script which will be run immediately after the order has been processed, see the note beneath the code below.
When using this API call, an invoice will be generated in your TransIP account.
<?php
/**
* Using this API call, you are able to order a new VPS. After the order process has been completed (payment will occur
* at a later stage should direct debit be used) the VPS will automatically be provisioned and deployed. Values
* associated to the newly delivered VPS will be returned in a new call respectively.
*/
require_once(__DIR__ . '/../Authenticate.php');
/**
* Example 1: Order a VPS
*/
$productName = 'vps-bladevps-x1';
$operatingSystemToInstall = 'debian-9';
// Order VPS
$api->vps()->order(
$productName,
$operatingSystemToInstall
);
/**
* Example 2: Order a VPS with an addon and choose your data center
*/
$addons = ['vpsAddon-1-extra-ip-address'];
$hostName = 'server.yoursite.com';
$availabilityZone = 'ams0';
$description = 'My server';
// Order VPS
$api->vps()->order(
$productName,
$operatingSystemToInstall,
$addons,
$hostName,
$availabilityZone,
$description,
);
If you'd like to use an unattended installation as part of ordering a VPS, then also provide the following variable in the second exaple:
$base64InstallText = 'installscript';
The order command would then look as follows:
// Order VPS
$api->vps()->order(
$productName,
$operatingSystemToInstall,
$addons,
$hostName,
$availabilityZone,
$description,
$base64InstallText
);
The contents of the unattended installation script fall out of the scope of this tutorial, but you can consult Ubuntu, Debian or RedHat's documentation.
Click below for an example of a minimal install for Ubuntu 18.04.
Attach existing Big Storage to your VPS
You can attach a Big Storage using the 'update' function from the BigStorage Repository. Please note that your Big Storage can be attached to a maximum of one VPS and a maximum of ten Big Storages can be attached to a single VPS.
<?php
/**
* This is an example on how to attach a Big Storage to a VPS.
*/
require_once(__DIR__ . '/../Authenticate.php');
// Name of your Big Storage and VPS to which it will be attached
$bigStorageName = 'testtransip-bigstorage40';
$bigStorageVpsName = 'testtransip-vps28';
// Attach Big Storage to your VPS
$bigStorage = $api->bigStorages()->getByName($bigStorageName);
$bigStorage->setVpsName($bigStorageVpsName);
$api->bigStorages()->update($bigStorage);
Retrieving a list of your domains
In this example, we show you how to retrieve an overview of all domains in your TransIP account, regardless of whether they have been ordered via the API or the TransIP website. The output is an array that contains the following information:
- name
- authCode
- isTransferLocked
- registrationDate
- renewalDate
- isWhitelabel
- cancellationDate
- cancellationStatus
- isDnsOnly
- tags
<?php
/**
* This is an example on how to retrieve and list all domains in your TransIP account.
*/
require_once (__DIR__ . '/../Authenticate.php');
// Get a list of all domains in your account
$domains = $api->domains()->getAll();
$domains = print_r($domains, true);
echo "<pre>{$domains}</pre>";
Listing DNS records for a domain
In the example below, we show you how to list all DNS records for a specific domain.
<?php
/**
* This is an example on how to retrieve and list all DNS records for a domain in your TransIP account.
*/
require_once (__DIR__ . '/../Authenticate.php');
$domainName = 'example.com';
// Get the DNS for your domain
$domainDns = $api->domainDns()->getByDomainName($domainName);
$domainDns = print_r($domainDns, true);
echo "<pre>$domainDns</pre>";
Updating a single existing DNS record
Updates the content of an existing DNS record. You can update the name (setName), TTL (setExpire), type (setType) and / or value (setContent). Accepted values for TTL and type are:
- TTL: 60, 300, 3600, 86400
- Type: A, AAAA, CNAME, MX, NS, TXT, SRV, SSHFP, TLSA, CAA
You will receive an error message if the record does not yet exist.
<?php
/**
* This is an example on how to update a single existing DNS entry for a specific domain
*/
use Transip\Api\Library\Entity\Domain\DnsEntry;
require_once (__DIR__ . '/../Authenticate.php');
$domainName = 'example.com';
// Create a DNS entry object
$dnsEntry = new DnsEntry();
$dnsEntry->setName('apidemo');
$dnsEntry->setExpire('300');
$dnsEntry->setType('TXT');
$dnsEntry->setContent('transip demo');
// Apply entry
$api->domainDns()->updateEntry($domainName, $dnsEntry);
Adding a single new DNS record
Adds a new DNS record to a domain. You can update the name (setName), TTL (setExpire), type (setType) and / or value (setContent). Accepted values for TTL and type are:
- TTL: 60, 300, 3600, 86400
- Type: A, AAAA, CNAME, MX, NS, TXT, SRV, SSHFP, TLSA, CAA
<?php
/**
* This is an example on how to add a single new DNS entry to a specific domain
*/
use Transip\Api\Library\Entity\Domain\DnsEntry;
require_once (__DIR__ . '/../Authenticate.php');
$domainName = 'supporttest.nl';
// Create a DNS entry object
$dnsEntry = new DnsEntry();
$dnsEntry->setName('apidemo2');
$dnsEntry->setExpire('300');
$dnsEntry->setType('TXT');
$dnsEntry->setContent('transip demo');
// Apply entry
$api->domainDns()->updateEntry($domainName, $dnsEntry);
This concludes our examples on how to use the PHP library of our REST API.
Should you have any questions left regarding this article, do not hesitate to contact our support department. You can reach them via the ‘ContactUs’ button at the bottom of this page.
If you want to discuss this article with other users, please leave a message under 'Comments'.