Skip to content

Commit 02cd2d5

Browse files
kayedspacekayedspace
committed
Initial commit
0 parents  commit 02cd2d5

19 files changed

+1025
-0
lines changed

‎.gitignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
composer.lock
2+
vendor
3+
tests/temp
4+
.idea
5+
.phpunit.cache
6+
.phpunit.result.cache
7+
.php-cs-fixer.cache

‎LICENCE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Ali Youssef Kayed
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎composer.json

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"name": "kayedspace/laravel-n8n",
3+
"description": "A complete, expressive, and fluent Laravel client for the n8n public REST API and Webhooks Triggering.",
4+
"type": "library",
5+
"keywords": [
6+
"n8n",
7+
"workflow",
8+
"automation",
9+
"webhook",
10+
"laravel"
11+
],
12+
"support": {
13+
"issues": "https://github.com/kayedspace/laravel-n8n/issues",
14+
"source": "https://github.com/kayedspace/laravel-n8n"
15+
},
16+
"authors": [
17+
{
18+
"name": "Ali Youssef Kayed",
19+
"email": "[email protected]"
20+
}
21+
],
22+
"license": "MIT",
23+
"autoload": {
24+
"psr-4": {
25+
"KayedSpace\\N8n\\": "src/"
26+
}
27+
},
28+
"extra": {
29+
"laravel": {
30+
"providers": [
31+
"KayedSpace\\N8n\\N8nServiceProvider"
32+
],
33+
"aliases": {
34+
"N8nClient": "KayedSpace\\N8n\\Facades\\N8nClient"
35+
}
36+
}
37+
},
38+
"require": {
39+
"php": ">=8.2",
40+
"illuminate/support": ">=10",
41+
"illuminate/http": ">=10"
42+
}
43+
}

‎config/n8n.php

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?php
2+
3+
return [
4+
'api' => [
5+
'base_url' => env('N8N_API_BASE_URL'),
6+
'key' => env('N8N_API_KEY'),
7+
],
8+
'webhook' => [
9+
'base_url' => env('N8N_WEBHOOK_BASE_URL'),
10+
'username' => env('N8N_WEBHOOK_USERNAME'),
11+
'password' => env('N8N_WEBHOOK_PASSWORD'),
12+
],
13+
'timeout' => env('N8N_TIMEOUT',120),
14+
'throw' => env('N8N_THROW',true),
15+
'retry' => env('N8N_RETRY',3),
16+
];

‎readme.md

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# n8n Laravel Client
2+
3+
A complete, expressive, and fluent Laravel client for the n8n public REST API and Webhooks Triggering, empowering PHP
4+
developers to interact
5+
seamlessly with n8n webhooks, workflows, executions, credentials, tags, users, variables, projects, and source control
6+
operations.
7+
8+
## Table of Contents
9+
10+
* [📦 Installation](#-installation)
11+
* [⚙️ Configuration](#-configuration)
12+
* [🚀 Quick Start](#-quick-start)
13+
* [⚡ Webhooks Trigger](#-webhooks-trigger)
14+
* [📚 Full API Resource Reference](#-full-api-resource-reference)
15+
* [🕵 Audit](#-audit)
16+
* [🔑 Credentials](#-credentials)
17+
* [⏯️ Executions](#-executions)
18+
* [🚧 Projects](#-projects)
19+
* [📝 Source Control](#-source-control)
20+
* [🏷️ Tags](#-tags)
21+
* [🙍 Users](#-users)
22+
* [🔠 Variables](#-variables)
23+
* [🔄 Workflows](#-workflows)
24+
* [🤝 Contributing](#-contributing)
25+
* [🛠 Support](#-support)
26+
* [📄 License](#-license)
27+
28+
## 📦 Installation
29+
30+
Install via Composer:
31+
32+
```bash
33+
composer require kayedspace/n8n-laravel
34+
```
35+
36+
Service providers and facades are auto-discovered by Laravel.
37+
38+
## ⚙️ Configuration
39+
40+
Publish and customize the configuration file:
41+
42+
```bash
43+
php artisan vendor:publish --tag=n8n-config
44+
```
45+
46+
Set environment variables in .env:
47+
48+
```dotenv
49+
N8N_TIMEOUT=120
50+
N8N_THROW=true
51+
N8N_RETRY=3
52+
53+
N8N_BASE_URI=https://your-n8n-instance.com/api/v1
54+
N8N_API_KEY=your_api_key
55+
56+
N8N_WEBHOOK_BASE_URI=https://your-n8n-instance.com/webhook
57+
N8N_WEBHOOK_USERNAME==your_webhook_username
58+
N8N_WEBHOOK_PASSWORD=your_webhook_password
59+
```
60+
61+
## 🚀 Quick Start
62+
63+
```php
64+
use N8nClient;
65+
66+
// trigger webhook
67+
$webhookTrigger =N8nClient::webhooks()->trigger("path-to-webhook",$payload);
68+
69+
// List all workflows
70+
$workflows = N8nClient::workflows()->list();
71+
72+
73+
// Retrieve execution status with data
74+
$status = N8nClient::executions()->get($execution['id'], includeData: true);
75+
76+
```
77+
78+
## ⚡ Webhooks Trigger
79+
80+
The Webhooks class enables sending HTTP requests to n8n workflow webhook trigger URLs, supporting multiple HTTP verbs (
81+
GET, POST, etc.) and basic authentication (if configured).
82+
83+
## 📚 Full API Resource Reference
84+
85+
Below is an exhaustive reference covering every resource and method provided.
86+
87+
### 🕵 Audit
88+
89+
| Method | Description | HTTP Method & Path |
90+
|-------------------------------------------|----------------------------------------------------------------------|--------------------|
91+
| `generate(array $additionalOptions = [])` | Generate a full audit report based on optional categories or filters | `POST /audit` |
92+
93+
**Description:**
94+
This endpoint performs a security audit of your n8n instance and returns diagnostics grouped by category. It must be
95+
invoked by an account with owner privileges.
96+
97+
### 🔑 Credentials
98+
99+
| Method Signature | HTTP Method & Path | Description |
100+
|------------------------------------------------------|--------------------------------------|--------------------------------------------------------|
101+
| `create(array $payload)` | `POST /credentials` | Create a credential using the appropriate type schema. |
102+
| `list(int $limit = 100, ?string $cursor = null)` | `GET /credentials` | List stored credentials with optional pagination. |
103+
| `get(string $id)` | `GET /credentials/{id}` | Retrieve details of a specific credential by ID. |
104+
| `delete(string $id)` | `DELETE /credentials/{id}` | Delete a credential permanently. |
105+
| `schema(string $typeName)` | `GET /credentials/schema/{typeName}` | Get the schema definition for a credential type. |
106+
| `transfer(string $id, string $destinationProjectId)` | `PUT /credentials/{id}/transfer` | Move a credential to another project using its ID. |
107+
108+
**Example:**
109+
110+
```php
111+
$schema = $n8n->credentials()->schema('slackApi');
112+
113+
$n8n->credentials()->create([
114+
'name' => 'Slack Token',
115+
'type' => 'slackApi',
116+
'data' => [
117+
'token' => 'xoxb-123456789',
118+
]
119+
]);
120+
```
121+
122+
### ⏯️ Executions
123+
124+
| Method Signature | HTTP Method & Path | Description |
125+
|-------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
126+
| `list(array $filters = [])` | `GET /executions` | Retrieve a paginated list of workflow executions. Supports filters such as `status`, `workflowId`, `projectId`, `includeData`, `limit`, `cursor`. |
127+
| `get(int $id, bool $includeData = false)` | `GET /executions/{id}` | Retrieve detailed information for a specific execution. Optionally include execution data. |
128+
| `delete(int $id)` | `DELETE /executions/{id}` | Delete an execution record by ID. |
129+
130+
**Example:**
131+
132+
```php
133+
// Get a list of executions filtered by status
134+
$executions = $n8n->executions()->list(['status' => 'success']);
135+
136+
// Get detailed execution data
137+
$execution = $n8n->executions()->get(101, true);
138+
139+
// Delete an execution
140+
$n8n->executions()->delete(101);
141+
```
142+
143+
### 🚧 Projects
144+
145+
| Method Signature | HTTP Method & Path | Description |
146+
|-------------------------------------------------------------------|-----------------------------------------------|------------------------------------------------------------------------|
147+
| `create(array $payload)` | `POST /projects` | Create a new project with name, description, etc. |
148+
| `list(int $limit = 100, ?string $cursor = null)` | `GET /projects` | Retrieve a paginated list of projects. |
149+
| `update(string $projectId, array $payload)` | `PUT /projects/{projectId}` | Update project name or metadata. Returns 204 No Content on success. |
150+
| `delete(string $projectId)` | `DELETE /projects/{projectId}` | Delete a project by ID. Returns 204 No Content on success. |
151+
| `addUsers(string $projectId, array $relations)` | `POST /projects/{projectId}/users` | Add users to a project with specified roles via the `relations` array. |
152+
| `changeUserRole(string $projectId, string $userId, string $role)` | `PATCH /projects/{projectId}/users/{userId}` | Change the role of an existing user within a project. |
153+
| `removeUser(string $projectId, string $userId)` | `DELETE /projects/{projectId}/users/{userId}` | Remove a user from a project. |
154+
155+
**Example Usage:**
156+
157+
```php
158+
// Create a project
159+
$project = $n8n->projects()->create(['name' => 'DevOps', 'description' => 'CI/CD flows']);
160+
161+
// Add users
162+
$n8n->projects()->addUsers($project['id'], [
163+
['userId' => 'abc123', 'role' => 'member'],
164+
]);
165+
166+
// Promote user role
167+
$n8n->projects()->changeUserRole($project['id'], 'abc123', 'admin');
168+
169+
// Delete the project
170+
$n8n->projects()->delete($project['id']);
171+
```
172+
173+
### 📝 Source Control
174+
175+
| Method Signature | HTTP Method & Path | Description |
176+
|------------------------|-----------------------------|--------------------------------------------------------------------------|
177+
| `pull(array $payload)` | `POST /source-control/pull` | Trigger a pull operation from the connected Git source for all projects. |
178+
179+
**Example:**
180+
181+
```php
182+
$syncStatus = $n8n->sourceControl()->pull([
183+
'projectIds' => ['project-1', 'project-2'],
184+
]);
185+
```
186+
187+
> Requires source control integration to be configured in the n8n instance.
188+
189+
### 🏷️ Tags
190+
191+
| Method Signature | HTTP Method & Path | Description |
192+
|--------------------------------------------------|---------------------|------------------------------------------------------------|
193+
| `create(array $payload)` | `POST /tags` | Create a new tag with the given name or properties. |
194+
| `list(int $limit = 100, ?string $cursor = null)` | `GET /tags` | List all tags with optional pagination using limit/cursor. |
195+
| `get(string $id)` | `GET /tags/{id}` | Retrieve a single tag by its ID. |
196+
| `update(string $id, array $payload)` | `PUT /tags/{id}` | Update the name or properties of a specific tag. |
197+
| `delete(string $id)` | `DELETE /tags/{id}` | Delete a tag permanently by its ID. |
198+
199+
**Example:**
200+
201+
```php
202+
$tag = $n8n->tags()->create(['name' => 'Marketing']);
203+
$updated = $n8n->tags()->update($tag['id'], ['name' => 'Sales']);
204+
$all = $n8n->tags()->list();
205+
```
206+
207+
### 🙍 Users
208+
209+
| Method Signature | HTTP Method & Path | Description |
210+
|------------------------------------------------------|---------------------------------|----------------------------------------------------------------------------------|
211+
| `list(array $filters = [])` | `GET /users` | List users with optional filters: `limit`, `cursor`, `includeRole`, `projectId`. |
212+
| `create(array $userPayloads)` | `POST /users` | Create (invite) one or more users by providing user objects. |
213+
| `get(string $idOrEmail, bool $includeRole = false)` | `GET /users/{idOrEmail}` | Get a user by ID or email. Optionally include role. |
214+
| `delete(string $idOrEmail)` | `DELETE /users/{idOrEmail}` | Delete a user by ID or email. |
215+
| `changeRole(string $idOrEmail, string $newRoleName)` | `PATCH /users/{idOrEmail}/role` | Change the user's role to the new role name. |
216+
217+
**Example:**
218+
219+
```php
220+
// Invite users
221+
$n8n->users()->create([
222+
['email' => '[email protected]', 'role' => 'member']
223+
]);
224+
225+
// Promote to admin
226+
$n8n->users()->changeRole('[email protected]', 'admin');
227+
```
228+
229+
### 🔠 Variables
230+
231+
| Method Signature | HTTP Method & Path | Description |
232+
|--------------------------------------------------|--------------------------|-----------------------------------------------------------------|
233+
| `create(array $payload)` | `POST /variables` | Create a new variable with a key-value pair. |
234+
| `list(int $limit = 100, ?string $cursor = null)` | `GET /variables` | List variables with optional pagination using limit and cursor. |
235+
| `update(string $id, array $payload)` | `PUT /variables/{id}` | Update the value of an existing variable. |
236+
| `delete(string $id)` | `DELETE /variables/{id}` | Permanently delete a variable. |
237+
238+
**Example:**
239+
240+
```php
241+
// Create a new variable
242+
$n8n->variables()->create(['key' => 'ENV_MODE', 'value' => 'production']);
243+
244+
// Update the variable
245+
$n8n->variables()->update('ENV_MODE', ['value' => 'staging']);
246+
247+
// Delete the variable
248+
$n8n->variables()->delete('ENV_MODE');
249+
```
250+
251+
### 🔄 Workflows
252+
253+
| Method Signature | HTTP Method & Path | Description |
254+
|------------------------------------------------------|-----------------------------------|---------------------------------------------------------------------------|
255+
| `create(array $payload)` | `POST /workflows` | Create a new workflow using a flow definition. |
256+
| `list(array $filters = [])` | `GET /workflows` | List workflows with optional filters: `active`, `tags`, `projectId`, etc. |
257+
| `get(string $id, bool $excludePinnedData = false)` | `GET /workflows/{id}` | Retrieve a specific workflow; optionally exclude pinned node data. |
258+
| `update(string $id, array $payload)` | `PUT /workflows/{id}` | Update the workflow definition. |
259+
| `delete(string $id)` | `DELETE /workflows/{id}` | Delete the specified workflow. |
260+
| `activate(string $id)` | `POST /workflows/{id}/activate` | Activate the workflow. |
261+
| `deactivate(string $id)` | `POST /workflows/{id}/deactivate` | Deactivate the workflow. |
262+
| `transfer(string $id, string $destinationProjectId)` | `PUT /workflows/{id}/transfer` | Move a workflow to a different project. |
263+
| `tags(string $id)` | `GET /workflows/{id}/tags` | Get all tags associated with the workflow. |
264+
| `updateTags(string $id, array $tagIds)` | `PUT /workflows/{id}/tags` | Update the list of tag IDs for a workflow. |
265+
266+
**Example:**
267+
268+
```php
269+
// Create and activate a workflow
270+
$wf = $n8n->workflows()->create([...]);
271+
$n8n->workflows()->activate($wf['id']);
272+
273+
```
274+
275+
## 🤝 Contributing
276+
277+
Contributions are welcome! If you have a feature request, bug report, or improvement:
278+
279+
1. Fork the repository
280+
2. Create your feature branch: `git checkout -b feature/my-feature`
281+
3. Commit your changes: `git commit -am 'Add new feature'`
282+
4. Push to the branch: `git push origin feature/my-feature`
283+
5. Open a pull request
284+
285+
Please adhere to PSR-12 and include tests where applicable.
286+
287+
## 🛠 Support
288+
289+
If you encounter any issues or have questions:
290+
291+
* Open an issue on the GitHub repository
292+
* Use Discussions for non-bug topics or feature proposals
293+
* Pull requests are always welcome for fixes and improvements
294+
*
295+
296+
## 📄 License
297+
298+
This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)