Search by

pipetower / pipetower-php-sdk

pipetower

The PHP SDK for the Pipetower API

Package info

github.com/pipetower/pipetower-php-sdk

Homepage

pkg:composer/pipetower/pipetower-php-sdk

Statistics

Installs: 8

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v2.1.0 2026-11-06 23:24 UTC

This package is auto-updated.

Last update: 2026-11-06 23:27:02 UTC


README

The PHP SDK for the Pipetower API v1 Pipetower API Docs

Installation

composer require pipetower/pipetower-php-sdk

Usage

$pt = new \Pipetower\PhpSdk\Pipetower('api-token');

// another instance, e.g. a local one
$pt = new \Pipetower\PhpSdk\Pipetower('api-token', 'http://pipetower.localhost/api/v1/');

Resources contain all attributes the API returns, as properties ($server->name) and as array ($server->attributes). Lists return ['data' => [...resources], 'meta' => ['total' => …, 'has_more' => …]] and take the parameters limit (at most 100) and page.

$pt->ping();                                    // reachable, no token needed
$pt->status();                                  // the token is valid

$pt->account->info();
$pt->account->vars();

$pt->servers->all(['search' => 'web', 'team' => $teamId, 'tag' => 'prod']);
$pt->servers->retrieve($serverId);              // incl. the latest metrics
$pt->servers->connect($serverId);
$pt->servers->disconnect($serverId);
$pt->servers->metrics($serverId);
$pt->servers->vars($serverId);

$pt->actions->all(['search' => 'deploy']);
$pt->actions->retrieve($actionId);
$pt->workflows->all();
$pt->workflows->retrieve($workflowId);
$pt->pipes->all();
$pt->pipes->retrieve($pipeId);
$pt->templates->all();
$pt->templates->retrieve($templateId);

// Actions, workflows and templates are created and changed through their definition: the portable
// description an export file contains (see the API docs). The same methods exist on workflows and templates.
$pt->actions->example();                        // a definition with every option, as array
$pt->actions->example(asYaml: true);            // as YAML with comments which explain every key
$pt->actions->validate($definition, team: 'Ops');  // only check it, returns the normalized definition
$action = $pt->actions->create($definition, team: 'Ops'); // the team is needed with several teams
$pt->actions->update($action->id, $definition); // replaces the whole action
$pt->actions->definition($action->id);          // the definition of an existing action
$pt->actions->delete($action->id);              // throws a ConflictException when still used
$pt->teams->all();
$pt->teams->retrieve($teamId);
$pt->teams->vars($teamId);

$run = $pt->runs->create([
    'action_id' => $actionId,                   // or 'workflow_id'
    'server_ids' => [$serverId],
    'variables' => ['BRANCH' => 'main'],
]);
$pt->runs->all(['server' => $serverId, 'action' => $actionId, 'workflow' => $workflowId, 'pipe' => $pipeId, 'status' => 'failed']);
$pt->runs->retrieve($run->id);                  // with its executions and steps
$pt->runs->retrieve($run->id, withOutput: true);
$pt->runs->terminate($run->id);

$pt->runExecutions->retrieve($executionId, withOutput: true);
$pt->runExecutions->terminate($executionId);
$pt->runExecutions->log($executionId);         // the full log as text

$pt->terminalSessions->open($serverId);         // a shared session, its ticket attaches through the gateway
$pt->terminalSessions->attach($sessionId);
$pt->gateway->ticket();                         // URL and single-use ticket of the real-time gateway

Errors

Unsuccessful requests throw a Pipetower\PhpSdk\Exceptions\PipetowerException with the message of the API, the status as code and the response as $e->body. The status decides the subclass: UnauthenticatedException (401), UnauthorizedException (403), NotFoundException (404), MethodNotAllowedException (405), ConflictException (409, an object which is still used cannot be deleted, $e->usedBy() names the users) and ValidationException (422) with the errors by field:

try {
    $pt->runs->create(['action_id' => $actionId, 'server_ids' => [$serverId]]);
} catch (\Pipetower\PhpSdk\Exceptions\ValidationException $e) {
    $e->getMessage();                           // The variable NAME is required.
    $e->errors();                               // ['variables.NAME' => ['The variable NAME is required.']]
}

Upgrade from 1.x

  • The API is under /api/v1/, a custom base URI needs the v1/ too
  • servers|actions|workflows|pipes->runs($id) are replaced by runs->all(['server' => $id]) etc.
  • runExecutions->details($id) is replaced by runExecutions->retrieve($id, withOutput: true)
  • Resource attributes are read through __get: unknown attributes are null, all are in $resource->attributes
  • Exceptions carry the message of the API instead of the raw response body