Merge pull request #349 from gacela-project/feat/getRequired

Add getRequired() for type-safe service resolution

Author: Chemaclass

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Add contextual bindings via GacelaConfig::when()
 - Add service aliases via GacelaConfig::addAlias()
 - Add protected services via GacelaConfig::addProtected()
+- Add `Gacela::getRequired()` and `Locator::getRequired()` methods for type-safe service resolution that throws `ServiceNotFoundException` instead of returning null
 
 ## [1.12.0](https://github.com/gacela-project/gacela/compare/1.11.0...1.12.0) - 2025-11-09
 

src/Framework/Container/Locator.php

@@ -5,6 +5,7 @@
 namespace Gacela\Framework\Container;
 
 use Gacela\Framework\ClassResolver\GlobalInstance\AnonymousGlobal;
+use Gacela\Framework\Exception\ServiceNotFoundException;
 
 /**
  * @internal
@@ -49,6 +50,23 @@ public static function getSingleton(string $className, ?Container $container = n
         return self::getInstance($container)->get($className);
     }
 
+    /**
+     * Get a singleton from the container, throwing an exception if not found.
+     * Use this when you expect the service to exist and want type-safe returns.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $className
+     *
+     * @throws ServiceNotFoundException
+     *
+     * @return T
+     */
+    public static function getRequiredSingleton(string $className, ?Container $container = null): object
+    {
+        return self::getInstance($container)->getRequired($className);
+    }
+
     public static function getInstance(?Container $container = null): self
     {
         if (!self::$instance instanceof self) {
@@ -83,6 +101,26 @@ public function get(string $className)
         return $locatedInstance;
     }
 
+    /**
+     * @template T of object
+     *
+     * @param class-string<T> $className
+     *
+     * @throws ServiceNotFoundException
+     *
+     * @return T
+     */
+    public function getRequired(string $className): object
+    {
+        $instance = $this->get($className);
+
+        if ($instance === null) {
+            throw new ServiceNotFoundException($className);
+        }
+
+        return $instance;
+    }
+
     /**
      * @template T
      *

src/Framework/Container/LocatorInterface.php

@@ -4,6 +4,8 @@
 
 namespace Gacela\Framework\Container;
 
+use Gacela\Framework\Exception\ServiceNotFoundException;
+
 interface LocatorInterface
 {
     /**
@@ -14,4 +16,18 @@ interface LocatorInterface
      * @return T|null
      */
     public function get(string $className);
+
+    /**
+     * Get a service from the container, throwing an exception if not found.
+     * Use this when you expect the service to exist and want type-safe returns.
+     *
+     * @template T of object
+     *
+     * @param class-string<T> $className
+     *
+     * @throws ServiceNotFoundException
+     *
+     * @return T
+     */
+    public function getRequired(string $className): object;
 }

src/Framework/Exception/ServiceNotFoundException.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gacela\Framework\Exception;
+
+use RuntimeException;
+
+use function sprintf;
+
+final class ServiceNotFoundException extends RuntimeException
+{
+    public function __construct(string $className)
+    {
+        parent::__construct(sprintf('Service "%s" not found in the container.', $className));
+    }
+}

src/Framework/Gacela.php

@@ -18,6 +18,7 @@
 use Gacela\Framework\Container\Container;
 use Gacela\Framework\Container\Locator;
 use Gacela\Framework\Exception\GacelaNotBootstrappedException;
+use Gacela\Framework\Exception\ServiceNotFoundException;
 use Gacela\Framework\ServiceResolver\DocBlockResolverCache;
 
 use function is_string;
@@ -66,6 +67,23 @@ public static function get(string $className): mixed
         return Locator::getSingleton($className, self::$mainContainer);
     }
 
+    /**
+     * Get a service from the container, throwing an exception if not found.
+     * Use this when you expect the service to exist and want type-safe returns.
+     *
+     * @template T of object
+     *
+     * @param  class-string<T>  $className
+     *
+     * @throws ServiceNotFoundException
+     *
+     * @return T
+     */
+    public static function getRequired(string $className): object
+    {
+        return Locator::getRequiredSingleton($className, self::$mainContainer);
+    }
+
     /**
      * Get the main dependency injection container.
      * This is the actual container created during bootstrap with all runtime bindings and frozen services.

tests/Unit/Framework/Container/LocatorTest.php

@@ -6,6 +6,7 @@
 
 use Gacela\Framework\Container\Container;
 use Gacela\Framework\Container\Locator;
+use Gacela\Framework\Exception\ServiceNotFoundException;
 use GacelaTest\Fixtures\StringValue;
 use PHPUnit\Framework\TestCase;
 
@@ -55,4 +56,49 @@ public function test_get_existing_singleton_from_container(): void
 
         self::assertEquals(new StringValue('str'), $singleton);
     }
+
+    public function test_get_required_throws_when_not_found(): void
+    {
+        $this->expectException(ServiceNotFoundException::class);
+        $this->expectExceptionMessage('Service "GacelaTest\Unit\Framework\Container\NonExisting" not found in the container.');
+
+        Locator::getInstance()->getRequired(NonExisting::class);
+    }
+
+    public function test_get_required_singleton_throws_when_not_found(): void
+    {
+        $this->expectException(ServiceNotFoundException::class);
+        $this->expectExceptionMessage('Service "GacelaTest\Unit\Framework\Container\NonExisting" not found in the container.');
+
+        Locator::getRequiredSingleton(NonExisting::class);
+    }
+
+    public function test_get_required_returns_existing_service(): void
+    {
+        Locator::addSingleton(StringValue::class, new StringValue('required'));
+
+        $singleton = Locator::getInstance()->getRequired(StringValue::class);
+
+        self::assertEquals(new StringValue('required'), $singleton);
+    }
+
+    public function test_get_required_singleton_returns_existing_service(): void
+    {
+        Locator::addSingleton(StringValue::class, new StringValue('required'));
+
+        $singleton = Locator::getRequiredSingleton(StringValue::class);
+
+        self::assertEquals(new StringValue('required'), $singleton);
+    }
+
+    public function test_get_required_singleton_from_container(): void
+    {
+        $container = new Container(bindings: [
+            StringValue::class => new StringValue('from-container'),
+        ]);
+
+        $singleton = Locator::getRequiredSingleton(StringValue::class, $container);
+
+        self::assertEquals(new StringValue('from-container'), $singleton);
+    }
 }