feat: support usage as Composer dependency (bin script, path resolution, Accept header)

  - Add bin/openapi-mock-server with autoloader detection for standalone and dependency usage
  - Resolve relative OPENAPI_SPEC paths from getcwd() when installed as dependency, from package root when standalone
  - Replace Content-Type based response generation with Accept header content negotiation, enabling correct Content-Type for
  application/ld+json and other non-default media types

Author: Fahl-Design

bin/openapi-mock-server

@@ -0,0 +1,56 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+use Mezzio\Application;
+use Mezzio\MiddlewareFactory;
+use Psr\Container\ContainerInterface;
+
+(static function (): void {
+    // Find the Composer autoloader (works both standalone and as dependency)
+    $autoloadPaths = [
+        __DIR__ . '/../../../autoload.php',   // installed as dependency: vendor/webproject-xyz/php-openapi-mock-server/bin/
+        __DIR__ . '/../vendor/autoload.php',  // standalone: project-root/bin/
+    ];
+
+    $autoloaderFound = false;
+    foreach ($autoloadPaths as $autoloadPath) {
+        if (file_exists($autoloadPath)) {
+            require $autoloadPath;
+            $autoloaderFound = true;
+            break;
+        }
+    }
+
+    if (! $autoloaderFound) {
+        fwrite(STDERR, 'Could not find Composer autoloader. Please run "composer install".' . PHP_EOL);
+        exit(1);
+    }
+
+    // Resolve relative OPENAPI_SPEC paths to absolute from the current working directory
+    $specPath = getenv('OPENAPI_SPEC');
+    if ($specPath !== false && $specPath !== '' && ! str_starts_with($specPath, '/') && ! str_starts_with($specPath, 'http')) {
+        putenv('OPENAPI_SPEC=' . getcwd() . '/' . $specPath);
+    }
+
+    // Optional Codeception coverage collector
+    $c3Path = dirname(__DIR__) . '/c3.php';
+    if (file_exists($c3Path)) {
+        require $c3Path;
+    }
+
+    /** @var ContainerInterface $container */
+    $container = require dirname(__DIR__) . '/config/container.php';
+
+    /** @var Application $app */
+    $app = $container->get(Application::class);
+
+    /** @var MiddlewareFactory $factory */
+    $factory = $container->get(MiddlewareFactory::class);
+
+    (require dirname(__DIR__) . '/config/pipeline.php')($app, $factory);
+    (require dirname(__DIR__) . '/config/routes.php')($app, $factory);
+
+    $app->run();
+})();

composer.json

@@ -51,6 +51,9 @@
     "slam/phpstan-laminas-framework": "^2.0",
     "webproject-xyz/codeception-module-ai-reporter": "^1.0.1"
   },
+  "bin": [
+    "bin/openapi-mock-server"
+  ],
   "autoload": {
     "psr-4": {
       "WebProject\\PhpOpenApiMockServer\\": "src/"

composer.lock

@@ -11,15 +11,21 @@
 use WebProject\PhpOpenApiMockServer\Middleware\MockMiddleware\Utils\RemoteSpecificationLoader;
 
 return static function (Application $application, MiddlewareFactory $middlewareFactory): void {
-    $specPath = getenv('OPENAPI_SPEC') ?: 'data/openapi.yaml';
-    $projectRoot = realpath(__DIR__ . '/..') ?: '/app';
+    $specPath = getenv('OPENAPI_SPEC') ?: null;
+    $packageRoot = realpath(__DIR__ . '/..') ?: '/app';
 
-    $specHandler = static function (ServerRequestInterface $serverRequest) use ($specPath, $projectRoot): ResponseInterface {
+    if ($specPath === null || $specPath === false) {
+        $specPath = $packageRoot . '/data/openapi.yaml';
+    } elseif (!str_starts_with((string) $specPath, '/') && !str_starts_with((string) $specPath, 'http')) {
+        $resolveBase = str_contains($packageRoot, DIRECTORY_SEPARATOR . 'vendor' . DIRECTORY_SEPARATOR)
+            ? (getcwd() ?: '.')
+            : $packageRoot;
+        $specPath = $resolveBase . DIRECTORY_SEPARATOR . $specPath;
+    }
+
+    $specHandler = static function (ServerRequestInterface $serverRequest) use ($specPath): ResponseInterface {
         try {
             $path = $specPath;
-            if (!str_starts_with((string) $path, '/') && !str_starts_with((string) $path, 'http')) {
-                $path = $projectRoot . DIRECTORY_SEPARATOR . $path;
-            }
 
             if (str_starts_with((string) $path, 'http')) {
                 $content = file_get_contents($path, false, RemoteSpecificationLoader::createStreamContext());

config/routes.php

@@ -20,8 +20,10 @@
 
 use function dirname;
 use function file_get_contents;
+use function getcwd;
 use function getenv;
 use function sprintf;
+use function str_contains;
 use function str_ends_with;
 use function str_starts_with;
 
@@ -31,15 +33,21 @@ class OpenApiMockMiddlewareFactory
 {
     public function __invoke(ContainerInterface $container): MiddlewareInterface
     {
-        $projectRoot = dirname(__DIR__, 2);
+        $packageRoot = dirname(__DIR__, 2);
         /** @var array{openapi_mock?: array{spec?: string, validate_request?: bool, validate_response?: bool}} $config */
         $config      = $container->has('config') ? (array) $container->get('config') : [];
         $mockConfig  = (array) ($config['openapi_mock'] ?? []);
-        $specPath    = $mockConfig['spec'] ?? getenv('OPENAPI_SPEC') ?: $projectRoot . '/data/openapi.yaml';
+        $specPath    = $mockConfig['spec'] ?? getenv('OPENAPI_SPEC') ?: null;
 
-        // Ensure absolute path if relative and not a URL
-        if (! str_starts_with((string) $specPath, '/') && ! str_starts_with((string) $specPath, 'http')) {
-            $specPath = $projectRoot . DIRECTORY_SEPARATOR . $specPath;
+        if ($specPath === null) {
+            // No spec configured — use default from the package itself
+            $specPath = $packageRoot . '/data/openapi.yaml';
+        } elseif (! str_starts_with((string) $specPath, '/') && ! str_starts_with((string) $specPath, 'http')) {
+            // Relative paths: resolve from cwd when installed as dependency, package root otherwise
+            $resolveBase = str_contains($packageRoot, DIRECTORY_SEPARATOR . 'vendor' . DIRECTORY_SEPARATOR)
+                ? (getcwd() ?: '.')
+                : $packageRoot;
+            $specPath = $resolveBase . DIRECTORY_SEPARATOR . $specPath;
         }
 
         $openApiMockMiddlewareConfig = new OpenApiMockMiddlewareConfig(

src/Factory/OpenApiMockMiddlewareFactory.php

@@ -23,6 +23,7 @@
 use Webmozart\Assert\Assert;
 
 use function array_key_exists;
+use function array_keys;
 
 final class OpenAPIFaker
 {
@@ -164,6 +165,26 @@ public function setOptions(array $options): self
         return $this;
     }
 
+    /**
+     * @return list<string>
+     */
+    public function getAvailableResponseContentTypes(
+        string $path,
+        string $method,
+        string $statusCode = '200',
+    ): array {
+        $operation = $this->findOperation($path, HttpMethod::fromString($method));
+
+        if ($operation->responses === null || ! $operation->responses->hasResponse($statusCode)) {
+            return [];
+        }
+
+        /** @var Response $response */
+        $response = $operation->responses->getResponse($statusCode);
+
+        return array_keys($response->content);
+    }
+
     private function findOperation(string $path, HttpMethod $httpMethod): Operation
     {
         try {

src/Middleware/MockMiddleware/Faker/OpenAPIFaker.php

@@ -8,14 +8,21 @@
 use WebProject\PhpOpenApiMockServer\Middleware\MockMiddleware\Response\ResponseHandler;
 use WebProject\PhpOpenApiMockServer\Middleware\MockMiddleware\Validator\RequestValidator;
 use WebProject\PhpOpenApiMockServer\Middleware\MockMiddleware\Validator\ResponseValidator;
-use Exception;
+use function array_map;
+use function array_slice;
+use function explode;
 use const FILTER_VALIDATE_BOOLEAN;
 use function filter_var;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
+use function str_contains;
+use function str_starts_with;
+use function substr;
 use Throwable;
+use function trim;
+use function usort;
 
 class OpenApiMockMiddleware implements MiddlewareInterface
 {
@@ -25,7 +32,7 @@ class OpenApiMockMiddleware implements MiddlewareInterface
 
     public const string HEADER_OPENAPI_MOCK_EXAMPLE    = 'X-OpenApi-Mock-Example';
 
-    public const string HEADER_CONTENT_TYPE  = 'Content-Type';
+    public const string HEADER_ACCEPT = 'Accept';
 
     public const string DEFAULT_CONTENT_TYPE = 'application/json';
 
@@ -40,10 +47,10 @@ public function __construct(
 
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
-        $isActive    = $this->isActive($request);
-        $statusCode  = $this->getStatusCode($request);
-        $contentType = $this->getContentType($request);
-        $exampleName = $this->getExample($request);
+        $isActive             = $this->isActive($request);
+        $statusCode           = $this->getStatusCode($request);
+        $acceptedContentTypes = $this->getAcceptedContentTypes($request);
+        $exampleName          = $this->getExample($request);
 
         $path = $request->getUri()->getPath();
         if ($path === '/' || $path === '/openapi.yaml' || $path === '/openapi.json') {
@@ -64,7 +71,7 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             $response = $this->requestHandler->handleValidRequest(
                 $requestValidatorResult->getSchema(),
                 $requestValidatorResult->getOperationAddress(),
-                $contentType,
+                $acceptedContentTypes,
                 $statusCode,
                 $exampleName
             );
@@ -76,7 +83,10 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             );
 
             if ($responseResult->getException() instanceof Throwable) {
-                return $this->responseHandler->handleInvalidResponse($responseResult->getException(), $contentType);
+                return $this->responseHandler->handleInvalidResponse(
+                    $responseResult->getException(),
+                    $acceptedContentTypes[0] ?? self::DEFAULT_CONTENT_TYPE
+                );
             }
 
             return $response;
@@ -85,7 +95,7 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
                 $exception,
                 isset($requestValidatorResult) ? $requestValidatorResult->getSchema() : null,
                 isset($requestValidatorResult) ? $requestValidatorResult->getOperationAddress() : null,
-                $contentType
+                $acceptedContentTypes
             );
         }
     }
@@ -104,11 +114,47 @@ private function getStatusCode(ServerRequestInterface $serverRequest): ?string
         return empty($statusCode) ? null : $statusCode;
     }
 
-    private function getContentType(ServerRequestInterface $serverRequest): string
+    /**
+     * Parse the Accept header into a list of content types ordered by quality preference.
+     *
+     * @return list<string>
+     */
+    private function getAcceptedContentTypes(ServerRequestInterface $serverRequest): array
     {
-        $contentType = $serverRequest->getHeader(self::HEADER_CONTENT_TYPE)[0] ?? self::DEFAULT_CONTENT_TYPE;
+        $accept = $serverRequest->getHeaderLine(self::HEADER_ACCEPT);
 
-        return empty($contentType) ? self::DEFAULT_CONTENT_TYPE : $contentType;
+        if ($accept === '' || $accept === '*/*') {
+            return [self::DEFAULT_CONTENT_TYPE];
+        }
+
+        /** @var list<array{type: string, quality: float}> $types */
+        $types = [];
+
+        foreach (explode(',', $accept) as $part) {
+            $part    = trim($part);
+            $quality = 1.0;
+
+            if (str_contains($part, ';')) {
+                $segments = explode(';', $part);
+                $part     = trim($segments[0]);
+                foreach (array_slice($segments, 1) as $param) {
+                    $param = trim($param);
+                    if (str_starts_with($param, 'q=')) {
+                        $quality = (float) substr($param, 2);
+                    }
+                }
+            }
+
+            if ($part !== '') {
+                $types[] = ['type' => $part, 'quality' => $quality];
+            }
+        }
+
+        usort($types, static fn (array $a, array $b): int => $b['quality'] <=> $a['quality']);
+
+        $result = array_map(static fn (array $t): string => $t['type'], $types);
+
+        return $result !== [] ? $result : [self::DEFAULT_CONTENT_TYPE];
     }
 
     private function getExample(ServerRequestInterface $serverRequest): ?string