From 781b49ee75b327dbdc4f6df25660a3482266f11f Mon Sep 17 00:00:00 2001
From: Micilini Roll <micilini@hotmail.com>
Date: Sat, 9 May 2026 21:15:36 -0300
Subject: [PATCH] fix examples autoload when installed through composer

---
 README.md                                     | 23 +++++++++
 examples/bootstrap.php                        | 31 +++++++++++
 examples/easy-chat/server.php                 |  2 +-
 examples/medium-chat/server.php               |  2 +-
 examples/private-chat/server.php              |  2 +-
 .../Examples/ExampleServerAutoloadTest.php    | 51 +++++++++++++++++++
 6 files changed, 108 insertions(+), 3 deletions(-)
 create mode 100644 examples/bootstrap.php
 create mode 100644 tests/Unit/Examples/ExampleServerAutoloadTest.php

diff --git a/README.md b/README.md
index 9a7204b..69120e7 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,8 @@ ws://127.0.0.1:8080
 
 ## Running the Examples
 
+> The example servers can be executed both from a cloned repository and from a project where the package was installed through Composer. The examples use `examples/bootstrap.php` to locate the correct Composer autoload file automatically.
+
 Each example has two parts:
 
 1. a WebSocket server process;
@@ -164,6 +166,13 @@ Open another terminal and serve the UI:
 php -S 127.0.0.1:8000 -t examples/easy-chat/public
 ```
 
+If you installed the package inside another project with Composer, run:
+
+```bash
+php vendor/micilini/php-websockets/examples/easy-chat/server.php
+php -S 127.0.0.1:8000 -t vendor/micilini/php-websockets/examples/easy-chat/public
+```
+
 Open:
 
 ```txt
@@ -196,6 +205,13 @@ Open another terminal and serve the UI:
 php -S 127.0.0.1:8001 -t examples/medium-chat/public
 ```
 
+If you installed the package inside another project with Composer, run:
+
+```bash
+php vendor/micilini/php-websockets/examples/medium-chat/server.php
+php -S 127.0.0.1:8001 -t vendor/micilini/php-websockets/examples/medium-chat/public
+```
+
 Open:
 
 ```txt
@@ -226,6 +242,13 @@ Open another terminal and serve the UI:
 php -S 127.0.0.1:8002 -t examples/private-chat/public
 ```
 
+If you installed the package inside another project with Composer, run:
+
+```bash
+php vendor/micilini/php-websockets/examples/private-chat/server.php
+php -S 127.0.0.1:8002 -t vendor/micilini/php-websockets/examples/private-chat/public
+```
+
 Open:
 
 ```txt
diff --git a/examples/bootstrap.php b/examples/bootstrap.php
new file mode 100644
index 0000000..8567cbb
--- /dev/null
+++ b/examples/bootstrap.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+$autoloadCandidates = [
+    // Repository clone:
+    // php-websockets/vendor/autoload.php
+    __DIR__ . '/../vendor/autoload.php',
+
+    // Composer package install:
+    // project/vendor/micilini/php-websockets/examples/../../../autoload.php
+    __DIR__ . '/../../../autoload.php',
+
+    // Fallback when executed from the consumer project root:
+    // project/vendor/autoload.php
+    getcwd() . '/vendor/autoload.php',
+];
+
+foreach ($autoloadCandidates as $autoload) {
+    if (is_file($autoload)) {
+        require_once $autoload;
+
+        return;
+    }
+}
+
+throw new RuntimeException(
+    'Composer autoload file was not found. '
+    . 'Run "composer install" in the repository root, '
+    . 'or install micilini/php-websockets through Composer before running the examples.'
+);
diff --git a/examples/easy-chat/server.php b/examples/easy-chat/server.php
index d568e35..098d70b 100644
--- a/examples/easy-chat/server.php
+++ b/examples/easy-chat/server.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-require __DIR__ . '/../../vendor/autoload.php';
+require __DIR__ . '/../bootstrap.php';
 
 use Micilini\PhpSockets\Chat\ChatServer;
 use Micilini\PhpSockets\Config\ChatConfig;
diff --git a/examples/medium-chat/server.php b/examples/medium-chat/server.php
index ed82d98..f1b7ec1 100644
--- a/examples/medium-chat/server.php
+++ b/examples/medium-chat/server.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-require __DIR__ . '/../../vendor/autoload.php';
+require __DIR__ . '/../bootstrap.php';
 
 use Micilini\PhpSockets\Chat\ChatMessage;
 use Micilini\PhpSockets\Chat\ChatServer;
diff --git a/examples/private-chat/server.php b/examples/private-chat/server.php
index 1b115da..a167df6 100644
--- a/examples/private-chat/server.php
+++ b/examples/private-chat/server.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-require __DIR__ . '/../../vendor/autoload.php';
+require __DIR__ . '/../bootstrap.php';
 require __DIR__ . '/bots/EchoBot.php';
 require __DIR__ . '/bots/HelpBot.php';
 
diff --git a/tests/Unit/Examples/ExampleServerAutoloadTest.php b/tests/Unit/Examples/ExampleServerAutoloadTest.php
new file mode 100644
index 0000000..e82797f
--- /dev/null
+++ b/tests/Unit/Examples/ExampleServerAutoloadTest.php
@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Micilini\PhpSockets\Tests\Unit\Examples;
+
+use PHPUnit\Framework\TestCase;
+
+final class ExampleServerAutoloadTest extends TestCase
+{
+    public function testExamplesHaveSharedBootstrapFile(): void
+    {
+        self::assertFileExists(__DIR__ . '/../../../examples/bootstrap.php');
+    }
+
+    public function testExampleServersUseSharedBootstrapInsteadOfLocalVendorAutoload(): void
+    {
+        $serverFiles = [
+            __DIR__ . '/../../../examples/easy-chat/server.php',
+            __DIR__ . '/../../../examples/medium-chat/server.php',
+            __DIR__ . '/../../../examples/private-chat/server.php',
+        ];
+
+        foreach ($serverFiles as $serverFile) {
+            self::assertFileExists($serverFile);
+
+            $contents = (string) file_get_contents($serverFile);
+
+            self::assertStringContainsString(
+                "require __DIR__ . '/../bootstrap.php';",
+                $contents,
+                "{$serverFile} should use the shared examples bootstrap.",
+            );
+
+            self::assertStringNotContainsString(
+                '/../../vendor/autoload.php',
+                $contents,
+                "{$serverFile} should not assume a local package vendor directory.",
+            );
+        }
+    }
+
+    public function testSharedBootstrapSupportsRepositoryAndComposerInstallPaths(): void
+    {
+        $bootstrap = (string) file_get_contents(__DIR__ . '/../../../examples/bootstrap.php');
+
+        self::assertStringContainsString("__DIR__ . '/../vendor/autoload.php'", $bootstrap);
+        self::assertStringContainsString("__DIR__ . '/../../../autoload.php'", $bootstrap);
+        self::assertStringContainsString("getcwd() . '/vendor/autoload.php'", $bootstrap);
+    }
+}