Download the PHP package freema/n8n-bundle without Composer

Symfony N8n Bundle

Elegant integration between Symfony applications and n8n workflow automation platform.

Features

• Type-safe communication using PHP interfaces
• UUID tracking system for request/response pairing
• Flexible communication modes: Fire & Forget, Async with callback, Sync
• Robust error handling with retry and circuit breaker
• Event-driven architecture for monitoring and logging
• Multi-instance support for different environments
• Dry run mode for testing without actual sending

Requirements

* Symfony 8.0 itself requires PHP 8.4+. On PHP 8.2/8.3 the bundle runs with Symfony 6.4 or 7.x; use PHP 8.4+ if you want Symfony 8.0.

Quick Start

1. Installation

2. Development with Docker and Taskfile

3. Configuration

4. Entity Implementation

5. Usage

Communication Modes

Fire & Forget

Sends data to n8n and returns immediate response from webhook.

Async with Callback

Sends data + callback URL, n8n processes and returns result.

Sync

Waits for immediate response (if n8n webhook supports it).

Error Handling

All errors thrown by the client extend Freema\N8nBundle\Exception\N8nException:

Retries

When retry_attempts > 0, failed requests are retried with exponential backoff (retry_delay_ms, doubled each attempt). Retries apply to transport errors, timeouts and HTTP 5xx responses. Client errors (4xx) are not retried.

Circuit Breaker

With enable_circuit_breaker: true, the client opens the circuit after circuit_breaker_threshold consecutive failures and rejects further calls (throwing N8nCommunicationException) for circuit_breaker_timeout_seconds before trying again. A successful call resets the breaker.

The circuit breaker is in-memory, so its state lives for the duration of a single PHP process — it is most useful in long-running workers (e.g. Symfony Messenger).

Test Webhooks

During development you can target n8n's test webhook URL (/webhook-test/) instead of the production one (/webhook/) to use unpublished workflows:

HTTP Methods and Content Types

Bundle supports various HTTP methods and content types:

Response Entity Mapping

You can automatically map n8n responses to PHP objects:

Debug Panel

Bundle includes debug panel for Symfony Web Profiler:

Panel shows:

• All N8n requests with UUID, duration, status
• Payload data and response data
• Errors and their details
• Total request count and time

Monitoring and Events

Bundle emits events for each phase of communication:

Test Application

The dev/ directory contains a test application with Docker support (PHP 8.2 + PHP 8.4).

Setup

1. Start Docker containers:

2. Install dependencies:

3. Environment configuration:

4. Start development server:

Application will be available at http://localhost:8080

Available Taskfile Commands:

Endpoints:

• POST /demo/fire-and-forget - Fire & Forget test
• POST /demo/with-callback - Async callback test
• POST /demo/sync - Synchronous test
• GET /demo/health - Health check
• POST /api/n8n/callback - Callback endpoint
• GET /_profiler - Symfony Web Profiler

Example Usage

Forum Post Moderation

Testing

Mock Client

For testing your application without making actual HTTP requests to n8n, use the MockN8nClient:

Mock Client Features

Configure responses:

Assertions:

Inspect requests:

Configure behavior:

Configuration

Complete Configuration

Author

Created by Tomáš Grasl

License

MIT