Download the PHP package mcore-services/teamleader-sdk without Composer
On this page you can find all versions of the php package mcore-services/teamleader-sdk. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download mcore-services/teamleader-sdk
More information about mcore-services/teamleader-sdk
Files in mcore-services/teamleader-sdk
Package teamleader-sdk
Short Description Laravel SDK for Teamleader Focus API
License MIT
Homepage https://hub.mcore-services.be/docs/teamleader-sdk
Informations about the package teamleader-sdk
Teamleader Focus SDK for Laravel
A Laravel package for the Teamleader Focus API. Handles OAuth token management, rate limiting, and around 70 API resources behind a consistent interface.
Quick Links:
- π¦ Packagist: packagist.org/packages/mcore-services/teamleader-sdk
- π» GitHub: github.com/MCore-Services-bv/teamleader-sdk
- π Documentation: teamleader-sdk.mcore-services.dev β guides, and an API reference generated from the code
β¨ Key Features
π Authentication & Security
- Complete OAuth 2.0 Flow β Authorization URL generation and secure callback handling
- Automatic Token Management β Smart token refresh with database and cache layers
- Concurrent Request Safety β Distributed locking prevents token refresh race conditions
π Performance & Reliability
- Proactive Rate Limiting β Redis-backed sliding window that waits for a free slot rather than letting you hit the 200 req/min limit
- Response Caching β Configurable caching for static data endpoints
- Retry Logic β Automatic retry with backoff for transient failures
π¦ Developer Experience
- Resource-Based Architecture β Organised access to all API endpoints
- Fluent Sideloading β Reduce API calls by including related resources
- Fail-Fast Validation β Unsupported filters, sort fields and includes throw before the request is sent, rather than being silently ignored by the API
- Rich Error Handling β Typed exceptions with actionable messages
- Resource Introspection β Query any resource's capabilities programmatically
π― API Coverage
CRM β Companies, Contacts, Business Types, Tags, Addresses
Deals & Sales β Deals, Quotations, Orders, Pipelines, Phases, Sources, Lost Reasons
Invoicing β Invoices, Credit Notes, Payment Methods, Payment Terms, Tax Rates, Withholding Tax Rates, Commercial Discounts, Subscriptions
Expenses β Expenses, Incoming Invoices, Incoming Credit Notes, Receipts, Bookkeeping Submissions
Projects & Time Tracking β Projects (both the current and legacy systems), Project Tasks, Groups, Materials, Project Lines, External Parties, Time Tracking, Timers
Planning β Reservations, User Availability, Plannable Items
Calendar & Activities β Meetings, Calls, Call Outcomes, Calendar Events, Activity Types
Products & Services β Products, Product Categories, Units of Measure, Work Types, Price Lists
General β Users, Teams, Departments, Custom Fields, Currencies, Notes, Files, Document Templates, User Schedules, Closing Days, Days Off, Day Off Types, Email Tracking
System β Webhooks, Cloud Platforms, Accounts, Migration Utilities
π Requirements
- PHP: 8.2 or higher (tested on 8.2 β 8.5)
- Laravel: 12.x or 13.x
- Extensions:
ext-json,ext-mbstring - Database: MySQL 5.7+, PostgreSQL 10+, or SQLite 3.8+
- Redis: required only if rate limiting is enabled β it is, by default
Laravel 10 and 11 were dropped in v2.0. Both are EOL with unpatched CVEs, and Composer's security advisories block installing them.
π Installation
1. Install via Composer
2. Publish the Configuration
3. Configure Environment Variables
4. Set Up OAuth Routes
Note: No
php artisan migrateis required. The SDK creates theteamleader_tokenstable on first use.
π Authentication
π Basic Usage
Every resource follows the same shape:
$filters maps to the API's filter object. $options carries page_size,
page_number, sort, sort_order and include.
Companies
Contacts
Deals
Invoices
A grouped line with no section title must omit the
sectionkey entirely β Teamleader rejects bothnulland''. See the Invoices reference.
Time Tracking
Files
Custom Fields
π Pagination
The API returns no total count. Most endpoints send no meta block, so the
only end-of-list signal is a page shorter than the requested page size β meaning
a full final page costs one extra empty request.
β‘ Rate Limiting
Teamleader allows 200 requests per sliding minute. The SDK tracks usage in Redis, throttles progressively as the window fills, and waits for a free slot rather than firing a request that can only come back as a 429.
The wait is capped by teamleader.rate_limiting.max_wait_ms (default 5000). Once
the cap is reached a RateLimitExceededException is thrown and the decision
returns to you β which in a queue worker usually means releasing the job:
Set max_wait_ms to 65000 if you would rather the SDK sit out a full window
itself β sensible for a CLI import, less so for a web request.
π Sideloading
Related records can be requested in the same call, via $options['include'] or
the fluent methods:
Includes are per endpoint.
listandinfofrequently accept different sets, and some endpoints accept none at all. An unsupported include throws rather than being silently ignored.
πͺ Webhooks
The payload carries the entity id at subject.id, not data.id:
π οΈ Error Handling
All API exceptions extend TeamleaderException.
Client-side validation throws InvalidArgumentException before the request is
sent β for unsupported filter keys, sort fields, includes and subject types:
This is deliberate. The API answers 200 to filters it does not recognise and
returns the complete unfiltered set, so silence is the more dangerous outcome.
π₯οΈ Artisan Commands
β Specification Parity
Every resource is checked against Teamleader's machine-readable API
specification, @teamleader/focus-api-specification,
currently pinned at 1.221.0.
The Teamleader API answers 200 OK to a filter, sort field, include or body
field it does not recognise, and simply ignores it. A typo therefore looks like
success: a mistyped filter returns every record, and a mistyped field on an
update changes nothing. The SDK checks those names against the specification
and throws before the request is sent.
How that is kept true:
- Spec contract tests. Field lists, required fields and enums on each resource are asserted against a fixture generated from the specification.
- Spec audit.
composer spec:auditcompares every resource's filters, sort fields, includes, pagination and endpoints with the specification;php bin/spec-audit --checkfails CI on anything not recorded in the baseline. The one recorded divergence is the deprecatedusers.getWeekSchedulewrapper, kept until v3.0. - Weekly watch. A scheduled workflow audits the SDK against the newest published specification and opens an issue when it finds a difference, so API changes surface before they surface as bug reports.
π€ Contributing
Contributions are welcome β see CONTRIBUTING.md.
Bug reports are especially useful when they include what you expected, what happened, and how you worked around it. Several fixes in v2.2.0 came directly from reports written that way.
π Security
If you discover a security issue, email [email protected] rather than using the issue tracker. See SECURITY.md.
π Changelog
See CHANGELOG.md.
π License
The MIT License (MIT). See LICENSE.md.
π Credits
- MCore Services β https://mcore-services.be
- Built with β€οΈ for the Laravel and Teamleader communities
π¬ Support
- Documentation: teamleader-sdk.mcore-services.dev
- Email: [email protected]
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Teamleader API: developer.focus.teamleader.eu
πΊοΈ Roadmap
- [x] Spec-derived filter parity across every resource, enforced by a test (v2.3.0)
- [x] Payload tests for all resources (v2.3.0)
- [ ] Bulk operations helper (v3.0)
- [ ] CLI tool for quick API exploration (v3.0)
- [ ] Enhanced caching strategies with tag-based invalidation
- [ ] Laravel Pulse integration
Made with β€οΈ by MCore Services
All versions of teamleader-sdk with dependencies
guzzlehttp/guzzle Version ^7.0 || ^8.0
illuminate/support Version ^12.0|^13.0