Basecamp SDK for PHP

The Basecamp SDK for PHP enables PHP developers to easily integrate 37signals Basecamp all new API into their applications.

NOTE: This library is under heavy development and a lot of calls haven't been implemented yet. We're looking forward to any of your PR's.

Installation

We recommend Composer for managing dependencies. Installing is as easy as:

$ php composer.phar require netvlies/basecamp-php

Usage

To use the library the only requirement is you have a account. Upon creating the client you have to pass your credentials or an OAuth token. Furthermore you need your userId to construct the URI's.

Authorization with username and password



$client = \Basecamp\BasecampClient::factory(array(
    'auth' => 'http',
    'username' => '[email protected]',
    'password' => 'secret',
    'user_id' => 99999999,
    'app_name' => 'My Wicked Application',
    'app_contact' => 'http://mywickedapplication.com'
));

Authorization with OAuth token

This library doesn't handle the OAuth authorization process for you. There are already a lot of libraries out there which handle this process perfectly for you. When you recieved your token you'll have to pass it on to the client:



$client = \Basecamp\BasecampClient::factory(array(
    'auth'     => 'oauth',
    'token'    => 'Wtj4htewhtuewhuoitewh',
    'user_id'   => 99999999,
    'app_name' => 'My Wicked Application',
    'app_contact' => 'http://mywickedapplication.com'
));

Identification

It is required to identify you application. This can be accomplished by using app_name and app_contact.

About this API client

This client is build upon the shoulders of the impressive Guzzle library. If you're willing to contribute to this client, make sure to check out the docs.

Caching

It is required to implement caching in your application. Lucky for you, using Guzzle this is peanuts! Please refer to the official docs for more information.

Here's a quick example using the Doctrine cache:



use Basecamp\BasecampClient;
use Doctrine\Common\Cache\FilesystemCache;
use Guzzle\Cache\DoctrineCacheAdapter;
use Guzzle\Plugin\Cache\CachePlugin;

$cachePlugin = new CachePlugin(array(
    'adapter' => new DoctrineCacheAdapter(new FilesystemCache(__DIR__.'/../../../../app/cache/basecamp'))
));

$this->client = BasecampClient::factory(array(
    // config options
));
$this->client->addSubscriber($cachePlugin);

API calls

All services are documented below. View full service description in src/Basecamp/Resources/service.php

Get archived Projects

Basecamp API: Projects

$response = $client->getArchivedProjects();

Get active Projects

Basecamp API: Projects

$response = $client->getProjects();

Get a Project

Basecamp API: Projects

$response = $client->getProject( array( 
    'id' => 1234567,  // Required. Project ID 
) );

Get all Documents

Basecamp API: Documents

$response = $client->getDocumentsByProject( array( 
    'projectId' => 1234567,  // Required. Project ID 
) );

Get a Document

Basecamp API: Documents

$response = $client->getDocument( array( 
    'projectId' => 1234567,  // Required. Project ID 
    'documentId' => 1234567,  // Required. Document ID 
) );

Get Topics

Basecamp API: Topics

$response = $client->getTopicsByProject( array( 
    'projectId' => 1234567,  // Required. Project ID 
) );

Get Todo Lists

Basecamp API: Todo lists

$response = $client->getTodolistsByProject( array( 
    'projectId' => 1234567,  // Required. Project ID 
) );

Get Todo Lists assigned to a Person

Basecamp API: Todo lists

$response = $client->getAssignedTodolistsByPerson( array( 
    'personId' => 1234567,  // Required. Person id 
    'page' => 1234567,  // Optional. The page to retrieve. API returns 50 todos per page. 
    'due_since' => 'example',  // Optional. Will return all the to-do lists with to-dos assigned to the specified person due after the date specified. (format: 2012-03-24T11:00:00-06:00) 
) );

Get completed Todo Lists

Basecamp API: Todo lists

$response = $client->getCompletedTodolistsByProject( array( 
    'projectId' => 1234567,  // Required. Project id 
) );

Get completed Todos

Basecamp API: Todos

$response = $client->getCompletedTodosByProject( array( 
    'projectId' => 1234567,  // Required. Project id 
) );

Create a new project

Basecamp API: Projects

$response = $client->createProject( array( 
    'name' => 'Example name',  // Required.  
    'description' => 'Example description',  // Required.  
) );

Create a new document

Basecamp API: Documents

$response = $client->createDocument( array( 
    'projectId' => 1234567,  // Required. Project ID 
    'title' => 'example',  // Required.  
    'content' => 'Example content',  // Required.  
) );

Create Todo List

Basecamp API: Todo lists

$response = $client->createTodolistByProject( array( 
    'projectId' => 1234567,  // Required. Project id 
    'name' => 'Example name',  // Required.  
    'description' => 'Example description',  // Required.  
) );

Create Todo

Basecamp API: Todos

$response = $client->createTodoByTodolist( array( 
    'projectId' => 1234567,  // Required. Project id 
    'todolistId' => 1234567,  // Required. Todo list id 
    'content' => 'Example content',  // Required.  
    'assignee' => array( 'id' => 1234567, 'type' => 'Person' ),  // Optional.  
) );

Create Comment on Todo

Basecamp API: Comments

$response = $client->createCommentByTodo( array( 
    'projectId' => 1234567,  // Required. Project id 
    'todoId' => 1234567,  // Required. Todo id 
    'content' => 'Example content',  // Required.  
    'attachments' => array( array( 'token' => $upload_token, 'name' => 'file.jpg' ) ),  // Optional.  
) );

Get Attachments

Basecamp API: Attachments

$response = $client->getAttachmentsByProject( array( 
    'projectId' => 1234567,  // Required. Project id 
) );

Create Attachment

Basecamp API: Attachments

$response = $client->createAttachment( array( 
    'mimeType' => 'image/jpeg',  // Required. The content type of the data 
    'data' => file_get_contents( 'image.jpg' ),  // Required. The attachment's binary data 
) );

Get Todo List

Basecamp API: Todo lists

$response = $client->getTodolist( array( 
    'projectId' => 1234567,  // Required. Project id 
    'todolistId' => 1234567,  // Required. Todolist id 
) );

Get Todo

Basecamp API: Todos

$response = $client->getTodo( array( 
    'projectId' => 1234567,  // Required. Project id 
    'todoId' => 1234567,  // Required. Todo id 
) );

Update Todo

Basecamp API: Todos

$response = $client->updateTodo( array( 
    'projectId' => 1234567,  // Required. Project id 
    'todoId' => 1234567,  // Required. Todo id 
    'content' => 'Example content',  // Optional.  
    'due_at' => 'example',  // Optional.  
    'assignee' => array( 'id' => 1234567, 'type' => 'Person' ),  // Optional.  
    'completed' => 'example',  // Optional.  
) );

Get current User

Basecamp API: People

$response = $client->getCurrentUser();

Get specific User

Basecamp API: People

$response = $client->getSpecificUser( array( 
    'personId' => 1234567,  // Required. Person id 
) );

Get global Events

Basecamp API: Events

$response = $client->getGlobalEvents( array( 
    'since' => '2012-03-24T11:00:00-06:00',  // Optional. All events since given datetime (format: 2012-03-24T11:00:00-06:00) 
    'page' => 1234567,  // Optional. The page to retrieve. API returns 50 events per page. 
) );

Get Project Events

Basecamp API: Events

$response = $client->getProjectEvents( array( 
    'projectId' => 1234567,  // Required. Project id 
    'since' => '2012-03-24T11:00:00-06:00',  // Optional. All events since given datetime (format: 2012-03-24T11:00:00-06:00) 
) );

Get Accesses to Project

Basecamp API: Accesses

$response = $client->getAccessesByProject( array( 
    'projectId' => 1234567,  // Required. Project id 
) );

Get Accesses to Calendar

Basecamp API: Accesses

$response = $client->getAccessesByCalendar( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
) );

Get all People

Basecamp API: People

$response = $client->getPeople();

Get all Groups

Basecamp API: People

$response = $client->getGroups();

Grant access

Basecamp API: Access

$response = $client->grantAccess( array( 
    'projectId' => 1234567,  // Required. Project id 
    'ids' => '',  // Required. Existing user ids 
    'email_addresses' => 'example',  // Optional. Grant access to new users 
) );

Get all Calendars

Basecamp API: Calendars

$response = $client->getCalendars();

Get single Calendar

Basecamp API: Calendars

$response = $client->getCalendar( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
) );

Create new Calendar

Basecamp API: Calendars

$response = $client->createCalendar( array( 
    'name' => 'Example name',  // Required.  
) );

Update Calendar

Basecamp API: Calendars

$response = $client->updateCalendar( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
    'name' => 'Example name',  // Required.  
) );

Delete Calendar

Basecamp API: Calendars

$response = $client->deleteCalendar( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
) );

Get all events

Basecamp API: Calendar Events

$response = $client->getAllCalendarEvents( array( 
    'start_date' => 'example',  // Optional. Will return 6 weeks worth of events after the start date if the end date is not supplied (format: 2015-09-15) 
    'end_date' => 'example',  // Optional. Will return 6 weeks worth of events after the start date if the end date is not supplied (format: 2015-09-15) 
) );

Get upcoming calendar events

Basecamp API: Calendar Events

$response = $client->getCalendarEvents( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
    'start_date' => 'example',  // Optional. Will return 6 weeks worth of events after the start date if the end date is not supplied (format: 2015-09-15) 
    'end_date' => 'example',  // Optional. Will return 6 weeks worth of events after the start date if the end date is not supplied (format: 2015-09-15) 
) );

Get past calendar events

Basecamp API: Calendar Events

$response = $client->getCalendarEventsPast( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
) );

Get single calendar event

Basecamp API: Calendar Events

$response = $client->getCalendarEvent( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
    'eventId' => 1234567,  // Required. Event id 
) );

Create calendar event

Basecamp API: Calendar Events

$response = $client->createCalendarEvent( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
    'summary' => 'example',  // Required. Event Summary / title 
    'description' => 'Example description',  // Optional. Event Description 
    'starts_at' => 'example',  // Required. Date (and time if not an all day event) that the event starts at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'ends_at' => 'example',  // Optional. Date (and time if not an all day event) that the event ends at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'remind_at' => 'example',  // Optional. Datetime to remind subscribers about the event via email (format: 2015-09-15T11:50:00-05:00) 
    'subscribers' => '',  // Optional. Array of user id's to subscribe to the event. 
    'recurring' => '',  // Optional. Array of recurring parrameters - starts_at, frequency, count, until, excluding 
    'all_day' => '',  // Optional. Is the event a full day event? 
) );

Update a calendar event

Basecamp API: Calendar Events

$response = $client->updateCalendarEvent( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
    'eventId' => 1234567,  // Required. Event id 
    'summary' => 'example',  // Optional. Event Summary / title 
    'description' => 'Example description',  // Optional. Event Description 
    'starts_at' => 'example',  // Optional. Date (and time if not an all day event) that the event starts at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'ends_at' => 'example',  // Optional. Date (and time if not an all day event) that the event ends at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'remind_at' => 'example',  // Optional. Datetime to remind subscribers about the event via email (format: 2015-09-15T11:50:00-05:00) 
    'subscribers' => '',  // Optional. Array of user id's to subscribe to the event. 
    'recurring' => '',  // Optional. Array of recurring parrameters - starts_at, frequency, count, until, excluding 
    'all_day' => '',  // Optional. Is the event a full day event? 
) );

Delete a calendar event

Basecamp API: Calendar Events

$response = $client->deleteCalendarEvent( array( 
    'calendarId' => 1234567,  // Required. Calendar id 
    'eventId' => 1234567,  // Required. Event id 
) );

Get upcoming project calendar events

Basecamp API: Calendar Events

$response = $client->getProjectCalendarEvents( array( 
    'projectId' => 1234567,  // Required. Project ID 
    'start_date' => 'example',  // Optional. Will return 6 weeks worth of events after the start date if the end date is not supplied (format: 2015-09-15) 
    'end_date' => 'example',  // Optional. Will return 6 weeks worth of events after the start date if the end date is not supplied (format: 2015-09-15) 
) );

Get past project calendar events

Basecamp API: Calendar Events

$response = $client->getProjectCalendarEventsPast( array( 
    'projectId' => 1234567,  // Required. Project ID 
) );

Get single project calendar event

Basecamp API: Calendar Events

$response = $client->getProjectCalendarEvent( array( 
    'projectId' => 1234567,  // Required. Project id 
    'eventId' => 1234567,  // Required. Event id 
) );

Create project calendar event

Basecamp API: Calendar Events

$response = $client->createProjectCalendarEvent( array( 
    'projectId' => 1234567,  // Required. Project id 
    'summary' => 'example',  // Required. Event Summary / title 
    'description' => 'Example description',  // Optional. Event Description 
    'starts_at' => 'example',  // Required. Date (and time if not an all day event) that the event starts at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'ends_at' => 'example',  // Optional. Date (and time if not an all day event) that the event ends at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'remind_at' => 'example',  // Optional. Datetime to remind subscribers about the event via email (format: 2015-09-15T11:50:00-05:00) 
    'subscribers' => '',  // Optional. Array of user id's to subscribe to the event. 
    'recurring' => '',  // Optional. Array of recurring parrameters - starts_at, frequency, count, until, excluding 
    'all_day' => '',  // Optional. Is the event a full day event? 
) );

Update a project calendar event

Basecamp API: Calendar Events

$response = $client->updateProjectCalendarEvent( array( 
    'projectId' => 1234567,  // Required. Project id 
    'eventId' => 1234567,  // Required. Event id 
    'summary' => 'example',  // Optional. Event Summary / title 
    'description' => 'Example description',  // Optional. Event Description 
    'starts_at' => 'example',  // Optional. Date (and time if not an all day event) that the event starts at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'ends_at' => 'example',  // Optional. Date (and time if not an all day event) that the event ends at (format: 2015-09-15 or 2015-09-15T11:50:00-05:00) 
    'remind_at' => 'example',  // Optional. Datetime to remind subscribers about the event via email (format: 2015-09-15T11:50:00-05:00) 
    'subscribers' => '',  // Optional. Array of user id's to subscribe to the event. 
    'recurring' => '',  // Optional. Array of recurring parrameters - starts_at, frequency, count, until, excluding 
    'all_day' => '',  // Optional. Is the event a full day event? 
) );

Delete a project calendar event

Basecamp API: Calendar Events

$response = $client->deleteProjectCalendarEvent( array( 
    'projectId' => 1234567,  // Required. Project id 
    'eventId' => 1234567,  // Required. Event id 
) );

Unit Test Coverage

The following service operations are not (yet) covered by unit tests:

updateTodo
grantAccess
updateCalendar
deleteCalendar
updateCalendarEvent
deleteCalendarEvent
updateProjectCalendarEvent
deleteProjectCalendarEvent

Adds getSpecificUser and tests to cover getSpecificUser and getCurrentUser

Doing some work with users, didn't have a call for a specific user, so have added that.

Also noticed there wasn't a test covering getCurrentUser, so added that at the same time.

opened by nickedwards 3
Added support for new calls
Added support for three new calls:

Add project

Add document

Grant access

I've also added tests for the new calls and updated the documentation to reflect the changes.
opened by mrberggg 3
Adds missing unit test coverage section to README

After my previous PR I noticed that testGetCurrentPerson is a duplicate test of testGetCurrentUser, so have removed that.

I've also added a test to cover the only untested line of code (code coverage is now showing 100%).

However, code coverage being at 100% doesn't represent that every service operation has been unit tested, so I've also added a quick summary to the README which tells you which service operation that hasn't been covered by a unit test.

Obviously the ideal situation is that we write unit tests to cover these services, but I figure this at least makes it visible which ones still need written.

Let me know what you think

opened by nickedwards 1
Add calendar service calls

I've been doing some work with basecamp calendars recently, and found this sdk pretty useful (so thanks!).

Here's the work I've added for calendar endpoints, and project calendar endpoints. There is quite a lot, but I figured it'd be better implementing the full calendar scope into this while I was at it.

Also added tests and updated the README documentation file.

opened by nickedwards 1
getGlobalEvents displays only logged in user

Trying to use getGlobalEvents API but it's returning just my events, not any activity of other members working on the projects. Is there a way to display all activity? Thanks.

opened by alexlavr 1
Add API documentation. Add script for generating API docs from service.php
Add summaries and descriptions to service.php

Add script generate-api-docs.php, which will update API docs between markers based on the code in service.php.

Run generate-api-docs.php with php -f generate-api-docs.php

Include example PHP values for each type of parameter in generate-api-docs.php.

Add links to relevant Basecamp API documentation in service.php. Include these when generating section in readme.

Add link to service.php file in readme.

Change $service in readme authorization example to $client to be consistent with API examples.

Sorry, this PR includes the two commits from #20.
opened by pdclark 1
Replace double-quotes with single-quotes in service.php

PHP parses double-quotes for variables, adding a slight overhead to string processing. When variables are not present, single-quotes should be prefered

opened by pdclark 1
API additions
Adding the following API calls, tests included:

getCompletedTodolistsByProject

getAllTodolistsByProject

createTodolistByProject

createTodoByTodolist

createCommentByTodo

createAttachment
opened by rjkip 1
Config defaults had auth_method key which was never used

Changed the default key to auth and removed it from the $required array. Also updated the unit test to test for an invalid auth rather than no auth, since one will always be set.

opened by tplaner 0
Can't run unit tests

I'm 100% certain it's me doing something wrong but I can't figure out what it is.

Using PHPUnit 6.5.6, I can get any of the tests to run. I always get a No tests executed message.

Can you offer any guidance on how to properly run the tests?

opened by markbiek 0

Missing get project(s) a person has access to.

Added this to my service.php file to get a person's projects.

    'getPersonsProjects' => array(
        'httpMethod' => 'GET',
        'uri'       => 'people/{personId}/projects.json',
        'summary'   => 'Get projects a person has access to.' . PHP_EOL . '[Basecamp API: People](https://github.com/basecamp/bcx-api/blob/master/sections/people.md)',
        'parameters' => array(
            'personId' => array(
                'location' => 'uri',
                'description' => 'Person ID',
                'type' => 'integer',
                'required' => true,
            )
        )
    ),

opened by Jameron 1

Updtae createTodoByTodolist?

Hello Markri,

in the basecamp api you can add a date and assign a person to a todo list. Maybe you can update your service with that feature?

'createTodoByTodolist' => array(
            'httpMethod' => 'POST',
            'uri' => 'projects/{projectId}/todolists/{todolistId}/todos.json',
            'parameters' => array(
                'projectId' => array(
                    'location' => 'uri',
                    'description' => 'Project id',
                    'required' => true
                ),
                'todolistId' => array(
                    'location' => 'uri',
                    'description' => 'Todo list id',
                    'required' => true
                ),
                "content" => array(
                    "location" => "json",
                    "type" => "string",
                    'required' => true,
                ),               
                "due_at" => array(
                    "location" => "json",
                    "type" => "string",
                    'required' => false,
                ),
                "assignee" => array(
                    "location" => "json",
                    "type" => "array",
                    'required' => false,
                )
            )
        ),

opened by cms09 3