Skip to content

Latest commit

 

History

History
290 lines (203 loc) · 9.93 KB

README.md

File metadata and controls

290 lines (203 loc) · 9.93 KB
Raw

Complete Pipedrive API client for PHP

Build Status

Consider donating

Do you like this package? Did you find it useful? Donate and support its development.

Donate

This package provides a complete framework agnostic Pipedrive CRM API client library for PHP. It includes all the resources listed at Pipedrive's documentation.

Feel free to drop me a message at israel@devio.es or tweet me at @IsraelOrtuno.

$token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx';
$pipedrive = new Pipedrive($token);

// Easily access a Pipedrive resource and its values
$organization = $pipedrive->organizations->find(1);
var_dump($organization->getData());

// Also simple to update any Pipedrive resource value
$organization = $pipedrive->organizations->update(1, ['name' => 'Big Code']);
var_dump($organization->getData());

// Keep reading this documentation to find out more.

For a deeper knowledge of how to use this package, follow this index:

Installation

You can install the package via composer require command:

composer require devio/pipedrive

Or simply add it to your composer.json dependences and run composer update:

"require": {
    "devio/pipedrive": "1.0.*"
}

Usage

Create the Pipedrive instance

Devio\Pipedrive\Pipedrive class acts as Manager and will be responsible of resolving the different API resources available. First of all we need to create an instance of this class with our Pipedrive API Token:

$token = 'PipedriveTokenHere';

$pipedrive = new Pipedrive($token);

NOTE: Consider storing this object into a global variable.

Resolve a Pipedrive API Resource

Once we have our Pipedrive instance, we are able to resolve any Pipedrive API Resource in many ways.

First you could do it calling the make() method:

// Organizations
$organizations = $pipedrive->make('organizations');
// Persons
$organizations = $pipedrive->make('persons');
// ...

It also intercepts the magic method __get so we could do:

// Deals
$organizations = $pipedrive->deals;
// Activities
$organizations = $pipedrive->activities;
// ...

And just in case you preffer __call, you can use it too:

// EmailMessages
$organizations = $pipedrive->emailMessages();
// GlobalMessages
$organizations = $pipedrive->globalMessages();
// ...

They are 3 different ways of doing the same thing, pick the one you like the most. It will automatically set the studly case version of the asked resource, so it will work with emailMessages, EmailMessages, email_messages...

IMPORTANT: Navigate to the src/Resources directory to find out all the resources available.

Performing a resource call

Available methods

All resources have various methods for performing the different API requests. Please, navigate to the resource class you would like to work with to find out all the methods available. Every method is documented and can also be found at Pipedrive API Docs page.

Every resource extends from Devio\Pipedrive\Resources\Basics\Resource where the most common methods are defined. Some of them are disabled for the resources that do not inlcude them. Do not forget to check out the Traits included and some resources use, they define some other common calls to avoid code duplication.

Performing the Request

After resolved the resource we want to use, we are able to perform an API request. At this point, we only have to execute the endpoint we would like to access:

$organizations = $pipedrive->organizations->all();
//
$pipedrive->persons->update(1, ['name' => 'Israel Ortuno']);

Any of these methods will perform a synchronous request to the Pipedrive API.

Handling the response

Every Pipedrive API endpoint gives a response and this response is converted to a Devio\Pipedrive\Http\Response object to handle it:

$response = $pipedrive->organizations->all();

$organizations = $response->getData();

Response methods

The Response class has many methods available for accessing the response data:

isSuccess()

Check if the server responded the request was successful.

getContent()

Will provide the raw response provided by the Pipedrive API. Useful if you need specific control.

getData()

Get the response main data object which will include the information about the endpoint we are calling.

getAdditionalData()

Some responses include an additional data object with some extra information. Fetch this object with this method.

getStatusCode()

Get the response status code.

getHeaders()

Get the response headers.

Available resources

Every Resource logic is located at the src/Resources directory. However we'll mention every included resource here:

Resource Methods implemented Notes
Activities ✅ 6/6
ActivityTypes ✅ 5/5
Currencies ✅ 1/1
DealFields ✅ 25/25
Deals ✅ 6/6
EmailMessages ✅ 4/4
EmailThreads ✅ 6/6
Files ✅ 8/8
Filters ✅ 6/6
GlobalMessages ✅ 2/2
Goals ⚠️ 5/6 Missing goal results method
Notes ✅ 5/5
OrganizationFields ✅ 6/6
OrganizationRelationships ✅ 5/5
Organizations ✅ 18/18
PermissionsSets ✅ 6/6
PersonFields ✅ 18/20
Persons ⚠️ 18/20 Missing add and delete pictures as getting required fields error.
Pipelines ⚠️ 6/8 Missing deals conversion rates and deals movements
ProductFields ✅ 6/6
Products ✅ 9/9
PushNotifications ✅ 4/4
Recents ✅ 1/1
Roles ⚠️ 0/11 Getting unathorized access
SearchResults ✅ 2/2
Stages ✅ 7/7
UserConnections ✅ 1/1
Users ⚠️ 13/20 Getting unathorized access when playing with roles and permissions
UserSettings ✅ 1/1

✅ Completed / ⚠️ Pipedrive API errors

The File Resource

The File resource is the only one that works a little bit different than others. While other resources may be intuitively used as most of them just require a plain array of tada, the File resource requires an \SplFileInfo instance to make it work:

$file = new \SplFileInfo('document.pdf');

$pipedrive->files->add([
    'file'   => $file,
    'person_id' => 1,
    // 'deal_id' => 1
]);

Actually it is pretty simple, just pass a \SplFileInfo instance to the file key of the options array and specify at least one of the elements it goes related to (deal, person, ...).

Configure and use in Laravel

If you are using Laravel, you could make use of the PipedriveServiceProvider and PipedriveFacade which will make the using of this package much more comfortable:

Service Provider and Facade

Include the PipedriveServiceProvider to the providers array in config/app.php and register the Laravel Facade.

'providers' => [
  ...
  Devio\Pipedrive\PipedriveServiceProvider::class,
  ...
],
'alias' => [
    ...
    'Pipedrive' => Devio\Pipedrive\PipedriveFacade::class,
    ...
]

The service configuration

Laravel includes a configuration file for storing external services information at config/services.php. We have to set up our Pipedrive token at that file like this:

'pipedrive' => [
    'token' => 'the pipedrive token'
]

Of course, as many other config parameters, you could store the token at your .env file or environment variable and fetch it using dotenv:

'pipedrive' => [
    'token' => env('PIPEDRIVE_TOKEN')
]

Using it

You could use it using the Laravel facade PipedriveFacade that we have previously loaded:

$organizations = Pipedrive::organizations()->all();
//
Pipedrive::persons()->add(['name' => 'John Doe']);

Also, resolve it out of the service container:

$pipedrive = app()->make('pipedrive');

Or even inject it wherever you may need using the Devio\Pipedrive\Pipedrive signature.

Contribute

Feel free to contribute via PR.