Time to release a 1.0.0

Author: Robin de Graaf

Diff for: .gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 .idea
+.phpunit.result.cache
 composer.lock
 vendor
 coverage

Diff for: CHANGELOG.md

@@ -1,5 +1,16 @@
 # Parable PHP DI
 
+## 1.0.0
+
+It's time! Finally a 1.0.0 release, locking the interface in place for at least a while.
+
+_Changes_
+- Completed the `README`.
+- `clear()` no longer throws on a non-stored instance, since the expected result (that instance no longer being stored) is met.
+- `NotFoundException` renamed to `InstanceNotFoundException` for clarity.
+- Added `unmap(string $requested): void` to unmap _and_ clear any mapped instance.
+- Improved `clearExcept()` to use `clear()` so it also unsets any existing relationships. 
+
 ## 0.3.2
 
 _Changes_

Diff for: README.md

@@ -37,7 +37,7 @@ $container = new Container();
 
 class App
 {
-    public function __construct(ThatInterface $classWithInterface)
+    public function __construct(ThatInterface $classWithThatInterface)
     {
     }
 
@@ -47,15 +47,15 @@ class App
     }
 }
 
-$container->map(ThatInterface::class, ClassWithInterface::class);
+$container->map(ThatInterface::class, ClassWithThatInterface::class);
 
 $app = $container->get(App::class);
 $app->run();
 ```
 
-The above situation can also be solved by instantiating and then storing `ClassWithInterface` under `ThatInterface`.
+The above situation can also be solved by instantiating and then storing `ClassWithThatInterface` under `ThatInterface`.
 
-Example usage of a class that needs the di itself:
+Example usage of a class that needs the di itself, in case you need to do dynamic DI:
 
 ```php
 use \Parable\Di\Container;
@@ -65,31 +65,30 @@ $container = new Container();
 class App
 {
     public $container;
-    public function __construct(\Parable\Di\Container $container)
-    {
-        $this->container = $container;
-    }
+    public function __construct(
+        public Container $container
+    ) {}
 }
 
 $app = $container->get(App::class);
-var_dump($app->container->has(App::class));
-
-// output: bool(true)
+var_dump($app->container->has(App::class)); // output: bool(true)
 ```
 
-For all other use cases, simply check the tests in `tests/DiTest.php`.
+For all other use cases, simply check the tests in `tests/ContainerTest.php`.
 
 ## API
 
 - `get(string $name): object` - creates or gets instance
 - `has(string $name): bool` - check if instance is stored
+- `assertHas(string $name): void` - check and throw exception if instance is not stored
 - `build(string $name): object` - build instance with stored deps, don't store
 - `buildAll(string $name): object` - build instance with new deps, don't store
 - `map(string $requested, string $replacement): void` - allow pre-emptively defining a replacement class to be instantiated when the requested name is retrieved or built. Use for lazy-loading classes, i.e. for interface deps.
+- `unmap(string $requested): void` - removes the mapping _and_ clears any previously mapped instances
 - `getDependenciesFor(string $name, [int $storedDependencies]): array` - get dependencies for instance, with stored (default) or new deps 
 - `store(object $instance, [string $name]): void` - store instance under name, or under instance name by default
 - `clear(string $name): void` - clear instance
-- `clearExcept(array $keep): void` - clear all except provided names
+- `clearExcept(array $keep): void` - clear all except provided names, throws if any of the instances to keep doesn't exist
 - `clearAll(): void` - clear all
 
 Where `object` refers to any instance of any class.

Diff for: src/Container.php

@@ -3,7 +3,7 @@
 namespace Parable\Di;
 
 use Parable\Di\Exceptions\ContainerException;
-use Parable\Di\Exceptions\NotFoundException;
+use Parable\Di\Exceptions\InstanceNotFoundException;
 use ReflectionClass;
 use ReflectionNamedType;
 use Throwable;
@@ -42,9 +42,6 @@ public function get(string $name): object
         return $this->instances[$name];
     }
 
-    /**
-     * Returns whether an instance is currently stored or not.
-     */
     public function has(string $name): bool
     {
         $name = $this->getDefinitiveName($name);
@@ -55,7 +52,7 @@ public function has(string $name): bool
     public function assertHas(string $name): void
     {
         if (!$this->has($name)) {
-            throw NotFoundException::fromName($name);
+            throw InstanceNotFoundException::fromName($name);
         }
     }
 
@@ -79,31 +76,6 @@ public function buildAll(string $name): object
         return $this->createInstance($name, self::USE_NEW_DEPENDENCIES);
     }
 
-    /**
-     * Create an instance with either new or existing dependencies.
-     *
-     * @throws ContainerException
-     */
-    protected function createInstance(string $name, int $useStoredDependencies): object
-    {
-        $name = $this->getDefinitiveName($name);
-
-        if (interface_exists($name)) {
-            throw new ContainerException(sprintf(
-                "Cannot create instance for interface `%s`.",
-                $name
-            ));
-        }
-
-        try {
-            $dependencies = $this->getDependenciesFor($name, $useStoredDependencies);
-        } catch (Throwable $t) {
-            throw new ContainerException($t->getMessage(), (int)$t->getCode(), $t);
-        }
-
-        return new $name(...$dependencies);
-    }
-
     /**
      * Map the requested name to the replacement name. When the requested
      * name is retrieved, the replacement name will be used to build the instance.
@@ -113,21 +85,12 @@ public function map(string $requested, string $replacement): void
         $this->maps[$this->normalize($requested)] = $this->normalize($replacement);
     }
 
-    /**
-     * Return the mapping if it exists, otherwise just return the requested name.
-     */
-    protected function getMapIfExists(string $requested): string
+    public function unmap(string $requested): void
     {
-        return $this->maps[$requested] ?? $requested;
+        unset($this->maps[$requested]);
+        $this->clear($requested);
     }
 
-    /**
-     * Get the dependencies for an instance, based on the constructor.
-     * Optionally use stored dependencies or always create new ones.
-     *
-     * @return mixed[]
-     * @throws ContainerException
-     */
     public function getDependenciesFor(
         string $name,
         int $useStoredDependencies = self::USE_STORED_DEPENDENCIES
@@ -210,53 +173,43 @@ public function getDependenciesFor(
         return $dependencies;
     }
 
-    /**
-     * Store the provided instance with the provided name, or the class name of the object.
-     */
     public function store(object $instance, string $name = null): void
     {
         $name = $this->getDefinitiveName($name ?? $instance::class);
 
         $this->instances[$name] = $instance;
     }
 
-    /**
-     * Clear the requested instance.
-     *
-     * @throws NotFoundException
-     */
     public function clear(string $name): void
     {
         $name = $this->getDefinitiveName($name);
 
-        $this->assertHas($name);
+        if (!$this->has($name)) {
+            return;
+        }
 
         unset($this->instances[$name]);
 
         $this->clearRelationship($name);
     }
 
     /**
-     * Clear all instances except those provided.
-     *
      * @param string[] $keep
      *
      * @throws ContainerException
-     * @throws NotFoundException
+     * @throws InstanceNotFoundException
      */
     public function clearExcept(array $keep): void
     {
-        $kept = [];
-
         foreach ($keep as $name) {
-            $name = $this->getDefinitiveName($name);
-
             $this->assertHas($name);
-
-            $kept[$name] = $this->get($name);
         }
 
-        $this->instances = $kept;
+        foreach ($this->instances as $name => $instance) {
+            if (!in_array($name, $keep, true)) {
+                $this->clear($name);
+            }
+        }
     }
 
     /**
@@ -268,6 +221,39 @@ public function clearAll(): void
         $this->relationships = [];
     }
 
+    /**
+     * Create an instance with either new or existing dependencies.
+     *
+     * @throws ContainerException
+     */
+    protected function createInstance(string $name, int $useStoredDependencies): object
+    {
+        $name = $this->getDefinitiveName($name);
+
+        if (interface_exists($name)) {
+            throw new ContainerException(sprintf(
+                "Cannot create instance for interface `%s`.",
+                $name
+            ));
+        }
+
+        try {
+            $dependencies = $this->getDependenciesFor($name, $useStoredDependencies);
+        } catch (Throwable $t) {
+            throw new ContainerException($t->getMessage(), (int)$t->getCode(), $t);
+        }
+
+        return new $name(...$dependencies);
+    }
+
+    /**
+     * Return the mapping if it exists, otherwise just return the requested name.
+     */
+    protected function getMapIfExists(string $requested): string
+    {
+        return $this->maps[$requested] ?? $requested;
+    }
+
     /**
      * Store the relationship between the two items.
      *

Diff for: src/Exceptions/NotFoundException.php renamed to src/Exceptions/InstanceNotFoundException.php

@@ -4,7 +4,7 @@
 
 use Exception;
 
-class NotFoundException extends Exception
+class InstanceNotFoundException extends Exception
 {
     public static function fromName(string $id)
     {

Diff for: tests/DiTest.php renamed to tests/ContainerTest.php

@@ -4,7 +4,7 @@
 
 use Parable\Di\Container;
 use Parable\Di\Exceptions\ContainerException;
-use Parable\Di\Exceptions\NotFoundException;
+use Parable\Di\Exceptions\InstanceNotFoundException;
 use Parable\Di\Tests\Classes\ScalarDependency;
 use Parable\Di\Tests\Classes\CyclicalDependencyFirst;
 use Parable\Di\Tests\Classes\CyclicalDependencySecond;
@@ -19,14 +19,14 @@
 use Parable\Di\Tests\Classes\ScalarDependencyWithDefaultAndNonScalarReverse;
 use PHPUnit\Framework\TestCase;
 
-class DiTest extends TestCase
+class ContainerTest extends TestCase
 {
     protected Container $container;
 
-    public function setUp(): void
-    {
-        $this->container = new Container();
-    }
+public function setUp(): void
+{
+    $this->container = new Container();
+}
 
     public function testGetStoresAndRetrievesInstance(): void
     {
@@ -134,6 +134,24 @@ public function testMappingWorksForInterface(): void
         self::assertTrue($this->container->has(FakeWithInterface::class));
     }
 
+    public function testUnmappingWorksForInterface(): void
+    {
+        // Since mapped, this part should work
+        $this->container->map(FakeInterface::class, FakeWithInterface::class);
+        $this->container->get(FakeInterface::class);
+
+        // But not anymore
+        $this->container->unmap(FakeInterface::class);
+
+        try {
+            $fakeWithInterface = $this->container->get(FakeInterface::class);
+
+            self::fail('Should not have gotten here due to interface instantiation.');
+        } catch (ContainerException $e) {
+            self::assertStringContainsString('Cannot create instance for interface', $e->getMessage());
+        }
+    }
+
     public function testGetDependenciesForWorks(): void
     {
         $noDependencies = $this->container->get(NoDependencies::class);
@@ -243,14 +261,6 @@ public function testClearWorks(): void
         self::assertTrue($this->container->has(Dependencies::class));
     }
 
-    public function testClearThrowsForMissingInstance(): void
-    {
-        $this->expectException(NotFoundException::class);
-        $this->expectExceptionMessage("No instance found stored for `Parable\Di\Tests\Classes\NoDependencies`.");
-
-        $this->container->clear(NoDependencies::class);
-    }
-
     public function testClearAllWorks(): void
     {
         $this->container->get(NoDependencies::class);
@@ -279,12 +289,15 @@ public function testClearExceptWorks(): void
         self::assertFalse($this->container->has(Dependencies::class));
     }
 
-    public function testClearExceptThrowsOnMissingInstance(): void
+    public function testClearExceptThrowsWhenNonExistingClassIsProvided(): void
     {
-        $this->expectException(NotFoundException::class);
-        $this->expectExceptionMessage("No instance found stored for `Parable\Di\Tests\Classes\NoDependencies`.");
+        $this->expectException(InstanceNotFoundException::class);
+        $this->expectExceptionMessage(sprintf(
+            "No instance found stored for `%s`.",
+            ScalarDependency::class
+        ));
 
-        $this->container->clearExcept([NoDependencies::class]);
+        $this->container->clearExcept([ScalarDependency::class]);
     }
 
     public function testThrowsOnCyclicalDependency(): void