README

This is a lightweight (dependency-free) php wrapper for the Shortcut.com REST version 3 API. See the official Shortcut API docs here.

Installation

To install with Composer:

composer require mikkelson/shortcut-php

After the package installation completes, use the autoloader provided by Composer.

require __DIR__ . '/vendor/autoload.php';

Or, without Composer:

Download this repo and include Shortcut.php

require_once('src/Shortcut.php');

Usage & Setup

Load the package namespace.

use Mikkelson\Shortcut;

Before making useful calls to Shortcut, create an instance of Shortcut, providing your Shortcut API token, which you can get here.

    
    $token = '213901-dk9AJ-3SOJ-8dj9-KAAa0smsa';

    $shortcut = new Shortcut($token);

Epics

Get

Get Epic returns information about the selected Epic.

$epic_id = '3000';

$epic = $shortcut->get('epics', $epic_id);

Update

Update Epic can be used to update numerous fields in the Epic. See complete list of available fields.

$epic_id = "4351";

$data = [
    'description' => 'Keep your developers happy by providing detailed descriptions (-;',
    'state' => 'to do'
];

$update = $shortcut->update('epics', $epic_id, $data);

Delete

Deletes an Epic

$epic_id = '3000';

$shortcut->delete('epics', $epic_id);

List

List Epics returns a list of all Epics and their attributes.

$epics = $shortcut->get('epics');

Create

Create Epic allows you to create a new Epic in Shortcut. See complete list of available fields.

$new_epic = [
    'deadline' => '2020-08-16T12:30:00Z',
    'name' => 'Terraforming of Mars',
    'description' => 'Should be easy. Couple of astropeople, a trowel each. Easy.'
];

$epic = $shortcut->create('epics', $new_epic);

Files

Get

Get File returns information about the selected File.

$file_id = '3000';

$file = $shortcut->get('files', $file_id);

Update

Update File can used to update the properties of a file uploaded to Shortcut. See complete list of available fields.

$file_id = "4351";

$data = [
    'description' => 'This file contains all of my most important passwords, in plain text.',
    'name' => 'Paswords.txt'
];

$update = $shortcut->update('files', $file_id, $data);

Delete

Delete File can be used to delete any previously attached File.

$file_id = '3000';

$shortcut->delete('files', $file_id);

List

List Files returns a list of all Files and related attributes in your Shortcut.

$files = $shortcut->get('files');

Labels

Create

Create Label allows you to create a new Label in Shortcut.

$new_label = [
    'external_id' => 'thirdparty-id-123',
    'name' => 'My New Label'
];

$label = $shortcut->create('labels', $new_label);

Update

Update Label allows you to replace a Label name with another name. If you try to name a Label something that already exists, you will receive a 422 response.

$label_id = "1234";

$data = [
    'name' => 'Updated Label Name'
];

$label = $shortcut->update('labels', $label_id, $data);

Delete

Delete Label can be used to delete any Label.

$label_id = '3000';

$shortcut->delete('labels', $label_id);

List

List Labels returns a list of all Labels and their attributes.

$labels = $shortcut->get('labels');

Linked-Files

Get

Get File returns information about the selected Linked File.

$link_id = 5000;

$linked_files = $shortcut->get('linked-files', $link_id);

Create

Create Linked File allows you to create a new Linked File in Shortcut. See complete list of available fields

$new_link = [
    'name' => 'My Linked File',
    'description' => 'Description of the file',
    'type' => 'dropbox',
    'url' => 'http://dropbox.com/1sjsSA9Q/asd20j.txt
];

$linked_file = $shortcut->create('linked-files', $new_link);

Update

Updated Linked File allows you to update properties of a previously attached Linked-File. See complete list of available fields

$link_id = "1234";

$data = [
    'name' => 'New name for linked file',
    'description' => 'Description of new linked file'
];

$linked_file = $shortcut->update('linked-files', $link_id, $data);

Delete

Delete Linked File can be used to delete any previously attached Linked-File.

$link_id = '3000';

$shortcut->delete('linked-files', $link_id);

List

List Linked Files returns a list of all Linked-Files and their attributes.

$linked_files = $shortcut->get('linked-files');

Projects

Get

Get Project returns information about the selected Project.

$project_id = '2990';

$project = $shortcut->get('projects', $project_id);

Create

Create Project is used to create a new Shortcut Project. See complete list of available fields

$new_project = [
    'name' => 'New Shortcut Project',
    'description' => 'Description of the project',
    'abbreviation' => 'ncp'
];

$project = $shortcut->create('projects', $new_project);

Update

Update Project can be used to change properties of a Project. See complete list of available fields

$project_id = 1234;

$data = [
    'name' => 'New name for project',
    'description' => 'Description update text'
];

$project = $shortcut->update('projects', $project_id, $data);

Delete

Delete Project can be used to delete a Project. Projects can only be deleted if all associated Stories are moved or deleted. In the case that the Project cannot be deleted, you will receive a 422 response.

$project_id = 3000;

$shortcut->delete('projects', $project_id);

List

List Projects returns a list of all Projects and their attributes.

$projects = $shortcut->get('projects');

Story-Links

Create

Story links allow you create semantic relationships between two stories. Relationship types are relates to, blocks / blocked by, and duplicates / is duplicated by. The format is subject -> link -> object, or for example “story 5 blocks story 6”. See complete list of available fields

$new_link = [
    'object_id' => 100,
    'subject_id' => 250,
    'verb' => 'blocks' //blocks, relates, duplicates
];

$story_links = $shortcut->create('story-links', $new_link);

Get

Returns information about the selected Story Link.

$storylink_id = 3000;

$story_links = $shortcut->get('story-links', $storylink_id);

Delete

Delete Story-Link can be used to delete any Story Link.

$storylink_id = 3000;

$shortcut->delete('story-links', $storylink_id);

Stories

Search

Warning Searching has changed in V3, and this library has not yet been fully updated, below is a hacky way you can search using this repo.

Search Stories lets you search Stories based on desired parameters. While all parameters are optional, you must include at least one parameter in order to receive a response.

See complete list of available search parameters

To search, for example, for all stories with a specific workflow state:

$query = "state:500005001";

$stories = $shortcut->get('search/stories?query='.$query);

Create

Create Story is used to add a new story to your Shortcut. See complete list of available fields

$new_story = [
    'name' => 'New story with some tasks',
    'project_id' => 6,
    'story_type' => 'feature', //feature, chore, bug
    'description' => 'Fuller descriptions make you more friends.',
    'tasks' => [
        ['description' => 'Task description 1'],
        ['description' => 'Task description 2']
    ]
];

$story = $shortcut->create('stories', $new_story);

Get

Get Story returns information about a chosen Story.

$story_id = 2000;

$story = $shortcut->get('stories', $story_id);

Update

Update Story can be used to change properties of a Story. See complete list of available fields

$story_id = 1234;

$data = [
    'epic_id' => 29,
    'description' => 'Description update text'
];

$story = $shortcut->update('stories', $story_id, $data);

Delete

Deletes a Story.

$story_id = 300';

$shortcut->delete('stories', $story_id);

Users

List

List Users returns information about users in the organization.

$users = $shortcut->get('users');

Get

Returns information about a User.

$user_id = '4JDaa9k-29d3-40s2-a4dc-a9bsd29sc';

$user = $shortcut->get('users', $user_id);

Workflows

List

List Workflows returns a list containing the single Workflow in the organization and its attributes.

$workflows = $shortcut->get('workflows');