README

n8n-php

A lightweight PHP SDK for n8n, the open-source workflow automation tool. Control your n8n instance directly from PHP: manage workflows, trigger webhooks, handle users, and more.

Quick Start

Install via Composer:

composer require usmanzahid/n8n-php

Connect and start using:

use UsmanZahid\N8n\N8nClient;

N8nClient::connect(
    'https://your-n8n-instance.com',
    'your-api-key'
);

// Get all users
$response = N8nClient::users()->listUsers();

if ($response->success) {
    foreach ($response->data->items as $user) {
        echo $user->email . PHP_EOL;
    }
}

That's it. You're ready to go.

Installation
Configuration
Understanding Responses
Working with Workflows
Working with Webhooks
Working with Users
Working with Tags
Working with Variables
Working with Projects
Working with Executions
Working with Credentials
Working with Audit
Pagination
Contributing
License

Installation

composer require usmanzahid/n8n-php

Requires PHP 7.4 or higher.

Configuration

Before making any requests, connect to your n8n instance:

use UsmanZahid\N8n\N8nClient;

N8nClient::connect(
    'https://your-n8n-instance.com',  // Your n8n instance URL
    'your-api-key'                     // Your n8n API key
);

Optional webhook authentication:

N8nClient::connect(
    'https://your-n8n-instance.com',
    'your-api-key',
    'webhook-username',  // Optional
    'webhook-password'   // Optional
);

Understanding Responses

Every method returns an N8nResponse object with these properties:

$response->success;    // bool: true if successful, false otherwise
$response->data;       // object: The actual data returned (workflows, users, etc.)
$response->message;    // string: Error message if something went wrong
$response->statusCode; // int: HTTP status code

Always check for success:

$response = N8nClient::workflows()->getWorkflow('workflow-id');

if ($response->success) {
    $workflow = $response->data;
    // Use the workflow
} else {
    echo "Error: " . $response->message;
}

No exceptions are thrown. Everything is handled through the response object.

Working with Workflows

List workflows

// Get first page (default: 20 workflows)
$response = N8nClient::workflows()->listWorkflows();

// Get with custom limit
$response = N8nClient::workflows()->listWorkflows(['limit' => 50]);

Get all workflows (handles pagination automatically)

$response = N8nClient::workflows()->listWorkflowsAll();

if ($response->success) {
    foreach ($response->data->items as $workflow) {
        echo $workflow->name . PHP_EOL;
    }
}

Get a single workflow

$response = N8nClient::workflows()->getWorkflow('workflow-id');

Create a workflow

$response = N8nClient::workflows()->createWorkflow([
    'name' => 'My New Workflow',
    'nodes' => [],
    'connections' => []
]);

Update a workflow

$response = N8nClient::workflows()->updateWorkflow('workflow-id', [
    'name' => 'Updated Workflow Name'
]);

Delete a workflow

$response = N8nClient::workflows()->deleteWorkflow('workflow-id');

Activate or deactivate

N8nClient::workflows()->activateWorkflow('workflow-id');
N8nClient::workflows()->deactivateWorkflow('workflow-id');

Transfer to another project

N8nClient::workflows()->transferWorkflow('workflow-id', 'destination-project-id');

Manage workflow tags

// Get tags
$response = N8nClient::workflows()->getTags('workflow-id');

// Update tags (provide array of tag IDs)
N8nClient::workflows()->updateTags('workflow-id', ['tag-id-1', 'tag-id-2']);

Working with Webhooks

Trigger webhooks programmatically:

use UsmanZahid\N8n\Enums\WebhookMode;
use UsmanZahid\N8n\Enums\RequestMethod;

$response = N8nClient::webhook(WebhookMode::Production, RequestMethod::Post)
    ->send('your-webhook-id', [
        'key' => 'value',
        'data' => 'your data here'
    ]);

if ($response->success) {
    echo "Webhook triggered successfully!";
}

Webhook modes:

WebhookMode::Production - Live workflows
WebhookMode::Test - Test mode webhooks

Request methods:

RequestMethod::Get
RequestMethod::Post
RequestMethod::Put
RequestMethod::Patch
RequestMethod::Delete

Working with Users

List users

$response = N8nClient::users()->listUsers();

Get all users

$response = N8nClient::users()->listUsersAll();

Create a user

$response = N8nClient::users()->createUser([
    [
        'email' => 'newuser@example.com',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'role' => 'member'
    ]
]);

Get a user

$response = N8nClient::users()->getUser('user@example.com');

Delete a user

$response = N8nClient::users()->deleteUser('user@example.com');

Change user role

$response = N8nClient::users()->changeUserRole('user@example.com', 'admin');

Available roles: member, admin, owner

Working with Tags

List tags

$response = N8nClient::tags()->listTags();

Get all tags

$response = N8nClient::tags()->listTagsAll();

Create a tag

$response = N8nClient::tags()->createTag([
    'name' => 'Production'
]);

Get a tag

$response = N8nClient::tags()->getTag('tag-id');

Update a tag

$response = N8nClient::tags()->updateTag('tag-id', [
    'name' => 'Updated Tag Name'
]);

Delete a tag

$response = N8nClient::tags()->deleteTag('tag-id');

Working with Variables

List variables

$response = N8nClient::variables()->listVariables();

Get all variables

$response = N8nClient::variables()->listVariablesAll();

Create a variable

$response = N8nClient::variables()->createVariable([
    'key' => 'API_KEY',
    'value' => 'secret-value'
]);

Update a variable

$response = N8nClient::variables()->updateVariable('variable-id', [
    'value' => 'new-secret-value'
]);

Delete a variable

$response = N8nClient::variables()->deleteVariable('variable-id');

Working with Projects

List projects

$response = N8nClient::projects()->listProjects();

Get all projects

$response = N8nClient::projects()->listProjectsAll();

Create a project

$response = N8nClient::projects()->createProject([
    'name' => 'My New Project'
]);

Update a project

$response = N8nClient::projects()->updateProject('project-id', [
    'name' => 'Updated Project Name'
]);

Delete a project

$response = N8nClient::projects()->deleteProject('project-id');

Add users to a project

$response = N8nClient::projects()->addUsers('project-id', [
    [
        'userId' => 'user-id-1',
        'role' => 'member'
    ],
    [
        'userId' => 'user-id-2',
        'role' => 'admin'
    ]
]);

Change user role in a project

$response = N8nClient::projects()->changeUserRole('project-id', 'user-id', 'admin');

Remove user from a project

$response = N8nClient::projects()->deleteUser('project-id', 'user-id');

Working with Executions

List executions

// Get first 10 executions
$response = N8nClient::executions()->listExecutions(10);

Get all executions

$response = N8nClient::executions()->listExecutionsAll();

Get a single execution

$response = N8nClient::executions()->getExecution('execution-id');

Delete an execution

$response = N8nClient::executions()->deleteExecution('execution-id');

Stop a running execution

$response = N8nClient::executions()->stopExecution('execution-id');

Retry a failed execution

$response = N8nClient::executions()->retryExecution('execution-id', [
    'inputData' => []  // Optional custom input data
]);

Working with Credentials

Get credential schema

$response = N8nClient::credentials()->getCredentialSchema('githubApi');

Create a credential

$response = N8nClient::credentials()->createCredential([
    'name' => 'My GitHub Token',
    'type' => 'githubApi',
    'data' => [
        'token' => 'your-github-token'
    ]
]);

Delete a credential

$response = N8nClient::credentials()->deleteCredential('credential-id');

Working with Audit

Generate audit logs:

$response = N8nClient::audit()->generateAudit([
    'action' => 'workflow_created',
    'additionalData' => []
]);

Pagination

Most list methods support pagination. There are three ways to handle it:

1. Manual pagination with limits

$response = N8nClient::workflows()->listWorkflows(['limit' => 10]);

2. Get all items automatically

$response = N8nClient::workflows()->listWorkflowsAll();
// Fetches all pages automatically

3. Manual page appending

$response = N8nClient::tags()->listTags();

$tagList = $response->data;
$tagsClient = N8nClient::tags();

// Check if more pages exist
while ($tagsClient->hasMore($tagList)) {
    // Append next page to existing list
    $tagsClient->appendNextTagPage($tagList);
}

// Now $tagList contains all tags from all pages
foreach ($tagList->items as $tag) {
    echo $tag->name . PHP_EOL;
}

Available append methods:

appendNextWorkflowPage()
appendNextUserPage()
appendNextTagPage()
appendNextVariablePage()
appendNextProjectPage()
appendNextExecutionPage()

Contributing

Contributions are welcome! If you have ideas, find bugs, or want to add features:

Fork this repository
Create your feature branch
Submit a pull request

Every contribution helps make this SDK better for the PHP community.

License

Why This Exists

I needed a clean way to integrate n8n into my PHP projects. Instead of writing the same API calls over and over, I built this SDK to make n8n integration simple and straightforward for PHP developers.

It's feature-complete for core use cases and ready for production. If you find it useful, star the repo and share it with others!

usmanzahid / n8n-php

Maintainers

Details