fix examples autoload when installed through composer

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

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.'
+);

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;

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;

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';
 

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);
+    }
+}