Download the PHP package codebes/gripp-sdk without Composer

Gripp SDK for PHP

A PHP SDK for the Gripp (now Exact Gripp) CRM/ERP API. Manage companies, contacts, projects, invoices, time tracking, and 50+ other resources through a fluent query builder with batch operations, auto-pagination, and automatic retries. Works with any PHP 8.1+ application, including Laravel.

Features

• Fluent query builder with 14 filter operators
• Full CRUD support on 54 Gripp resources
• Batch operations (multiple API calls in a single HTTP request)
• Auto-pagination for large datasets
• Automatic retries on server errors and connection failures
• Typed exceptions for authentication, rate limiting, and API errors
• Laravel Collection responses out of the box
• Self-documenting resources with field types, required fields, and relationship metadata
• Billability (declarabiliteit) and invoiceability (facturabiliteit) calculations, with an explicit account of what is exact and what is estimated

Requirements

• PHP 8.1+
• A Gripp API token and API URL

Installation

Configuration

Option 1: Environment variables

Set GRIPP_API_TOKEN in your .env file or environment:

Then call configure without arguments:

The SDK uses https://api.gripp.com by default. To override, set GRIPP_API_URL in your environment.

Option 2: Explicit configuration

Option 3: Interactive setup

This creates a .env file with your credentials.

Quick Start

Query Builder

The query builder provides a fluent interface for filtering, ordering, and paginating results.

Supported Filter Operators

Date Helpers

Common date filtering patterns are built into the query builder:

whereModifiedSince() sends two requests, on purpose. Gripp leaves updatedon empty on records that were created and never edited afterwards, so filtering on updatedon alone silently omits every untouched record. The correct condition is updatedon >= $date OR createdon >= $date, and the Gripp API has no OR - every filter in the array is ANDed. So the SDK runs both halves and merges them on id.

Auto-Prefixing

Field names are automatically prefixed with the entity name when using the query builder. Writing Project::where('createdon', ...) produces the filter field project.createdon. Fully qualified fields like project.createdon are left as-is.

Auto-Pagination

Both get() and the query builder's get() automatically paginate through all results. Use limit() when you only want a specific number of results (single API call):

Batch Operations

Group multiple API calls into a single HTTP request for better performance:

Rate Limit Awareness

The transport tracks rate limit headers from API responses and provides hooks for proactive budget management:

The SDK treats both HTTP 429 and HTTP 503 with Gripp error code 1004 (short-burst throttle) as rate limit errors.

Error Handling

The SDK throws specific exceptions for different error types:

Available Resources

All resources support read operations. Resources that also support create, update, and/or delete are indicated below.

Special resources:

• Notification has custom emit() and emitall() methods instead of CRUD.
• Company has additional getCompanyByCOC(), addInteractionByCompanyId(), and addInteractionByCompanyCOC() methods.

Resource Metadata

Every resource class exposes constants that describe its schema:

• FIELDS maps field names to their types (string, int, float, boolean, datetime, date, array, customfields, color)
• READONLY lists fields that cannot be written to
• REQUIRED lists fields that must be provided when creating/updating
• RELATIONS maps foreign key fields to their related resource classes

Auto-Pagination

Both all() and get() automatically handle pagination, fetching all matching records transparently:

Response Format

All collection methods return Illuminate\Support\Collection instances. Single-record methods return associative arrays or null.

Billability and Invoiceability

CodeBes\GrippSdk\Features\Billability computes two measures from hours, project lines and invoice lines. In Dutch they have different names, and they answer different questions.

Ten hours on a paid project line are 100% billable. If five of them end up on an invoice, invoiceability is 50%.

Why invoiceability is exact for some hours and estimated for others

Whether an hour counts as invoiced depends on the invoice basis (invoicebasis) of the project line it was written on, because Gripp records the link between hours and invoices differently per basis:

This was verified against a full year of live Gripp data: for Nacalculatie and Begroot, the quantity on every invoice line in hours equals the sum of the hours linked to it, and not a single hour on a Fixed line had an invoice line. The limit is in how Gripp records Fixed invoicing, not in the SDK. No API call can tell who a Fixed invoice line was for.

For Fixed lines the SDK therefore works per project line:

1. Over the line's whole life. All hours ever written on the line are set against all hour quantities ever invoiced on it, regardless of the requested period. Fixed work is often invoiced up front or in instalments, so comparing within one period would pair invoices with the wrong work.
2. Not capped at the hours worked. Sell and invoice 35 hours, work 10, and those 10 hours count as 35 invoiced hours: 350% on that line.
3. Split pro rata when a line is shared. When several people wrote hours on the line, each of their hours gets the line's ratio of invoiced hours to hours written. This is the only assumption in the calculation: totals per line, per project and per team add up exactly.
4. Credit lines count negative on the project line they point at.
5. Lines invoiced in other units are left out. Pieces (stuks), a fixed price (prijs) or any unit other than uur has no hour quantity to compare with. Unit.hoursperunit does not help, because Gripp returns 1 for every unit. These hours are reported as unmeasurable_hours and excluded from the percentage.

Every invoiceability result says how much of it is exact:

To make Fixed work exact per person, it has to be recorded differently in Gripp: one project line per person on Fixed projects, or the Begroot basis, where Gripp does link hours to invoices.

Cost. Invoiceability fetches the period's hours, plus the lifetime hours and invoice lines of every Fixed line in the period, 100 lines per request. For a team of about twenty people over a full year that took 206 API calls, around 100 seconds and 212 MB of memory, above PHP's default memory_limit of 128 MB. Raise the limit, or ask per employee or per quarter and add up the hours. forTeam() loads the same hours and needs the same memory.

uninvoicedHours() lists hours without hour.invoiceline. That includes every hour on a Fixed line, invoiced or not, so do not use it to find uninvoiced Fixed work.

Testing

Or directly:

Changelog

Please see the GitHub Releases page for more information on what has changed recently.

Contributing

Contributions are welcome! Please open a pull request against the main branch. All PRs require:

• Passing tests (composer test)
• Code style compliance (composer cs)
• Static analysis passing (composer analyse)
• Code owner approval

License

MIT - see LICENSE for details.