netvlies / basecamp-php
The Basecamp API makes it easy for developers to communicate with the 37signals Basecamp platform
Installs: 5 193
Dependents: 1
Suggesters: 0
Security: 0
Stars: 37
Watchers: 15
Forks: 31
Open Issues: 8
Requires
- guzzle/guzzle: ~3.3
Requires (Dev)
- phpunit/phpunit: 3.7.*
This package is not auto-updated.
Last update: 2024-11-09 16:00:47 UTC
README
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
<?php $client = \Basecamp\BasecampClient::factory(array( 'auth' => 'http', 'username' => 'you@email.com', '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:
<?php $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:
<?php 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
$response = $client->getArchivedProjects();
Get active Projects
$response = $client->getProjects();
Get a Project
$response = $client->getProject( array( 'id' => 1234567, // Required. Project ID ) );
Get all Documents
$response = $client->getDocumentsByProject( array( 'projectId' => 1234567, // Required. Project ID ) );
Get a Document
$response = $client->getDocument( array( 'projectId' => 1234567, // Required. Project ID 'documentId' => 1234567, // Required. Document ID ) );
Get Topics
$response = $client->getTopicsByProject( array( 'projectId' => 1234567, // Required. Project ID ) );
Get Todo Lists
$response = $client->getTodolistsByProject( array( 'projectId' => 1234567, // Required. Project ID ) );
Get Todo Lists assigned to a Person
$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
$response = $client->getCompletedTodolistsByProject( array( 'projectId' => 1234567, // Required. Project id ) );
Get completed Todos
$response = $client->getCompletedTodosByProject( array( 'projectId' => 1234567, // Required. Project id ) );
Create a new project
$response = $client->createProject( array( 'name' => 'Example name', // Required. 'description' => 'Example description', // Required. ) );
Create a new document
$response = $client->createDocument( array( 'projectId' => 1234567, // Required. Project ID 'title' => 'example', // Required. 'content' => 'Example content', // Required. ) );
Create Todo List
$response = $client->createTodolistByProject( array( 'projectId' => 1234567, // Required. Project id 'name' => 'Example name', // Required. 'description' => 'Example description', // Required. ) );
Create Todo
$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
$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
$response = $client->getAttachmentsByProject( array( 'projectId' => 1234567, // Required. Project id ) );
Create Attachment
$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
$response = $client->getTodolist( array( 'projectId' => 1234567, // Required. Project id 'todolistId' => 1234567, // Required. Todolist id ) );
Get Todo
$response = $client->getTodo( array( 'projectId' => 1234567, // Required. Project id 'todoId' => 1234567, // Required. Todo id ) );
Update Todo
$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
$response = $client->getCurrentUser();
Get specific User
$response = $client->getSpecificUser( array( 'personId' => 1234567, // Required. Person id ) );
Get global 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
$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
$response = $client->getAccessesByProject( array( 'projectId' => 1234567, // Required. Project id ) );
Get Accesses to Calendar
$response = $client->getAccessesByCalendar( array( 'calendarId' => 1234567, // Required. Calendar id ) );
Get all People
$response = $client->getPeople();
Get all Groups
$response = $client->getGroups();
Grant 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
$response = $client->getCalendars();
Get single Calendar
$response = $client->getCalendar( array( 'calendarId' => 1234567, // Required. Calendar id ) );
Create new Calendar
$response = $client->createCalendar( array( 'name' => 'Example name', // Required. ) );
Update Calendar
$response = $client->updateCalendar( array( 'calendarId' => 1234567, // Required. Calendar id 'name' => 'Example name', // Required. ) );
Delete Calendar
$response = $client->deleteCalendar( array( 'calendarId' => 1234567, // Required. Calendar id ) );
Get all 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
$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
$response = $client->getCalendarEventsPast( array( 'calendarId' => 1234567, // Required. Calendar id ) );
Get single calendar event
$response = $client->getCalendarEvent( array( 'calendarId' => 1234567, // Required. Calendar id 'eventId' => 1234567, // Required. Event id ) );
Create calendar event
$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
$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
$response = $client->deleteCalendarEvent( array( 'calendarId' => 1234567, // Required. Calendar id 'eventId' => 1234567, // Required. Event id ) );
Get upcoming project 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
$response = $client->getProjectCalendarEventsPast( array( 'projectId' => 1234567, // Required. Project ID ) );
Get single project calendar event
$response = $client->getProjectCalendarEvent( array( 'projectId' => 1234567, // Required. Project id 'eventId' => 1234567, // Required. Event id ) );
Create project calendar event
$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
$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
$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