Introduced Interface for ServiceEndpoints

Author: mgerzabek

src/Endpoint.php

@@ -2,21 +2,14 @@
 
 namespace Flat3\Lodata;
 
-class Endpoint
+use Flat3\Lodata\Interfaces\ServiceEndpointInterface;
+
+class Endpoint implements ServiceEndpointInterface
 {
-    /**
-     * @var string $serviceUri the &lt;service-uri> of the <code>Flat3\Lodata\Model</code>.
-     */
     protected $serviceUri;
 
-    /**
-     * @var string $route the route prefix configured in <code>'lodata.prefix'</code>
-     */
     protected $route;
 
-    /**
-     * @var string $endpoint the full url to the ODataService endpoint
-     */
     protected $endpoint;
 
     public function __construct(string $serviceUri)
@@ -31,10 +24,6 @@ public function __construct(string $serviceUri)
         $this->endpoint = url($this->route) . '/';
     }
 
-    /**
-     * @return string the path within the odata URI space, like in
-     * https://<server>:<port>/<config('lodata.prefix')>/<service-uri>/$metadata
-     */
     public function endpoint(): string
     {
         return $this->endpoint;
@@ -45,29 +34,18 @@ public function route(): string
         return $this->route;
     }
 
-    /**
-     * This method is intended to be overridden by subclasses.
-     *
-     * The value of the function will be presented in the Schema Namespace attribute,
-     * https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_Schema
-     *
-     * @return string
-     */
-    public function getNamespace(): string
+    public function namespace(): string
     {
-        // override this function to set Schema Namespace attribute
         return config('lodata.namespace');
     }
 
-    /**
-     * This method is intended to be overridden by subclasses.
-     *
-     * Discovers Schema and Annotations of the `$metadata` file for
-     * the service.
-     */
+    public function cachedMetadataXMLPath(): ?string
+    {
+        return null;
+    }
+
     public function discover(Model $model): Model
     {
-        // override this function to register all of your $metadata capabilities
         return $model;
     }
 }

src/Interfaces/ServiceEndpointInterface.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Flat3\Lodata\Interfaces;
+
+use Flat3\Lodata\Model;
+
+/**
+ * Interface for defining a custom OData service endpoint.
+ *
+ * Implementers can use this interface to expose a specific service under a custom path,
+ * define its namespace, route behavior, and optionally provide a statically generated
+ * $metadata document.
+ */
+interface ServiceEndpointInterface
+{
+
+    /**
+     * Returns the relative endpoint identifier within the OData service URI space.
+     *
+     * This is the part that appears between the configured Lodata prefix and
+     * the `$metadata` segment, e.g.:
+     *   https://<server>:<port>/<config('lodata.prefix')>/<endpoint>/$metadata
+     *
+     * @return string The relative OData endpoint path
+     */
+    public function endpoint(): string;
+
+    /**
+     * Returns the full request route to this service endpoint.
+     *
+     * This typically resolves to the route path used by Laravel to handle
+     * incoming requests for this specific service instance.
+     *
+     * @return string The full HTTP route to the endpoint
+     */
+    public function route(): string;
+
+    /**
+     * Returns the XML namespace used in the `$metadata` document.
+     *
+     * This value is injected as the `Namespace` attribute of the <Schema> element
+     * in the OData CSDL document, and must be globally unique per service.
+     *
+     * @see https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_Schema
+     *
+     * @return string The schema namespace for the service
+     */
+    public function namespace(): string;
+
+    /**
+     * Returns the absolute filesystem path to a statically annotated `$metadata` file.
+     *
+     * This method can be overridden to provide a custom pre-generated CSDL XML file
+     * for the OData metadata endpoint. If a path is returned, it will be used as-is
+     * instead of dynamically generating the schema from model definitions.
+     * Return `null` to fall back to automatic schema generation.
+     *
+     * @return string|null Full path to a static $metadata XML file, or null for dynamic generation
+     */
+    public function cachedMetadataXMLPath(): ?string;
+
+    /**
+     * Builds or enriches the model used for schema generation and metadata discovery.
+     *
+     * This method should populate the provided `Model` instance with entity sets,
+     * types, annotations, and operations that define the service schema. It is
+     * invoked during the metadata bootstrapping process when an OData service request
+     * is processed.
+     *
+     * @param Model $model The schema model to populate
+     * @return Model The enriched model instance representing the OData service
+     */
+    public function discover(Model $model): Model;
+}

src/Model.php

@@ -199,7 +199,7 @@ public function getTypeDefinition(string $name): ?Type
      */
     public static function getNamespace(): string
     {
-        return app(Endpoint::class)->getNamespace();
+        return app(Endpoint::class)->namespace();
     }
 
     /**

src/PathSegment/Metadata.php

@@ -5,10 +5,12 @@
 namespace Flat3\Lodata\PathSegment;
 
 use Flat3\Lodata\Controller\Transaction;
+use Flat3\Lodata\Endpoint;
 use Flat3\Lodata\Exception\Internal\PathNotHandledException;
 use Flat3\Lodata\Exception\Protocol\BadRequestException;
 use Flat3\Lodata\Interfaces\PipeInterface;
 use Flat3\Lodata\Interfaces\ResponseInterface;
+use Flat3\Lodata\PathSegment\Metadata\CachedXML;
 use Flat3\Lodata\Transaction\MediaType;
 use Flat3\Lodata\Transaction\MediaTypes;
 use Illuminate\Http\Request;
@@ -45,6 +47,9 @@ public static function pipe(
                 return new Metadata\JSON();
 
             default:
+                if (app(Endpoint::class)->cachedMetadataXMLPath()) {
+                    return new CachedXML();
+                }
                 return new Metadata\XML();
         }
     }

src/PathSegment/Metadata/CachedXML.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Flat3\Lodata\PathSegment\Metadata;
+
+use Flat3\Lodata\Controller\Response;
+use Flat3\Lodata\Controller\Transaction;
+use Flat3\Lodata\Endpoint;
+use Flat3\Lodata\Interfaces\ContextInterface;
+use Flat3\Lodata\Interfaces\StreamInterface;
+use Flat3\Lodata\PathSegment\Metadata;
+use Flat3\Lodata\Transaction\MediaType;
+use RuntimeException;
+
+class CachedXML extends Metadata implements StreamInterface
+{
+    public function response(Transaction $transaction, ?ContextInterface $context = null): Response
+    {
+        $transaction->sendContentType((new MediaType)->parse(MediaType::xml));
+
+        return $transaction->getResponse()->setCallback(function () use ($transaction) {
+            $this->emitStream($transaction);
+        });
+    }
+
+    public function emitStream(Transaction $transaction): void
+    {
+        $path = app(Endpoint::class)->cachedMetadataXMLPath();
+        if (!file_exists($path)) {
+            throw new RuntimeException("Metadata file not found: {$path}");
+        }
+        $content = file_get_contents($path);
+        if (false === $content) {
+            throw new RuntimeException("Failed to read metadata file: {$path}");
+        }
+        $transaction->sendOutput($content);
+    }
+}