Download the PHP package decole/planka-php-sdk without Composer

PHP PLANKA REST API SDK (v2.x)

An easy-to-use PHP SDK for accessing Planka's REST API.

⚠️ Version Notice & Compatibility:

• Planka v1 Support: Support for Planka v1 is discontinued in the main branch. The SDK for Planka v1 is maintained as-is in the v1 branch (SDK v1.x).
• Planka v2 Support: SDK 2.x is designed and optimized for Planka v2. Tested on Planka Community v2.2.1.
• TOTP & OIDC / SSO Notice: Two-Factor Authentication (TOTP) and OpenID Connect (OIDC / SSO) features are implemented according to Planka v2 OpenAPI specification, but have not been fully verified in automated live integration test suites. If you encounter any bugs or unexpected behavior with TOTP or OIDC, please open an Issue on GitHub with a detailed description, error logs, and reproduction steps.

Installation

For Planka v2 (SDK v2.x — Recommended)

To install the SDK for Planka v2:

Or default (installs latest v2.x):

For Planka v1 (SDK v1.x — Legacy)

If your server runs Planka v1, install the 1.x version of the SDK from the legacy branch:

Authentication

SDK 2.x supports two authentication methods for Planka v2:

1. Username & Password (JWT)

2. User API Key (Planka v2)

Configuration & Architecture Differences (SDK v1.x vs v2.x)

Advanced Usage

1. Unified Exception Handling

All SDK exceptions implement Planka\Bridge\Exceptions\PlankaSdkExceptionInterface, allowing you to catch any SDK-related error with a single catch block:

2. Flexible Network Layer: Native Symfony HttpClient & PSR-18 / PSR-17 Transport

Planka SDK is transport-agnostic. It works out-of-the-box with Symfony HttpClient, but seamlessly integrates with any PSR-18 HTTP Client (such as Guzzle, Buzz, or PSR-18 adapters) via PsrTransportClient:

A. Custom Symfony HttpClient (Timeouts, Proxies, HTTP/2):

B. PSR-18 Client with Guzzle 7:

📖 Full Transport & Testing Guide: See docs/TRANSPORT_CLIENTS.md for Buzz, Nyholm, Symfony PSR-18 adapter, and PHPUnit unit testing mock examples.

3. Custom Token Storage

You can provide a custom implementation of TokenStorageInterface to persist JWT authentication tokens or API keys across HTTP requests or sessions:

4. Type-Safe Partial Updates (Patch Input DTOs)

For partial entity updates via patching(), you can use strongly-typed Input DTOs (BoardPatchInput, CardPatchInput, ProjectPatchInput) or associative arrays:

5. Type-Safe Creation Inputs & Fluent Builder API (CardBuilder, BoardBuilder, ProjectBuilder)

When creating projects, boards, or cards, you can choose between 3 flexible options: simple positional arguments, strongly-typed Creation Input DTOs, or step-by-step Fluent Builders:

6. Transport Middleware Pipeline

You can inject custom HTTP transport middlewares into PlankaClient for logging (PSR-3 Monolog), retrying transient network errors, or collecting request metrics:

7. Parsing Incoming Webhooks (WebhookParser)

You can parse incoming HTTP Webhook JSON payloads received from the Planka server into typed DTOs using WebhookParser:

8. Raw Response Diagnostics ($_rawResponse)

Every DTO in the SDK includes a public $_rawResponse property. This diagnostic property holds the complete, unparsed associative array received from the Planka API response. It is useful for debugging, logging, or verifying whether all API response fields are properly hydrated into DTO properties:

Controllers & Features

All Planka API endpoints are accessible via explicit getter methods on PlankaClient:

• $planka->project() — Manage projects (list, create, get, update, delete, updateBackground)
• $planka->projectManager() — Manage project managers (create, delete)
• $planka->board() — Manage boards (create, get, update, delete, patching)
• $planka->boardList() — Manage lists (create, update, delete, clear, moveCards, sort)
• $planka->boardMembership() — Manage board memberships (create, update, delete)
• $planka->card() — Manage cards (create, get, update, delete, duplicate, patching, readNotifications, subscribe, unsubscribe)
• $planka->cardAction() — Fetch card activity history
• $planka->cardLabel() — Add and remove labels on cards
• $planka->cardTask() — Manage task lists within cards
• $planka->cardMembership() — Manage members assigned to cards
• $planka->comment() — Add, update and delete comments on cards
• $planka->attachment() — Upload, update and delete attachments
• $planka->label() — Manage board labels
• $planka->user() — Manage users (list, create, get, update, createApiKey, etc.)
• $planka->webhook() — (New in v2) Manage webhooks (list, create, update, delete)
• $planka->baseCustomFieldGroup() — (New in v2) Base custom field groups in projects
• $planka->customFieldGroup() — (New in v2) Custom field groups on boards/cards
• $planka->customField() — (New in v2) Custom fields inside groups
• $planka->notification() — User notifications (list, getOne, markIsRead, markIsNotRead, readAll)
• $planka->notificationService() — (New in v2) External notification services (Slack, Discord, Webhooks)
• $planka->systemConfig() — (New in v2) Planka application settings and SMTP testing

Documentation & Examples

• Enterprise Architecture & Production Readiness
• Transport Layer Architecture & Multiple HTTP Clients
• Two-Factor Authentication (2FA / TOTP) & Trusted Devices
• API Key Authentication
• Partial Updates with Patch Input DTOs
• Webhooks Management
• Custom Fields Management
• Delete Empty Boards
• Add & Manage Cards on Board
• Subscribe / Unsubscribe Users on Cards

💡 Comprehensive Examples: A complete end-to-end integration script demonstrating usage of all SDK controllers and API endpoints is available in tests/index.php.

You can also run integration tests against your Planka instance:

Testing & Quality

Unit Tests (Isolated, Mock-based)

Unit tests run locally without needing a connection to a live Planka server. They verify DTO hydration, controller behaviors, and API payload compilation using real JSON response fixtures recorded from Planka v2.

Integration Tests (Live Server Verification)

Integration tests perform real-world SDK verification against a live Planka v2 instance. To verify SDK health on your own Planka server, you can use two complementary testing methods:

1. PHPUnit Integration Test Suite (composer test-integration): Runs tests/Integration/PlankaIntegrationTest.php, performing a safe end-to-end lifecycle test (creating, updating, inspecting, and deleting projects, boards, columns, cards, task lists, labels, attachments, custom fields, webhooks, and notification services) with strict safety tracking guards.

2. Standalone Test Script (php tests/index.php): Runs tests/index.php, a standalone CLI script that executes end-to-end operations and dumps formatted DTO structures and _rawResponse payloads directly to the terminal for debugging.

Setup:

1. Copy the example configuration file:

2. Edit tests/config.php to specify your Planka server URI, port, login, and password:

3. Run the integration test suite:

Code Quality & Static Analysis

Run all quality checks (CS Fixer dry-run, Psalm static analysis, and Unit tests):

Or individual checks:

Acknowledgements & Community Contributions

This SDK v2 release incorporates valuable improvements, endpoint refinements, and architectural ideas inspired by the community fork steglasaurous/planka-php-sdk (such as TOTP 2FA flow structures, OpenAPI /api/config alignment, and extended user profile properties).

Contributing & Support

Contributions are very welcome! Whether you are fixing a bug, adding a new Planka v2 feature, or improving documentation:

1. Fork & Clone: Fork the repository on GitHub and clone it locally.
2. Create a Branch: git checkout -b feature/my-feature or fix/bug-fix.
3. Make Changes & Test: Ensure all quality checks pass before pushing:
   • composer test (Runs PHPUnit Unit tests)
   • ./vendor/bin/psalm --no-cache (Runs Psalm static analysis)
   • composer fix-cs (Formats code style)
4. Submit a Pull Request: Push your branch and open a PR against master.

For more details, see CONTRIBUTING.md.

Support & License

• 🐛 Bug Reports & Requests: Please open an Issue on GitHub Issues.
• 📄 License: Released under the AGPL-3.0 License.