PHPackages                             budgetlens/laravel-copernica-rest-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. budgetlens/laravel-copernica-rest-client

ActiveLibrary[HTTP & Networking](/categories/http)

budgetlens/laravel-copernica-rest-client
========================================

A fluent PHP (Laravel) REST client for the Copernica Marketing Software API v4

v1.0.2(2mo ago)0307MITPHPPHP ^8.3

Since Apr 9Pushed 2mo agoCompare

[ Source](https://github.com/123lens/laravel-copernica-rest-client)[ Packagist](https://packagist.org/packages/budgetlens/laravel-copernica-rest-client)[ RSS](/packages/budgetlens-laravel-copernica-rest-client/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (3)Dependencies (5)Versions (4)Used By (0)

Laravel Copernica REST Client for PHP
=====================================

[](#laravel-copernica-rest-client-for-php)

A fluent, modern PHP (Laravel) client for the [Copernica Marketing Software](https://www.copernica.com) REST API v4. Built with clean architecture, strongly-typed DTOs, and first-class Laravel support.

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- [Composer](https://getcomposer.org)
- A Copernica account with a REST API v4 access token - Generate your [access\_token](https://copernica.com)
- GuzzleHTTP 7.0+ (installed automatically via Composer)

Installation
------------

[](#installation)

```
composer require budgetlens/laravel-copernica-rest-client
```

### Laravel

[](#laravel)

The package supports Laravel auto-discovery. After installation, add your access token to `.env`:

```
COPERNICA_ACCESS_TOKEN=your-api-token-here
```

Optionally publish the configuration file:

```
php artisan vendor:publish --provider="Budgetlens\Copernica\RestClient\CopernicaServiceProvider"
```

This publishes `config/copernica.php` where you can configure:

OptionEnv VariableDefault`access_token``COPERNICA_ACCESS_TOKEN``""``base_url``COPERNICA_BASE_URL``https://api.copernica.com/v4``timeout``COPERNICA_TIMEOUT``30`> **Tip:** Use `https://rest.copernica.com/v4` as base URL for large dataset retrieval.

### Standalone (without Laravel)

[](#standalone-without-laravel)

```
use Budgetlens\Copernica\RestClient\CopernicaClient;

$client = new CopernicaClient(
    accessToken: 'your-api-token-here',
    baseUrl: 'https://api.copernica.com/v4', // optional
    timeout: 30, // optional
);
```

Quick Start
-----------

[](#quick-start)

```
// Laravel (via Facade)
use Budgetlens\Copernica\RestClient\Facades\Copernica;

$databases = Copernica::databases()->list();

// Laravel (via dependency injection)
use Budgetlens\Copernica\RestClient\CopernicaClient;

public function index(CopernicaClient $copernica)
{
    $databases = $copernica->databases()->list();
}

// Standalone
$client = new CopernicaClient('your-token');
$databases = $client->databases()->list();
```

Usage
-----

[](#usage)

### Account Information

[](#account-information)

```
// Get account identity
$identity = $client->identity();

// Get API consumption/usage
$consumption = $client->consumption();
```

### Databases

[](#databases)

```
// List all databases
$databases = $client->databases()->list();

// Get a single database
$database = $client->database(123)->get();

echo $database->name;
echo $database->description;

// Create a new database
$id = $client->databases()->create([
    'name' => 'Newsletter',
    'description' => 'Newsletter subscribers',
]);

// Update a database
$client->database(123)->update([
    'description' => 'Updated description',
]);

// Copy a database
$newId = $client->database(123)->copy([
    'name' => 'Newsletter Copy',
]);

// Delete a database
$client->database(123)->delete();
```

### Fields

[](#fields)

```
// List database fields
$fields = $client->database(123)->fields()->list();

// Create a field
$fieldId = $client->database(123)->fields()->create([
    'name' => 'email',
    'type' => 'email',
]);

// Update a field
$client->database(123)->fields()->update($fieldId, [
    'name' => 'email_address',
]);

// Delete a field
$client->database(123)->fields()->delete($fieldId);

// Collection fields work the same way
$fields = $client->database(123)->collection(456)->fields()->list();
```

### Profiles

[](#profiles)

```
// List profiles in a database
$profiles = $client->database(123)->profiles()->list();

// Paginated iteration (lazy-loads all pages)
foreach ($client->database(123)->profiles()->each() as $profile) {
    echo $profile->field('email');
}

// Filter profiles by field values
$results = $client->database(123)->profiles()->where('email', 'john@example.com');

// Filter by multiple fields
$results = $client->database(123)->profiles()->where([
    'city' => 'Amsterdam',
    'newsletter' => 'yes',
]);

// Get a single profile
$profile = $client->database(123)->profile(456)->get();

echo $profile->id;
echo $profile->field('email');
echo $profile->fields;    // all fields as array
echo $profile->interests; // interests array
echo $profile->createdAt; // DateTimeImmutable

// Create a profile
$profileId = $client->database(123)->profiles()->create([
    'fields' => [
        'email' => 'john@example.com',
        'firstname' => 'John',
        'lastname' => 'Doe',
    ],
    'interests' => [
        'newsletter' => true,
    ],
]);

// Update a profile
$client->database(123)->profile(456)->update([
    'fields' => [
        'lastname' => 'Smith',
    ],
]);

// Get/update profile fields directly
$fields = $client->database(123)->profile(456)->fields();
$client->database(123)->profile(456)->updateFields(['city' => 'Rotterdam']);

// Get/update interests
$interests = $client->database(123)->profile(456)->interests();
$client->database(123)->profile(456)->updateInterests(['newsletter' => true]);

// Delete a profile
$client->database(123)->profile(456)->delete();
```

### Subprofiles

[](#subprofiles)

```
// List subprofiles of a profile (optionally scoped to a collection)
$subprofiles = $client->database(123)->profile(456)->subprofiles()->list();
$subprofiles = $client->database(123)->profile(456)->subprofiles(collectionId: 789)->list();

// List subprofiles in a collection
$subprofiles = $client->database(123)->collection(789)->subprofiles()->list();

// Paginated iteration
foreach ($client->database(123)->profile(456)->subprofiles()->each() as $subprofile) {
    echo $subprofile->field('order_number');
}

// Get a single subprofile
$subprofile = $client->database(123)->profile(456)->subprofile(101)->get();

// Create a subprofile
$subId = $client->database(123)->profile(456)->subprofiles()->create([
    'fields' => [
        'order_number' => 'ORD-001',
        'amount' => '49.95',
    ],
]);

// Update a subprofile
$client->database(123)->profile(456)->subprofile(101)->update([
    'fields' => ['amount' => '59.95'],
]);

// Delete a subprofile
$client->database(123)->profile(456)->subprofile(101)->delete();
```

### Collections

[](#collections)

```
// List collections in a database
$collections = $client->database(123)->collections()->list();

// Get a single collection
$collection = $client->database(123)->collection(456)->get();

// Create a collection
$id = $client->database(123)->collections()->create([
    'name' => 'Orders',
]);

// Update a collection
$client->database(123)->collection(456)->update([
    'name' => 'Purchase Orders',
]);

// Manage unsubscribe behavior
$settings = $client->database(123)->collection(456)->unsubscribe();
$client->database(123)->collection(456)->setUnsubscribe([
    'behavior' => 'update',
    'field' => 'newsletter',
]);
```

### Views

[](#views)

```
// List views for a database
$views = $client->database(123)->views()->list();

// Get a single view
$view = $client->database(123)->view(456)->get();

// Create a view
$viewId = $client->database(123)->views()->create([
    'name' => 'Active subscribers',
    'description' => 'All active newsletter subscribers',
]);

// Get profiles from a view
$profiles = $client->database(123)->view(456)->profiles()->list();

// Paginate profiles in a view
foreach ($client->database(123)->view(456)->eachProfile() as $profile) {
    // ...
}

// Get profile IDs from a view
$ids = $client->database(123)->view(456)->profileIds();

// Manage view rules
$rules = $client->database(123)->view(456)->rules();
$ruleId = $client->database(123)->view(456)->createRule([
    'name' => 'Is active',
    'conditions' => [
        ['type' => 'field', 'field' => 'active', 'value' => 'yes'],
    ],
]);

// Rebuild a view
$client->database(123)->view(456)->rebuild();

// Update / delete
$client->database(123)->view(456)->update(['name' => 'Renamed view']);
$client->database(123)->view(456)->delete();
```

### Emailings

[](#emailings)

```
// --- HTML Emailings ---

// List all HTML emailings
$emailings = $client->emailings()->list();

// Paginate emailings
foreach ($client->emailings()->each() as $emailing) {
    echo $emailing->subject;
}

// Get scheduled emailings
$scheduled = $client->emailings()->scheduled();

// Get a single emailing
$emailing = $client->emailing(123)->get();

echo $emailing->id;
echo $emailing->subject;
echo $emailing->fromAddress;

// Create an emailing
$id = $client->emailings()->create([
    'subject' => 'Monthly newsletter',
    'database' => 123,
    'template' => 456,
]);

// --- Drag & Drop Emailings ---

$emailings = $client->dragAndDropEmailings()->list();
$emailing = $client->dragAndDropEmailing(123)->get();

// --- Statistics ---

$stats = $client->emailing(123)->statistics();

echo $stats->destinations;
echo $stats->deliveries;
echo $stats->impressions;
echo $stats->clicks;
echo $stats->unsubscribes;
echo $stats->abuses;
echo $stats->errors;

// --- Destinations ---

$destinations = $client->emailing(123)->destinations();

// Paginate destinations
foreach ($client->emailing(123)->eachDestination() as $dest) {
    echo $dest->profileId;
    echo $dest->timestamp; // DateTimeImmutable
}

// --- Result details ---

$deliveries   = $client->emailing(123)->deliveries();
$impressions  = $client->emailing(123)->impressions();
$clicks       = $client->emailing(123)->clicks();
$errors       = $client->emailing(123)->errors();
$unsubscribes = $client->emailing(123)->unsubscribes();
$abuses       = $client->emailing(123)->abuses();

// Get the emailing snapshot (the email as it was sent)
$snapshot = $client->emailing(123)->snapshot();
```

### Webhooks

[](#webhooks)

```
// List all webhooks
$webhooks = $client->webhooks()->list();

// Get a single webhook
$webhook = $client->webhook(123)->get();

echo $webhook->handler;
echo $webhook->url;
echo $webhook->trigger;

// Create a webhook
$id = $client->webhooks()->create([
    'handler' => 'profile',
    'url' => 'https://example.com/webhook',
    'trigger' => 'create',
    'database' => 123,
]);

// Update a webhook
$client->webhook(123)->update([
    'url' => 'https://example.com/webhook-v2',
]);

// Delete a webhook
$client->webhook(123)->delete();
```

### Raw API Access

[](#raw-api-access)

For endpoints not yet covered by the client, you can use the raw HTTP methods:

```
$response = $client->get('some/endpoint', ['param' => 'value']);
$response = $client->post('some/endpoint', ['key' => 'value']);
$response = $client->put('some/endpoint', ['key' => 'value']);
$response = $client->delete('some/endpoint');
```

Error Handling
--------------

[](#error-handling)

The client throws specific exceptions for different error scenarios:

```
use Budgetlens\Copernica\RestClient\Exceptions\AuthenticationException;
use Budgetlens\Copernica\RestClient\Exceptions\NotFoundException;
use Budgetlens\Copernica\RestClient\Exceptions\ValidationException;
use Budgetlens\Copernica\RestClient\Exceptions\RateLimitException;
use Budgetlens\Copernica\RestClient\Exceptions\CopernicaException;

try {
    $profile = $client->database(123)->profile(999)->get();
} catch (AuthenticationException $e) {
    // 401/403 - Invalid or expired access token
} catch (NotFoundException $e) {
    // 404 - Resource not found
} catch (ValidationException $e) {
    // 400/422 - Invalid request data
    $details = $e->errors; // detailed error info from the API
} catch (RateLimitException $e) {
    // 429 - Too many requests
} catch (CopernicaException $e) {
    // Any other API error
}
```

All exceptions extend `CopernicaException`, which extends `RuntimeException`. You can catch `CopernicaException` to handle all API errors at once.

DTOs
----

[](#dtos)

All API responses are mapped to strongly-typed Data Transfer Objects:

DTODescription`Database`Database with ID, name, description, archived status, fields, interests, collections`Collection`Database collection with ID, name, parent database, and fields`Field`Database/collection field with type, length, and display settings`Profile`Contact record with fields, interests, and timestamps`Subprofile`Collection subprofile with fields and timestamps`View`Database view with rules and rebuild status`Emailing`Email campaign (HTML or Drag & Drop) with content details`EmailingDestination`Single emailing recipient with profile/subprofile ID`EmailingStatistics`Aggregated statistics (deliveries, impressions, clicks, etc.)`Webhook`Webhook subscription with handler, URL, and trigger typeAll DTOs implement the `FromArray` contract and are immutable (`readonly` properties).

Architecture
------------

[](#architecture)

```
src/
├── CopernicaClient.php          # Main entry point
├── CopernicaServiceProvider.php # Laravel service provider
├── Facades/
│   └── Copernica.php            # Laravel facade
├── Http/
│   ├── CopernicaHttpClient.php  # Guzzle-based HTTP layer
│   └── PaginatedResponse.php    # Lazy-loading paginator
├── Resources/
│   ├── Resource.php             # Abstract base resource
│   ├── DatabaseResource.php     # /database endpoints
│   ├── ProfileResource.php      # /profile endpoints
│   ├── SubprofileResource.php   # /subprofile endpoints
│   ├── CollectionResource.php   # /collection endpoints
│   ├── FieldResource.php        # Field management
│   ├── ViewResource.php         # /view endpoints
│   ├── EmailingResource.php     # Emailing endpoints
│   └── WebhookResource.php      # /webhook endpoints
├── DTOs/
│   ├── Contracts/FromArray.php  # DTO factory contract
│   ├── Concerns/ParsesDate.php  # Date parsing trait
│   ├── Database.php
│   ├── Collection.php
│   ├── Field.php
│   ├── Profile.php
│   ├── Subprofile.php
│   ├── View.php
│   ├── Emailing.php
│   ├── EmailingDestination.php
│   ├── EmailingStatistics.php
│   └── Webhook.php
└── Exceptions/
    ├── CopernicaException.php        # Base exception
    ├── AuthenticationException.php   # 401/403
    ├── NotFoundException.php         # 404
    ├── ValidationException.php       # 400/422
    └── RateLimitException.php        # 429

```

Testing
-------

[](#testing)

```
composer test
```

Tests use PHPUnit 11 and Orchestra Testbench for Laravel integration testing.

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance85

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

78d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/af0112579d392b0f20366a7a4acbcfe437c29edf24d795f17cef8c15331371a0?d=identicon)[123lens](/maintainers/123lens)

---

Top Contributors

[![avido](https://avatars.githubusercontent.com/u/14986?v=4)](https://github.com/avido "avido (7 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/budgetlens-laravel-copernica-rest-client/health.svg)

```
[![Health](https://phpackages.com/badges/budgetlens-laravel-copernica-rest-client/health.svg)](https://phpackages.com/packages/budgetlens-laravel-copernica-rest-client)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k532.1M2.5k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k496.1k33](/packages/neuron-core-neuron-ai)[illuminate/http

The Illuminate Http package.

11937.2M6.5k](/packages/illuminate-http)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.2M46](/packages/tencentcloud-tencentcloud-sdk-php)[dreamfactory/df-core

DreamFactory(tm) Core Components

1652.0k38](/packages/dreamfactory-df-core)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

252.5k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)