sergeybruhin/nano-crm-client

Plain PHP API client for nano-crm-api

v0.0.1 2026-05-26 11:41 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

README

Plain PHP HTTP client for nano-crm-api — a self-hosted lead and contact management service.

Requirements

• PHP 8.3+
• Guzzle 7.x

Installation

composer require sergeybruhin/nano-crm-client

Quick start

use NanoCrm\Client\NanoCrmClient;
use NanoCrm\Client\Dto\CreateLeadInput;

$client = NanoCrmClient::create(
    baseUrl: 'http://nano-crm-api',
    token:   'your-service-token',
    timeout: 10,
);

$lead = $client->leads()->create(new CreateLeadInput(
    contact: ['full_name' => 'Ivan Petrov', 'phone' => '[phone]'],
    source:  'example.com',
    type:    'callback',
));

echo $lead->uuid;

The client appends /api/v1/ to baseUrl and attaches Authorization: Bearer {token} on every request.

Leads

All lead methods are accessible via $client->leads() and return LeadDto instances.

$leads = $client->leads();

// Create
$lead = $leads->create(new CreateLeadInput(
    contact: ['full_name' => 'Ivan Petrov', 'phone' => '[phone]'],
    source:  'example.com',
    type:    'callback',
    form:    ['page' => '/contacts'],   // optional
    utm:     ['utm_source' => 'google'], // optional
    meta:    ['ip' => '1.2.3.4'],       // optional
    formKey: 'callback-v2',             // optional
    isTest:  false,
    sentAt:  new DateTimeImmutable(),   // optional
));

// Find
$lead = $leads->find('019602a0-0000-7000-8000-000000000001');

// Update
$lead = $leads->update($lead->uuid, new UpdateLeadInput(source: 'acme.example.com'));

// Delete (soft)
$leads->delete($lead->uuid);

Contacts

All contact methods are accessible via $client->contacts() and return ContactDto instances.

$contacts = $client->contacts();

// Create
$contact = $contacts->create(new CreateContactInput(
    fullName:           'Ivan Petrov',
    primaryPhoneNumber: '[phone]',
    primaryEmail:       '[e-mail]', // optional
));

// Find
$contact = $contacts->find('019602a0-0000-7000-8000-000000000002');

// Update
$contact = $contacts->update($contact->uuid, new UpdateContactInput(
    primaryEmail: '[e-mail]',
));

// Delete (soft)
$contacts->delete($contact->uuid);

DTOs

CreateLeadInput

Property	Type	Required
contact	array{full_name: string, phone: string}	Yes
source	string	Yes
type	string	Yes
form	array|null	No
utm	array|null	No
meta	array|null	No
formKey	string|null	No
isTest	bool	No (default false)
sentAt	DateTimeInterface|null	No

LeadDto

Property	Type
uuid	string
type	string
source	string
isTest	bool
sentAt	DateTimeImmutable
createdAt	DateTimeImmutable
updatedAt	DateTimeImmutable
contact	ContactDto|null
utm	UtmDto|null
remoteIds	array|null
form	array|null
meta	array|null
formKey	string|null

ContactDto

Property	Type
uuid	string
fullName	string
firstName	string|null
lastName	string|null
middleName	string|null
primaryPhoneNumber	string|null
primaryEmail	string|null
remoteIds	array|null
createdAt	DateTimeImmutable
updatedAt	DateTimeImmutable

Exception handling

All exceptions extend NanoCrm\Client\Exceptions\NanoCrmException.

Exception	HTTP status	Notes
AuthenticationException	401	Invalid or missing service token
NotFoundException	404	Resource does not exist or was soft-deleted
UnprocessableException	422	Validation errors — call $e->errors()
NanoCrmException	other	Generic API error

use NanoCrm\Client\Exceptions\AuthenticationException;
use NanoCrm\Client\Exceptions\NotFoundException;
use NanoCrm\Client\Exceptions\UnprocessableException;
use NanoCrm\Client\Exceptions\NanoCrmException;

try {
    $lead = $client->leads()->find($uuid);
} catch (NotFoundException $e) {
    // 404 — not found or deleted
} catch (UnprocessableException $e) {
    $errors = $e->errors(); // array<string, string[]>
} catch (AuthenticationException $e) {
    // 401 — check token
} catch (NanoCrmException $e) {
    // other API error
}

License

MIT