README

A comprehensive Laravel package for integrating with the n8n API using clean architecture patterns. This package provides a facade-based interface with support for multiple execution strategies, request builders, and event observability.

Features

Facade - Simple static interface (N8N::workflows())
Adapter - Clean abstraction of n8n API communication
Strategy - Multiple execution strategies (sync, async, queued)
Builder - Fluent API for constructing complex payloads
Observer - Event hooks for request lifecycle
Clean Architecture - SOLID principles and separation of concerns
Type Safety - Full PHP 8.1+ type hints and strict typing
Event System - Laravel events for request monitoring
Comprehensive Testing - Pest framework with full test coverage

Installation

composer require mrkindy/n8n-laravel

Publish Configuration

php artisan vendor:publish --provider="MrKindy\N8NLaravel\N8NServiceProvider" --tag="n8n-config"

Environment Configuration

Add these variables to your .env file:

N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your-api-key-here
N8N_DEFAULT_STRATEGY=sync
N8N_HTTP_TIMEOUT=30
N8N_HTTP_RETRY_TIMES=3
N8N_HTTP_RETRY_SLEEP=1000
N8N_HTTP_VERIFY_SSL=true
N8N_EVENTS_ENABLED=true
N8N_LOGGING_ENABLED=true
N8N_LOGGING_LEVEL=info
N8N_LOGGING_CHANNEL=default
N8N_QUEUE_CONNECTION=default
N8N_QUEUE_NAME=n8n

Usage

For detailed usage instructions, please refer to DOCUMENTATION.md.

Testing

The package uses the Pest testing framework. Run tests with:

vendor/bin/pest

Test Structure

tests/
├── Pest.php                    # Pest configuration
├── TestCase.php                # Base test case
├── Feature/
│   ├── FacadeTest.php         # Facade functionality tests
│   ├── BuilderTest.php        # Builder tests
│   ├── ObserverTest.php       # Observer tests
│   └── StrategyTest.php       # Strategy tests
└── Unit/
    ├── AdapterTest.php        # Adapter unit tests
    └── ServiceTest.php        # Individual service tests

Writing Tests

use MrKindy\N8NLaravel\Facades\N8N;

it('can create a workflow', function () {
    Http::fake([
        'localhost:5678/api/v1/workflows' => Http::response([
            'id' => 'workflow-123',
            'name' => 'Test Workflow'
        ])
    ]);

    $result = N8N::workflows()->create([
        'name' => 'Test Workflow',
        'nodes' => []
    ]);

    expect($result)->toHaveKey('id', 'workflow-123');
});

Configuration Reference

HTTP Client Options

'http' => [
    'timeout' => 30,                    // Request timeout in seconds
    'retry' => [
        'times' => 3,                   // Number of retry attempts
        'sleep' => 1000,                // Sleep between retries (ms)
    ],
    'verify' => true,                   // SSL certificate verification
],

Queue Configuration

'queue' => [
    'connection' => 'redis',            // Queue connection
    'queue' => 'n8n-operations',       // Queue name
],

Logging Configuration

'logging' => [
    'enabled' => true,                  // Enable request logging
    'level' => 'info',                  // Log level
    'channel' => 'n8n',                // Log channel
],

API Coverage

This package provides full coverage of the n8n Public API v1.1.1:

Workflows

✅ List workflows
✅ Get workflow
✅ Create workflow
✅ Update workflow
✅ Delete workflow
✅ Activate workflow
✅ Deactivate workflow
✅ Transfer workflow
✅ Get workflow tags
✅ Update workflow tags

Credentials

✅ Create credential
✅ Delete credential
✅ Get credential schema
✅ Transfer credential

Executions

✅ List executions
✅ Get execution
✅ Delete execution

Users (Enterprise)

✅ List users
✅ Get user
✅ Create users
✅ Delete user
✅ Change user role

Variables

✅ List variables
✅ Create variable
✅ Update variable
✅ Delete variable

Projects (Enterprise)

✅ List projects
✅ Create project
✅ Delete project
✅ Add users to project

Audit

✅ Generate audit

Source Control

✅ Pull changes

Contributing

Fork the repository
Create a feature branch
Write tests for your changes
Ensure all tests pass: vendor/bin/pest
Follow PSR-12 coding standards
Submit a pull request

Development Setup

git clone https://github.com/mrkindy/n8n-laravel.git
cd n8n-laravel
composer install
cp .env.example .env
# Configure your n8n instance details in .env
vendor/bin/pest

Requirements

PHP 8.1+
Laravel 10.0+ or 11.0+
n8n instance with API access

License

This package is open-sourced software licensed under the MIT license.

Support

Changelog

Please see CHANGELOG for more information on what has changed recently.

Built with ❤️ for the Laravel and n8n communities.

mrkindy / n8n-laravel

Maintainers

Details