pipetower / pipetower-php-sdk
The PHP SDK for the Pipetower API
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.8
Requires (Dev)
- phpunit/phpunit: ^10.4
- symfony/var-dumper: ^6.3
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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 thev1/too servers|actions|workflows|pipes->runs($id)are replaced byruns->all(['server' => $id])etc.runExecutions->details($id)is replaced byrunExecutions->retrieve($id, withOutput: true)- Resource attributes are read through
__get: unknown attributes arenull, all are in$resource->attributes - Exceptions carry the message of the API instead of the raw response body