Skip to content

Commit 5206b1e

Browse files
iaintshineiaintshine
committed
version 1.0.0 public release
1 parent 71a3aae commit 5206b1e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+3374
-0
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/vendor
2+
/composer.lock
3+
/docs

‎LICENSE

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Copyright (c) 2015 BaseCRM developers
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining
6+
a copy of this software and associated documentation files (the
7+
"Software"), to deal in the Software without restriction, including
8+
without limitation the rights to use, copy, modify, merge, publish,
9+
distribute, sublicense, and/or sell copies of the Software, and to
10+
permit persons to whom the Software is furnished to do so, subject to
11+
the following conditions:
12+
13+
The above copyright notice and this permission notice shall be
14+
included in all copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎Makefile

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.PHONY: docs dist
2+
3+
docs:
4+
phpdoc run -d lib/ -t docs
5+
6+
test:
7+
vendor/bin/phpunit
8+

‎README.md

+356
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
# basecrm-php
2+
3+
BaseCRM Official API V2 library client for PHP
4+
5+
## Installation
6+
7+
The recommended way to install the client is through
8+
[Composer](http://getcomposer.org).
9+
10+
```bash
11+
# Install Composer
12+
curl -sS https://getcomposer.org/installer | php
13+
```
14+
15+
Next, run the Composer command to install the latest stable version :
16+
17+
```bash
18+
composer require basecrm/basecrm-php
19+
```
20+
21+
After installing, you need to require Composer's autoloader:
22+
23+
```php
24+
require 'vendor/autoload.php';
25+
```
26+
27+
## Usage
28+
29+
```php
30+
require 'vendor/autoload.php';
31+
32+
// Then we instantiate a client (as shown below)
33+
```
34+
35+
### Build a client
36+
__Using this api without authentication gives an error__
37+
38+
```php
39+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
40+
```
41+
42+
### Client Options
43+
44+
The following options are available while instantiating a client:
45+
46+
* __accessToken__: Personal access token
47+
* __baseUrl__: Base url for the api
48+
* __userAgent__: Default user-agent for all requests
49+
* __timeout__: Request timeout
50+
* __verbose__: Verbose/debug mode
51+
52+
### Architecture
53+
54+
The library follows few architectural principles you should understand before digging deeper.
55+
1. Interactions with resources are done via service objects.
56+
2. Service objects are exposed as properties on client instances.
57+
3. Service objects expose resource-oriented actions.
58+
4. Actions return associative arrays.
59+
60+
For example, to interact with deals API you will use `\BaseCRM\DealsService`, which you can get if you call:
61+
62+
```php
63+
$client = new \BaseCRM\Client(['accessToken] => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
64+
$client->deals; // \BaseCRM\DealsService
65+
```
66+
67+
To retrieve list of resources and use filtering you will call `#all` method:
68+
69+
```php
70+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
71+
$client->deals->all('organization_id' => google['id'], 'hot' => true]);
72+
```
73+
74+
To find a resource by it's unique identifier use `#get` method:
75+
76+
```php
77+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
78+
$client->deals->get($id) # => array
79+
```
80+
81+
When you'd like to create a resource, or update it's attributes you want to use either `#create` or `#update` methods. For example if you want to create a new deal you will call:
82+
83+
```php
84+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
85+
$deal = $client->deals->create(['name' => 'Website redesign', 'contact_id' => $id]);
86+
```
87+
88+
To destroy a resource use `#destroy` method:
89+
90+
```php
91+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
92+
$client->deals->destroy($id) // => true
93+
```
94+
95+
There other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.
96+
97+
### Full example
98+
99+
Create a new organization and after that change it's attributes (website).
100+
101+
```php
102+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
103+
$lead = $client->leads->create(['organization_name' => 'Design service company']);
104+
105+
$lead['website'] = "http://www.designservices.com"
106+
$client->leads->update($lead['id'], $lead);
107+
```
108+
109+
### Error handling
110+
111+
When you instantiate a client or make any request via service objects, exceptions can be raised for multiple
112+
of reasons e.g. a network error, an authentication error, an invalid param error etc.
113+
114+
Sample below shows how to properly handle exceptions:
115+
116+
```php
117+
try
118+
{
119+
// Instantiate a client.
120+
$client = new \BaseCRM\Client(['accessToken' => getenv('BASECRM_ACCESS_TOKEN')]);
121+
$lead = $client->leads->create(['organization_name' => 'Design service company']);
122+
123+
print_r($lead);
124+
}
125+
catch (\BaseCRM\Errors\ConfigurationError $e)
126+
{
127+
// Invalid client configuration option
128+
}
129+
catch (\BaseCRM\Errors\ResourceError $e)
130+
{
131+
// Resource related error
132+
print('Http status = ' . $e->getHttpStatusCode() . "\n");
133+
print('Request ID = ' . $e->getRequestId() . "\n");
134+
foreach ($e->errors as $error)
135+
{
136+
print('field = ' . $error['field'] . "\n");
137+
print('code = ' . $error['code'] . "\n");
138+
print('message = ' . $error['message'] . "\n");
139+
print('details = ' . $error['details'] . "\n");
140+
}
141+
}
142+
catch (\BaseCRM\Errors\RequestError $e)
143+
{
144+
// Invalid query parameters, authentication error etc.
145+
}
146+
catch (\BaseCRM\Errors\Connectionerror $e)
147+
{
148+
// Network communication error, curl error is returned
149+
print('Errno = ' . $e->getErrno() . "\n");
150+
print('Error message = ' . $e->getErrorMessage() . "\n");
151+
}
152+
catch (Exception $e)
153+
{
154+
// Other kind of exception
155+
}
156+
```
157+
158+
## Resources and actions
159+
160+
Documentation for every action can be found in corresponding service files under `lib/` directory.
161+
162+
### Account
163+
164+
```php
165+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
166+
$client->accounts // => \BaseCRM\AccountsService
167+
```
168+
169+
Actions:
170+
* Retrieve account details - `client->accounts->self`
171+
172+
### AssociatedContact
173+
174+
```php
175+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
176+
$client->associatedContacts // => \BaseCRM\AssociatedContactsService
177+
```
178+
179+
Actions:
180+
* Retrieve deal's associated contacts - `client->associatedContacts->all`
181+
* Create an associated contact - `client->associatedContacts->create`
182+
* Remove an associated contact - `client->associatedContacts->destroy`
183+
184+
### Contact
185+
186+
```php
187+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
188+
$client->contacts // => \BaseCRM\ContactsService
189+
```
190+
191+
Actions:
192+
* Retrieve all contacts - `client->contacts->all`
193+
* Create a contact - `client->contacts->create`
194+
* Retrieve a single contact - `client->contacts->get`
195+
* Update a contact - `client->contacts->update`
196+
* Delete a contact - `client->contacts->destroy`
197+
198+
### Deal
199+
200+
```php
201+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
202+
$client->deals // => \BaseCRM\DealsService
203+
```
204+
205+
Actions:
206+
* Retrieve all deals - `client->deals->all`
207+
* Create a deal - `client->deals->create`
208+
* Retrieve a single deal - `client->deals->get`
209+
* Update a deal - `client->deals->update`
210+
* Delete a deal - `client->deals->destroy`
211+
212+
### Lead
213+
214+
```php
215+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
216+
$client->leads // => \BaseCRM\LeadsService
217+
```
218+
219+
Actions:
220+
* Retrieve all leads - `client->leads->all`
221+
* Create a lead - `client->leads->create`
222+
* Retrieve a single lead - `client->leads->get`
223+
* Update a lead - `client->leads->update`
224+
* Delete a lead - `client->leads->destroy`
225+
226+
### LossReason
227+
228+
```php
229+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
230+
$client->lossReasons // => \BaseCRM\LossReasonsService
231+
```
232+
233+
Actions:
234+
* Retrieve all reasons - `client->lossReasons->all`
235+
* Create a loss reason - `client->lossReasons->create`
236+
* Retrieve a single reason - `client->lossReasons->get`
237+
* Update a loss reason - `client->lossReasons->update`
238+
* Delete a reason - `client->lossReasons->destroy`
239+
240+
### Note
241+
242+
```php
243+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
244+
$client->notes // => \BaseCRM\NotesService
245+
```
246+
247+
Actions:
248+
* Retrieve all notes - `client->notes->all`
249+
* Create a note - `client->notes->create`
250+
* Retrieve a single note - `client->notes->get`
251+
* Update a note - `client->notes->update`
252+
* Delete a note - `client->notes->destroy`
253+
254+
### Pipeline
255+
256+
```php
257+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
258+
$client->pipelines // => \BaseCRM\PipelinesService
259+
```
260+
261+
Actions:
262+
* Retrieve all pipelines - `client->pipelines->all`
263+
264+
### Source
265+
266+
```php
267+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
268+
$client->sources // => \BaseCRM\SourcesService
269+
```
270+
271+
Actions:
272+
* Retrieve all sources - `client->sources->all`
273+
* Create a source - `client->sources->create`
274+
* Retrieve a single source - `client->sources->get`
275+
* Update a source - `client->sources->update`
276+
* Delete a source - `client->sources->destroy`
277+
278+
### Stage
279+
280+
```php
281+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
282+
$client->stages // => \BaseCRM\StagesService
283+
```
284+
285+
Actions:
286+
* Retrieve all stages - `client->stages->all`
287+
288+
### Tag
289+
290+
```php
291+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
292+
$client->tags // => \BaseCRM\TagsService
293+
```
294+
295+
Actions:
296+
* Retrieve all tags - `client->tags->all`
297+
* Create a tag - `client->tags->create`
298+
* Retrieve a single tag - `client->tags->get`
299+
* Update a tag - `client->tags->update`
300+
* Delete a tag - `client->tags->destroy`
301+
302+
### Task
303+
304+
```php
305+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
306+
$client->tasks // => \BaseCRM\TasksService
307+
```
308+
309+
Actions:
310+
* Retrieve all tasks - `client->tasks->all`
311+
* Create a task - `client->tasks->create`
312+
* Retrieve a single task - `client->tasks->get`
313+
* Update a task - `client->tasks->update`
314+
* Delete a task - `client->tasks->destroy`
315+
316+
### User
317+
318+
```php
319+
$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
320+
$client->users // => \BaseCRM\UsersService
321+
```
322+
323+
Actions:
324+
* Retrieve all users - `client->users->all`
325+
* Retrieve a single user - `client->users->get`
326+
* Retrieve an authenticating user - `client->users->self`
327+
328+
329+
## Tests
330+
331+
Install PHPUnit via Composer:
332+
333+
```bash
334+
$ composer install
335+
```
336+
337+
To run all test suites:
338+
339+
```bash
340+
$ ./vendor/bin/phpunit
341+
```
342+
343+
And to run a single suite:
344+
345+
```bash
346+
$ ./vendor/bin/phpunit --filter testUpdate tests/LeadsServiceTest.php
347+
```
348+
349+
## License
350+
MIT
351+
352+
## Bug Reports
353+
Report [here](https://github.com/basecrm/basecrm-php/issues).
354+
355+
## Contact
356+
BaseCRM developers ([email protected])

0 commit comments

Comments
 (0)