Initial commit

Author: tlmcclatchey

.gitignore

@@ -0,0 +1,3 @@
+.idea/
+composer.lock
+vendor/

LICENSE.md

@@ -0,0 +1,25 @@
+# License
+
+This project is licensed under the terms of the MIT license.
+
+The MIT License (MIT)
+
+Copyright (c) 2023 [CommonPHP.org](https://www.commonphp.org/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,80 @@
+# CommonPHP Dependency Injection Library
+
+This library provides a straightforward way to manage service dependencies in a PHP application. It follows the Inversion of Control principle, allowing classes to specify their dependencies without being responsible for their creation.
+
+## Features
+
+1. **Dependency Injection**: Enables classes to declare their dependencies in the constructor, which will be automatically injected when the class is instantiated.
+
+2. **Service Container**: The library includes a service container that manages service instances. Services are created as singletons - once a service is created, the same instance will be returned every time it is requested.
+
+3. **Simple API**: The library provides simple and intuitive methods for registering services and retrieving them from the service container.
+
+## Usage
+
+Here is a simple example of how to use the library:
+
+```php
+class MyClass {
+    public function __construct(CommonPHP\DependencyInjection\ServiceContainer $container)
+    {
+        // The service container is injected as a dependency
+    }
+}
+
+$di = new CommonPHP\DependencyInjection\DependencyInjector();
+$container = new CommonPHP\DependencyInjection\ServiceContainer($di);
+
+// Register your services
+$di->services->register(MyClass::class);
+
+// Retrieve the service
+$myClassInstance = $container->get(MyClass::class);
+```
+
+This library is designed to prevent direct dependency on the `DependencyInjector` inside services. The `DependencyInjector` should only be used during application bootstrapping.
+
+## Installation
+
+This section outlines how to install the `CommonPHP Dependency Injection` library.
+
+### Requirements
+
+- PHP 8.1 or newer.
+
+### With Composer
+
+The easiest way to install the `CommonPHP Dependency Injection` library is via Composer.
+
+If you don't have Composer installed, you can download it from [https://getcomposer.org/](https://getcomposer.org/).
+
+Once you have Composer installed, you can install the `CommonPHP Dependency Injection` library by running the following command in your terminal:
+
+```bash
+composer require comphp/di
+```
+
+This command will add the `CommonPHP Dependency Injection` library as a dependency to your project, and Composer will automatically handle the autoloading of classes.
+
+### Manual Installation
+
+If you don't use Composer, you can download the latest release of the `CommonPHP Dependency Injection` library from the GitHub repository. After downloading, you will have to handle autoloading the classes manually in your application.
+
+After the installation, you can use the library as outlined in the Usage section.
+
+## Next Steps
+
+After the installation, refer to the Usage section of this README to learn how to use the `CommonPHP Dependency Injection` library in your projects.
+
+## Testing
+
+As of version 0.0.1, we are still in the process of refining the codebase and defining the overall functionality of the CommonPHP Dependency Injection library, as well as other libraries within the CommonPHP framework. Therefore, comprehensive unit tests have not been created yet.
+
+However, quality and reliability are paramount to us. Rest assured, we plan to incorporate robust testing in future versions as the functionality becomes more concrete. In the meantime, we encourage contributions in all areas of the project, including tests.
+
+If you are interested in contributing to testing, or any other aspect of this project, please see the 'Contributing' section for more information.
+
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.

composer.json

@@ -0,0 +1,28 @@
+{
+  "name": "comphp/di",
+  "type": "library",
+  "version": "0.0.1",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "timothy.mcclatchey",
+      "email": "timothy@commonphp.org"
+    }
+  ],
+  "autoload": {
+    "psr-4": {
+      "CommonPHP\\DependencyInjection\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Test\\CommonPHP\\DependencyInjection\\": "tests/"
+    }
+  },
+  "require": {
+    "php": "^8.1"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^9.5.23"
+  }
+}

examples/usage.php

@@ -0,0 +1,31 @@
+<?php
+
+include '../vendor/autoload.php';
+
+class InstantiateExample1
+{
+    public function __construct(CommonPHP\DependencyInjection\ServiceContainer $container)
+    {
+        // This is the expected usage, and will work. The DI will not expose itself
+    }
+}
+
+class InstantiateExample2
+{
+    public function __construct(CommonPHP\DependencyInjection\DependencyInjector $di)
+    {
+        // This instantiate will fail because DI will never expose itself. DI is only used during application bootstrapping
+        // then the ServiceContainer auto-registers itself as service and provides a simplified readonly method of handling
+        // services
+    }
+}
+
+$di = new CommonPHP\DependencyInjection\DependencyInjector();
+$container = new CommonPHP\DependencyInjection\ServiceContainer($di);
+
+// This is a simulated "bootstrapping"
+$di->services->register(InstantiateExample1::class);
+$di->services->register(InstantiateExample2::class);
+
+$ex1 = $container->get(InstantiateExample1::class); // This will work
+$ex2 = $container->get(InstantiateExample2::class); // This will not

src/Collections/AliasCollection.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace CommonPHP\DependencyInjection\Collections;
+
+use CommonPHP\DependencyInjection\Exceptions\AliasAlreadyRegisteredException;
+use CommonPHP\DependencyInjection\Exceptions\AliasClassNotDerivedException;
+use CommonPHP\DependencyInjection\Exceptions\AliasClassNotFoundException;
+use CommonPHP\DependencyInjection\Exceptions\AliasNotRegisteredException;
+use CommonPHP\DependencyInjection\Exceptions\ServiceClassNotFoundException;
+
+/**
+ * The AliasCollection class represents a collection of aliases.
+ */
+final class AliasCollection
+{
+    /**
+     * The array of aliases.
+     *
+     * @var array
+     */
+    private array $aliases = [];
+
+    /**
+     * Check if an alias exists in the collection.
+     *
+     * @param string $aliasClass The class name of the alias.
+     * @return bool True if the alias exists, false otherwise.
+     */
+    public function has(string $aliasClass): bool
+    {
+        return array_key_exists($aliasClass, $this->aliases);
+    }
+
+    /**
+     * Get the class name associated with an alias.
+     *
+     * @param string $aliasClass The class name of the alias.
+     * @return string The class name associated with the alias.
+     * @throws AliasNotRegisteredException If the alias is not found in the collection.
+     */
+    public function get(string $aliasClass): string
+    {
+        if (!$this->has($aliasClass)) {
+            throw new AliasNotRegisteredException($aliasClass);
+        }
+        return $this->aliases[$aliasClass];
+    }
+
+    /**
+     * Register an alias with a class name.
+     *
+     * @param string $aliasClass  The class name of the alias.
+     * @param string $serviceClass The class name associated with the alias.
+     * @return void
+     * @throws AliasAlreadyRegisteredException If the alias is already registered with a different class.
+     * @throws ServiceClassNotFoundException If the service class is not found.
+     * @throws AliasClassNotFoundException If the alias class is not found.
+     * @throws AliasClassNotDerivedException If the alias class and service class are not derived from each other.
+     */
+    public function register(string $aliasClass, string $serviceClass): void
+    {
+        if ($this->has($aliasClass)) {
+            throw new AliasAlreadyRegisteredException($aliasClass, $serviceClass, $this->aliases[$aliasClass]);
+        }
+
+        if (!class_exists($serviceClass)) {
+            throw new ServiceClassNotFoundException($serviceClass);
+        }
+
+        if (!class_exists($aliasClass)) {
+            throw new AliasClassNotFoundException($aliasClass);
+        }
+
+        if (!is_subclass_of($aliasClass, $serviceClass) && !is_subclass_of($serviceClass, $aliasClass)) {
+            throw new AliasClassNotDerivedException($aliasClass, $serviceClass);
+        }
+
+        $this->aliases[$aliasClass] = $serviceClass;
+    }
+
+    /**
+     * Get all aliases as an array.
+     *
+     * @return array The aliases as an array.
+     */
+    public function toArray(): array
+    {
+        return $this->aliases;
+    }
+}

src/Collections/NamespaceCollection.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace CommonPHP\DependencyInjection\Collections;
+
+use CommonPHP\DependencyInjection\Exceptions\NamespaceAlreadyRegisteredException;
+use CommonPHP\DependencyInjection\Exceptions\NamespaceInvalidException;
+
+/**
+ * The NamespaceCollection class represents a collection of namespaces.
+ */
+final class NamespaceCollection
+{
+    /**
+     * The array of namespaces.
+     *
+     * @var array
+     */
+    private array $namespaces = [];
+
+    /**
+     * Check if a class belongs to any registered namespace.
+     *
+     * @param string $className The fully qualified class name.
+     * @return bool True if the class belongs to any registered namespace, false otherwise.
+     */
+    public function has(string $className): bool
+    {
+        foreach ($this->namespaces as $namespace) {
+            if (str_starts_with($className, $namespace)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Register a namespace.
+     *
+     * @param string $namespace The namespace to register.
+     * @return void
+     * @throws NamespaceInvalidException If the namespace is not a valid PHP namespace.
+     * @throws NamespaceAlreadyRegisteredException If the namespace is already registered.
+     */
+    public function register(string $namespace): void
+    {
+        if (!preg_match('/^[a-zA-Z][a-zA-Z0-9_\\\\]*$/m', $namespace)) {
+            throw new NamespaceInvalidException($namespace);
+        }
+
+        if (!str_ends_with($namespace, "\\")) {
+            $namespace .= "\\";
+        }
+
+        // If the namespace is already registered, throw an exception
+        if (in_array($namespace, $this->namespaces)) {
+            throw new NamespaceAlreadyRegisteredException($namespace);
+        }
+
+        // Register the namespace.
+        $this->namespaces[] = $namespace;
+    }
+
+    /**
+     * Get all registered namespaces as an array.
+     *
+     * @return array The registered namespaces.
+     */
+    public function toArray(): array
+    {
+        return $this->namespaces;
+    }
+}