Merge pull request #73 from ray-di/feature/media-query-sql-module

Add MediaQuerySqlModule for simplified API (1.0 preparation)

Author: koriym

src/MediaQueryBaseModule.php

@@ -12,6 +12,14 @@
 use Ray\InputQuery\ToArray;
 use Ray\InputQuery\ToArrayInterface;
 
+/**
+ * Base module for MediaQuery framework - provides common bindings.
+ *
+ * This is an internal implementation module. Users should use MediaQuerySqlModule
+ * or MediaQueryWebModule instead of using this module directly.
+ *
+ * @internal
+ */
 final class MediaQueryBaseModule extends AbstractModule
 {
     public function __construct(

src/MediaQueryDbModule.php

@@ -10,6 +10,14 @@
 use Ray\MediaQuery\Annotation\Qualifier\FactoryMethod;
 use Ray\MediaQuery\Annotation\Qualifier\SqlDir;
 
+/**
+ * Database query module - provides SQL-specific bindings.
+ *
+ * This is an internal implementation module. Users should use MediaQuerySqlModule
+ * instead of using this module directly.
+ *
+ * @internal
+ */
 final class MediaQueryDbModule extends AbstractModule
 {
     public function __construct(

src/MediaQueryModule.php

@@ -7,12 +7,32 @@
 use Override;
 use Ray\Di\AbstractModule;
 
+/**
+ * Low-level MediaQuery module for advanced configurations.
+ *
+ * This is an internal/advanced API. For most use cases, use MediaQuerySqlModule instead.
+ *
+ * MediaQuerySqlModule provides a simpler interface:
+ * ```php
+ * // Recommended: Simple and clear
+ * $this->install(new MediaQuerySqlModule('/path/to/interfaces', '/path/to/sql'));
+ *
+ * // Advanced: When you need Queries::fromClasses() or other customization
+ * $queries = Queries::fromClasses([UserInterface::class, OrderInterface::class]);
+ * $this->install(new MediaQueryModule($queries, [new DbQueryConfig('/path/to/sql')]));
+ * ```
+ *
+ * Note: The array of DbQueryConfig currently only uses the last element.
+ * Multiple SQL directories may be supported in future versions if needed.
+ *
+ * @internal This is a low-level API. Use MediaQuerySqlModule for typical use cases.
+ */
 final class MediaQueryModule extends AbstractModule
 {
     /** @param list<DbQueryConfig> $configs */
     public function __construct(
-        private Queries $queries,
-        private array $configs,
+        private readonly Queries $queries,
+        private readonly array $configs,
         AbstractModule|null $module = null,
     ) {
         parent::__construct($module);
@@ -22,6 +42,7 @@ public function __construct(
     protected function configure(): void
     {
         $this->install(new MediaQueryBaseModule($this->queries));
+        // Note: Only the last config in the array is effective due to binding overwrite
         foreach ($this->configs as $config) {
             $this->install(new MediaQueryDbModule($config));
         }

src/MediaQuerySqlModule.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\MediaQuery;
+
+use Override;
+use Ray\Di\AbstractModule;
+
+/**
+ * SQL-based MediaQuery module.
+ *
+ * This module simplifies SQL query integration by accepting directory paths directly.
+ * It automatically discovers query interfaces from the interface directory and configures
+ * SQL query execution from the SQL directory.
+ *
+ * Example usage:
+ * ```php
+ * $this->install(new MediaQuerySqlModule(
+ *     interfaceDir: '/path/to/query/interfaces',
+ *     sqlDir: '/path/to/sql/files'
+ * ));
+ * ```
+ *
+ * For advanced use cases requiring explicit query class selection or custom configuration,
+ * create your own module that wraps the internal modules:
+ * ```php
+ * class MyQueryModule extends AbstractModule {
+ *     protected function configure(): void {
+ *         $queries = Queries::fromClasses([UserInterface::class, OrderInterface::class]);
+ *         $this->install(new MediaQueryBaseModule($queries));
+ *         $this->install(new MediaQueryDbModule(new DbQueryConfig('/path/to/sql')));
+ *     }
+ * }
+ * ```
+ */
+final class MediaQuerySqlModule extends AbstractModule
+{
+    public function __construct(
+        private readonly string $interfaceDir,
+        private readonly string $sqlDir,
+        AbstractModule|null $module = null,
+    ) {
+        parent::__construct($module);
+    }
+
+    #[Override]
+    protected function configure(): void
+    {
+        $queries = Queries::fromDir($this->interfaceDir);
+        $this->install(new MediaQueryBaseModule($queries));
+        $this->install(new MediaQueryDbModule(new DbQueryConfig($this->sqlDir)));
+    }
+}

tests/MediaQuerySqlModuleTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\MediaQuery;
+
+use PHPUnit\Framework\TestCase;
+use Ray\AuraSqlModule\AuraSqlModule;
+use Ray\Di\AbstractModule;
+use Ray\Di\Injector;
+
+class MediaQuerySqlModuleTest extends TestCase
+{
+    public function testModuleCanBeInstalled(): void
+    {
+        $module = new class extends AbstractModule {
+            protected function configure(): void
+            {
+                $this->install(new MediaQuerySqlModule(
+                    __DIR__ . '/Fake/Queries',
+                    __DIR__ . '/sql',
+                ));
+                $this->install(new AuraSqlModule('sqlite::memory:'));
+            }
+        };
+
+        $injector = new Injector($module);
+        // Test that basic services are bound
+        $logger = $injector->getInstance(MediaQueryLoggerInterface::class);
+        $this->assertInstanceOf(MediaQueryLoggerInterface::class, $logger);
+    }
+
+    public function testSimplifiedApiComparedToOldWay(): void
+    {
+        // New simplified API
+        $newModule = new class extends AbstractModule {
+            protected function configure(): void
+            {
+                $this->install(new MediaQuerySqlModule(
+                    __DIR__ . '/Fake/Queries',
+                    __DIR__ . '/sql',
+                ));
+                $this->install(new AuraSqlModule('sqlite::memory:'));
+            }
+        };
+
+        // Old verbose API (deprecated)
+        $oldModule = new class extends AbstractModule {
+            protected function configure(): void
+            {
+                $queries = Queries::fromDir(__DIR__ . '/Fake/Queries');
+                $this->install(new MediaQueryModule($queries, [new DbQueryConfig(__DIR__ . '/sql')]));
+                $this->install(new AuraSqlModule('sqlite::memory:'));
+            }
+        };
+
+        // Both should bind the same basic services
+        $newInjector = new Injector($newModule);
+        $oldInjector = new Injector($oldModule);
+
+        $newLogger = $newInjector->getInstance(MediaQueryLoggerInterface::class);
+        $oldLogger = $oldInjector->getInstance(MediaQueryLoggerInterface::class);
+
+        $this->assertInstanceOf(MediaQueryLoggerInterface::class, $newLogger);
+        $this->assertInstanceOf(MediaQueryLoggerInterface::class, $oldLogger);
+    }
+}