Multiple issues fixed in this commit

- Refactor 'Collections' Namespace to 'Support' (#10)
- Move all service-related tasks to CommonPHP/ServiceManager library (#9, #8, #4)
- Implement and pass tests (#6)
- Create CONTRIBUTING.md (#5)
- Close #3 and #1 as they are now applicable to ServiceManager library
- Modified version to 0.1 to create Packagist package for composer

Author: tlmcclatchey

README.md

@@ -1,79 +1,179 @@
-# CommonPHP Dependency Injection Library
+# CommonPHP Dependency Injection
 
-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.
+`CommonPHP\DependencyInjection` is a simple yet powerful dependency injection (DI) container for PHP applications, enabling the means to dynamically create new objects, invoke methods, call functions and populate properties without having to know the structure of the target directly. 
+
+enabling automatic instantiation and wiring of your classes. It is part of the CommonPHP project, which offers various components to ease PHP development.
 
 ## Features
 
-1. **Dependency Injection**: Enables classes to declare their dependencies in the constructor, which will be automatically injected when the class is instantiated.
+- Constructor and method injection: Instantiate classes and invoke methods with automatic resolution of dependencies.
+- Value finder: A support class for the DI process that assists in discovering and managing parameter values during instantiation.
+- Handling of circular dependencies: An instantiation stack to prevent issues caused by recursive dependency chains.
+- Customizable parameter lookup: Enhance the default lookup process by adding custom lookup hooks.
+- Populating object properties: Assign values to an object's properties, handling a variety of visibility and type scenarios.
+- Exception handling: A series of specific exceptions to help troubleshoot issues related to DI and instantiation.
+
+## Requirements
 
-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.
+The CommonPHP framework requires PHP 8.1 or newer. This library specifically has the following dependencies:
 
-3. **Simple API**: The library provides simple and intuitive methods for registering services and retrieving them from the service container.
+- PHP's built-in Reflection classes, which are used extensively for instantiating classes, invoking methods, and reading type information.
 
-## Usage
 
-Here is a simple example of how to use the library:
+## Installation
+
+You can install `CommonPHP\DependencyInjection` using Composer:
+
+```bash
+composer require comphp/di
+```
+
+## Basic Usage
+
+### Instantiating Classes
+
+The main component is the `DependencyInjector` class, which is responsible for injecting the passed parameters into a constructor, method or function. 
 
 ```php
-class MyClass {
-    public function __construct(CommonPHP\DependencyInjection\ServiceContainer $container)
-    {
-        // The service container is injected as a dependency
-    }
-}
+<?php
+
+require_once 'vendor/autoload.php';
 
-$di = new CommonPHP\DependencyInjection\DependencyInjector();
-$container = new CommonPHP\DependencyInjection\ServiceContainer($di);
+use CommonPHP\DependencyInjection\DependencyInjector;
 
-// Register your services
-$di->services->register(MyClass::class);
+$injector = new DependencyInjector();
 
-// Retrieve the service
-$myClassInstance = $container->get(MyClass::class);
+// Instantiate a class
+$exampleClass = $injector->instantiate(ExampleClass::class);
+
+// Invoke a method
+$result = $injector->invoke($exampleClass, 'exampleMethod');
+
+// Call a function or closure
+$result = $injector->call('exampleFunction');
 ```
 
-This library is designed to prevent direct dependency on the `DependencyInjector` inside services. The `DependencyInjector` should only be used during application bootstrapping.
+### Populating Object Properties
 
-## Installation
+The `DependencyInjector` can also populate the properties of an object:
 
-This section outlines how to install the `CommonPHP Dependency Injection` library.
+```php
+<?php
 
-### Requirements
+require_once 'vendor/autoload.php';
 
-- PHP 8.1 or newer.
+use CommonPHP\DependencyInjection\DependencyInjector;
 
-### With Composer
+$injector = new DependencyInjector();
+$object = new stdClass();
+$values = ['property1' => 'value1', 'property2' => 'value2'];
 
-The easiest way to install the `CommonPHP Dependency Injection` library is via Composer.
+// populate public properties only
+$injector->populate($object, $values);
 
-If you don't have Composer installed, you can download it from [https://getcomposer.org/](https://getcomposer.org/).
+// populate all properties
+$injector->populate($object, $values, false);
+```
 
-Once you have Composer installed, you can install the `CommonPHP Dependency Injection` library by running the following command in your terminal:
+### Custom Lookup Hooks
 
-```bash
-composer require comphp/di
+The `ValueFinder` class allows you to add custom lookup hooks:
+
+```php
+<?php
+
+require_once 'vendor/autoload.php';
+
+use CommonPHP\DependencyInjection\DependencyInjector;
+
+$injector = new DependencyInjector();
+
+$injector->valueFinder->onLookup(function (string $name, string $typeName, bool &$found): mixed {
+    if ($typeName == MyClassType::class) {
+        $found = true;
+        return new MyClassType();
+    } else if ($name == 'specificStringVariable') {
+        $found = true;
+        return 'specificStringValue';
+    }
+    return null;
+});
 ```
 
-This command will add the `CommonPHP Dependency Injection` library as a dependency to your project, and Composer will automatically handle the autoloading of classes.
+## Documentation
+
+For more in-depth documentation, check out [the Wiki](https://github.com/commonphp/di/wiki).
+
+### API Reference
+
+This is a high-level overview of the API. For detailed information about classes, methods, and properties, please refer to the source code and accompanying PHPDoc comments.
+
+- **`CommonPHP\DependencyInjection\DependencyInjector`**: The main class in the library. Provides methods for instantiating classes, invoking methods, calling functions, and populating properties with automatic dependency resolution.
+
+    - **`instantiate(string $class, array $params = []): object`**: Instantiates a class with the provided parameters.
+
+    - **`invoke($object, string $method, array $params = [], bool $publicOnly = true): mixed`**: Invokes a method on a given object with the provided parameters.
+
+    - **`call(callable $callable, array $params = []): mixed`**: Calls a function or closure with the provided parameters.
+
+    - **`populate(object $object, array $values, bool $publicOnly = true): void`**: Populates the properties of an object with the given values.
+
+- **`CommonPHP\DependencyInjection\Support\ValueFinder`**: A supporting class that assists in discovering and managing parameter values during instantiation.
+
+    - **`onLookup(callable $callback): void`**: Registers a callback function to be used during the lookup process.
+
+### Examples
+
+Here are some examples of using CommonPHP\DependencyInjection. You can find the full source code for these examples in the `examples` directory of this repository.
 
-### Manual Installation
+- [**Instantiate**](https://github.com/commonphp/di/blob/master/examples/instantiate.php): This example shows how to instantiate a class using `DependencyInjector::instantiate()`.
 
-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.
+- [**Invoke**](https://github.com/commonphp/di/blob/master/examples/invoke.php): This example shows how to invoke a method using `DependencyInjector::invoke()`.
 
-After the installation, you can use the library as outlined in the Usage section.
+- [**Call**](https://github.com/commonphp/di/blob/master/examples/call.php): This example shows how to call a function or closure using `DependencyInjector::call()`.
 
-## Next Steps
+- [**Populate**](https://github.com/commonphp/di/blob/master/examples/populate.php): This example shows how to populate the properties of an object using `DependencyInjector::populate()`.
 
-After the installation, refer to the Usage section of this README to learn how to use the `CommonPHP Dependency Injection` library in your projects.
+- [**Lookup Hooks**](https://github.com/commonphp/di/blob/master/examples/lookup-hooks.php): This example shows how to use a custom lookup hook with `ValueFinder::onLookup()`.
+
+
+## Contributing
+
+Contributions are always welcome! Please read the [contribution guidelines](CONTRIBUTING.md) first.
 
 ## 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.
+This project uses PHPUnit for unit testing. Follow the instructions below to run the tests:
+
+1. Ensure you have PHPUnit installed. If not, you can install it with Composer:
+
+    ```bash
+    composer require --dev phpunit/phpunit
+    ```
+
+2. Navigate to the project's root directory.
+
+3. Run the tests using the following command:
+
+    ```bash
+    ./vendor/bin/phpunit tests
+    ```
+
+4. If the tests are successful, you will see output similar to:
+
+    ```
+    PHPUnit 9.6.9 by Sebastian Bergmann and contributors.
+
+    ......................                                            22 / 22 (100%)
+
+    Time: 00:00.228, Memory: 4.00 MB
 
-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.
+    OK (22 tests, 36 assertions)
+    ```
 
-If you are interested in contributing to testing, or any other aspect of this project, please see the 'Contributing' section for more information.
+We recommend regularly running these tests during development to help catch any potential issues early. We also strive for a high level of test coverage, and additions to the codebase should ideally include corresponding tests.
 
+For more detailed output or for integration into continuous integration (CI) systems, PHPUnit can generate a log file in a variety of formats. Check the [PHPUnit documentation](https://phpunit.de/documentation.html) for more information.
 
 ## License
 

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "comphp/di",
   "type": "library",
-  "version": "0.0.1",
+  "version": "0.1",
   "license": "MIT",
   "authors": [
     {
@@ -16,7 +16,7 @@
   },
   "autoload-dev": {
     "psr-4": {
-      "Test\\CommonPHP\\DependencyInjection\\": "tests/"
+      "CommonPHP\\Tests\\": "tests/"
     }
   },
   "require": {
@@ -25,4 +25,4 @@
   "require-dev": {
     "phpunit/phpunit": "^9.5.23"
   }
-}
+}