PHPackages                             voipcompetencecenter/weclappclient - 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. [API Development](/categories/api)
4. /
5. voipcompetencecenter/weclappclient

ActiveLibrary[API Development](/categories/api)

voipcompetencecenter/weclappclient
==================================

Ein PHP-Client für die Weclapp REST-API v2 mit vollständiger Feature-Unterstützung

2.1.0(6mo ago)013MITPHPPHP ^8.2

Since Jul 14Pushed 3mo agoCompare

[ Source](https://github.com/VCC-Common-Tools/weclappclient)[ Packagist](https://packagist.org/packages/voipcompetencecenter/weclappclient)[ Docs](https://github.com/VCC-Common-Tools/weclappclient)[ RSS](/packages/voipcompetencecenter-weclappclient/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (6)Used By (0)

WeclappClient v2.0.0
====================

[](#weclappclient-v200)

A comprehensive and flexible PHP client for interacting with the Weclapp REST API v2.
It supports structured queries, pagination, sorting, CRUD operations, and all advanced API features.
Responses are returned as native PHP arrays with full RFC 7807 error handling.

🚀 What's New in v2.0.0
----------------------

[](#-whats-new-in-v200)

- **API v2 Migration**: Full support for weclapp API v2 with legacy v1 compatibility
- **Advanced Filtering**: OR conditions, grouping, raw filter expressions (Beta)
- **Custom Attributes**: Type-safe filtering for custom fields with automatic data conversion
- **Special Parameters**: Elegant handling of endpoint-specific parameters (entityName, entityId)
- **Performance Optimization**: Referenced entities, selective properties, additional properties
- **Enhanced Updates**: Partial updates, dry-run mode, null serialization
- **Complete Error Handling**: RFC 7807 compliant with 40+ error types
- **Backward Compatible**: Minimal breaking changes, easy migration from v1.x

📦 Installation
--------------

[](#-installation)

```
composer require voipcompetencecenter/weclappclient
```

🔧 Setup
-------

[](#-setup)

```
use WeclappClient\Core\WeclappClient;

// Default: API v2
$client = new WeclappClient('your-subdomain', 'your-api-key');

// Legacy: API v1 (if needed)
$client = new WeclappClient('your-subdomain', 'your-api-key', null, 1);
```

🔍 Querying with the QueryBuilder
--------------------------------

[](#-querying-with-the-querybuilder)

```
$results = $client->query('/customer')
    ->whereEq('customerType', 'CUSTOMER')
    ->whereLike('company', '%GmbH%')
    ->orderBy('lastModifiedDate', 'desc')
    ->limit(10)
    ->all();
```

### Supported Filter Methods

[](#supported-filter-methods)

MethodDescription`where($field, $op, $val)`Custom filter condition`whereEq('field', 'val')`Equals`whereNe('field', 'val')`Not equal`whereGt`, `whereGe`Greater than, greater or equal`whereLt`, `whereLe`Less than, less or equal`whereLike`, `whereILike`(i)LIKE search pattern`whereNotLike`, `whereNotILike`NOT LIKE pattern`whereIn('field', [...])`Field value in given list`whereNotIn('field', [...])`Field value NOT in given list`whereNull('field')`Field is null`whereNotNull('field')`Field is not null### Advanced Filtering (v2.0.0)

[](#advanced-filtering-v200)

```
// OR Conditions
$results = $client->query('/party')
    ->whereEq('firstName', 'Max')
    ->orWhere('lastName', 'eq', 'Mustermann')
    ->orWhere('email', 'like', '%@example.com')
    ->getResult();

// OR Grouping
$results = $client->query('/party')
    ->orWhereGroup('location', function($q) {
        $q->orWhere('city', 'eq', 'Berlin')
          ->orWhere('city', 'eq', 'München');
    })
    ->orWhereGroup('status', function($q) {
        $q->orWhere('active', 'eq', true)
          ->orWhere('verified', 'eq', true);
    })
    ->getResult();

// Raw Filter Expressions (Beta)
$results = $client->query('/party')
    ->whereRaw('(age >= 18) and (customer = true)')
    ->getResult();
```

### Custom Attributes (v2.0.0)

[](#custom-attributes-v200)

Type-safe filtering for custom fields with automatic data conversion:

```
// String Custom Attributes
$results = $client->query('/party')
    ->whereCustomAttributeString('customer-note', 'like', '%VIP%')
    ->getResult();

// Boolean Custom Attributes
$results = $client->query('/party')
    ->whereCustomAttributeBoolean('is-premium', 'eq', true)
    ->getResult();

// Number Custom Attributes
$results = $client->query('/party')
    ->whereCustomAttributeNumber('credit-limit', 'gt', 10000)
    ->getResult();

// Date Custom Attributes (automatic string → timestamp conversion)
$results = $client->query('/party')
    ->whereCustomAttributeDate('last-contact', 'gt', '2024-01-01')
    ->getResult();

// OR-Filter with Custom Attributes
$results = $client->query('/party')
    ->orWhereCustomAttribute('customer-tier', 'eq', 'Gold', 'stringValue')
    ->orWhereCustomAttribute('customer-tier', 'eq', 'Platinum', 'stringValue')
    ->getResult();
```

### Special Parameters (v2.0.0)

[](#special-parameters-v200)

Elegant handling of endpoint-specific parameters without operator suffixes:

```
// Document Endpoint - requires entityName and entityId
$documents = $client->query('/document')
    ->entityName('party')
    ->entityId('12345')
    ->whereLike('name', '%Rechnung%')
    ->orderBy('createdDate', 'desc')
    ->getResult();

// Comment Endpoint - requires entityName and entityId
$comments = $client->query('/comment')
    ->entityName('party')
    ->entityId('12345')
    ->orderBy('createdDate', 'desc')
    ->getResult();

// Generic parameters for any endpoint
$results = $client->query('/custom-endpoint')
    ->param('customParam', 'customValue')
    ->param('anotherParam', 123)
    ->getResult();
```

### Sorting

[](#sorting)

```
->orderAsc('fieldName')
->orderDesc('fieldName')
->orderBy('fieldName', 'desc') // 'asc' is default
```

### Limiting and Pagination

[](#limiting-and-pagination)

```
->limit(50)          // fetches up to 50 records across pages
->page(2, 25)        // page 2 with 25 entries (classic pagination)
```

🔢 Counting
----------

[](#-counting)

```
$count = $client->query('/customer')->whereEq('customerType', 'CUSTOMER')->count();
```

🎯 Getting Single Records
------------------------

[](#-getting-single-records)

```
// Get first matching record
$customer = $client->query('/customer')
    ->whereEq('customerType', 'CUSTOMER')
    ->first();

// Get specific record by ID
$customer = $client->query('/customer')->get($id);
```

⚡ Performance Optimization (v2.0.0)
-----------------------------------

[](#-performance-optimization-v200)

```
// Selective Properties - Only fetch needed fields
$results = $client->query('/article')
    ->properties(['id', 'name', 'unitId', 'articleCategoryId'])
    ->getResult();

// Referenced Entities - Load related data in one request
$results = $client->query('/article')
    ->includeReferencedEntities(['unitId', 'articleCategoryId'])
    ->getResult();

// Additional Properties - Computed fields
$results = $client->query('/article')
    ->additionalProperties('currentSalesPrice')
    ->getResult();

// Combined optimization
$results = $client->query('/article')
    ->properties(['id', 'name', 'unitId'])
    ->includeReferencedEntities(['unitId'])
    ->additionalProperties('currentSalesPrice')
    ->serializeNulls() // Include null values explicitly
    ->getResult();
```

🛠️ CRUD Operations
------------------

[](#️-crud-operations)

```
// Fetch single object by ID
$customer = $client->query('/customer')->get($id);

// Create
$created = $client->query('/customer')->create([
    'company' => 'Test GmbH',
    'customerType' => 'CUSTOMER',
    'partyType' => 'ORGANIZATION'
]);

// Update (Traditional)
$updated = $client->query('/customer')->update([
    'id' => $created['id'],
    'company' => 'Updated GmbH'
]);

// Partial Update (v2.0.0) - Only update specified fields
$updated = $client->query('/customer')->partialUpdate([
    'id' => $created['id'],
    'version' => $created['version'],
    'email' => 'new.email@example.com'
]);

// Dry-Run Mode (v2.0.0) - Validate without executing
$validation = $client->query('/customer')
    ->dryRun()
    ->create([
        'company' => 'Test Corp',
        'customerType' => 'CUSTOMER'
    ]);

// Delete
$success = $client->query('/customer')->delete($created['id']);
```

🛡️ Error Handling (v2.0.0)
--------------------------

[](#️-error-handling-v200)

The client now provides comprehensive RFC 7807 compliant error handling:

```
use WeclappClient\Exception\WeclappApiException;
use WeclappClient\Exception\WeclappValidationError;

try {
    $result = $client->query('/party')->create($data);
} catch (WeclappApiException $e) {
    // RFC 7807 compliant error information
    echo "Error Type: " . $e->getType();           // URI reference to error type
    echo "Title: " . $e->getTitle();               // Short summary
    echo "Detail: " . $e->getDetail();             // Detailed explanation
    echo "Instance: " . $e->getInstance();         // URI to affected entity

    // Validation errors (if any)
    foreach ($e->getValidationErrors() as $error) {
        echo "Field: " . $error->location;         // JsonPath to field
        echo "Message: " . $error->detail;         // Field-specific error
        echo "Allowed: " . implode(', ', $error->allowed ?? []); // Valid values
    }
}
```

### Error Types

[](#error-types)

The client supports 40+ error types including:

- **Main Errors**: `context`, `forbidden`, `optimistic_lock`, `validation`, etc.
- **Validation Errors**: `email`, `pattern`, `size`, `reference`, `enum`, etc.

📄 Response Format
-----------------

[](#-response-format)

All queries return Weclapp-formatted arrays (i.e. `response['body']['result']`). Example:

```
[
    'id' => 123456,
    'company' => 'Sample Company GmbH',
    'customerNumber' => 'C-1000',
    // ...
]
```

🔄 Migration from v1.x
---------------------

[](#-migration-from-v1x)

### Breaking Changes (Minimal)

[](#breaking-changes-minimal)

1. **Default API Version**: Now uses v2 by default (v1 still available)
2. **Update Method**: New signature `update(array $data, bool $ignoreMissingProperties = false)`

### Migration Steps

[](#migration-steps)

```
// v1.x (old)
$client = new WeclappClient('tenant', 'token');

// v2.0.0 (automatic migration)
$client = new WeclappClient('tenant', 'token'); // Uses v2 by default

// Legacy v1 (if needed)
$client = new WeclappClient('tenant', 'token', null, 1);
```

### New Features Available

[](#new-features-available)

All new features are **optional** and **backward compatible**:

```
// Use new advanced filtering
$results = $client->query('/party')
    ->whereNotNull('email')
    ->orWhere('firstName', 'eq', 'Max')
    ->getResult();

// Use custom attributes (replaces legacy customField methods)
$results = $client->query('/party')
    ->whereCustomAttributeString('customer-note', 'like', '%VIP%')
    ->whereCustomAttributeBoolean('is-premium', 'eq', true)
    ->getResult();

// Use special parameters for document/comment endpoints
$results = $client->query('/document')
    ->entityName('party')
    ->entityId('12345')
    ->getResult();

// Use performance optimizations
$results = $client->query('/article')
    ->properties(['id', 'name'])
    ->includeReferencedEntities(['unitId'])
    ->getResult();

// Use enhanced updates
$client->query('/party')->partialUpdate($data);
$client->query('/party')->dryRun()->create($data);
```

🧪 Testing
---------

[](#-testing)

```
# Run all tests
vendor/bin/phpunit

# Run specific test
vendor/bin/phpunit tests/unit/CustomerTest.php
```

---

🧩 For Developers: Reusing the QueryBuilder
------------------------------------------

[](#-for-developers-reusing-the-querybuilder)

The class `AbstractBaseQueryBuilder` provides the technical foundation for the QueryBuilder. It encapsulates reusable API logic for filters, pagination, sorting, and counting.

You can use this class as a base to implement your own API clients in a similar architecture – independent of Weclapp.

```
class MyApiQueryBuilder extends AbstractBaseQueryBuilder
{
    public function all(): array
    {
        // custom logic to retrieve all data
    }
}
```

📋 Changelog
-----------

[](#-changelog)

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

📄 License
---------

[](#-license)

MIT License - see [LICENSE](LICENSE) file for details.

###  Health Score

38

—

LowBetter than 84% of packages

Maintenance78

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

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 ~33 days

Total

4

Last Release

200d ago

Major Versions

1.0.1 → 2.0.12025-10-21

PHP version history (2 changes)v1.0.0PHP ^8.3

1.0.1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1fee26ca2fc0b57e390f74302aecf6e77f2ea3fdc8e1ea9c32f68345a38df0ca?d=identicon)[Nigatol](/maintainers/Nigatol)

---

Top Contributors

[![Nigatol](https://avatars.githubusercontent.com/u/46774889?v=4)](https://github.com/Nigatol "Nigatol (19 commits)")

---

Tags

phpclientREST APIrfc7807v2weclapp

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/voipcompetencecenter-weclappclient/health.svg)

```
[![Health](https://phpackages.com/badges/voipcompetencecenter-weclappclient/health.svg)](https://phpackages.com/packages/voipcompetencecenter-weclappclient)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[kunalvarma05/dropbox-php-sdk

Dropbox PHP API V2 SDK (Unofficial)

3633.0M18](/packages/kunalvarma05-dropbox-php-sdk)[resend/resend-php

Resend PHP library.

564.7M21](/packages/resend-resend-php)[mozex/anthropic-laravel

Anthropic PHP for Laravel is a supercharged PHP API client that allows you to interact with the Anthropic API

71226.4k1](/packages/mozex-anthropic-laravel)[optiosteam/payconiq-client-php

Payconiq API client library for PHP developed by Optios.

1273.4k](/packages/optiosteam-payconiq-client-php)

PHPackages © 2026

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