Initial version

Author: tlmcclatchey

.gitignore

@@ -0,0 +1,4 @@
+.idea/
+composer.lock
+vendor/
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 commonphp
+
+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.

composer.json

@@ -0,0 +1,29 @@
+{
+  "name": "comphp/drivers",
+  "type": "library",
+  "description": "Allows for drivers to be dynamically managed",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "timothy.mcclatchey",
+      "email": "[email protected]"
+    }
+  ],
+  "autoload": {
+    "psr-4": {
+      "CommonPHP\\Drivers\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "CommonPHP\\Tests\\Drivers\\": "tests/"
+    }
+  },
+  "require": {
+    "php": "^8.3",
+    "comphp/service-management": "^0.2"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^10.5.9"
+  }
+}

examples/general-usage.php

@@ -0,0 +1,70 @@
+<?php
+
+// Required namespaces for Driver Management and Service Management components.
+use CommonPHP\Drivers\Contracts\DriverAttributeContract;
+use CommonPHP\Drivers\Contracts\DriverContract;
+use CommonPHP\Drivers\DriverManager;
+use CommonPHP\ServiceManagement\ServiceManager;
+use CommonPHP\Drivers\ServiceProviders\DriverManagerServiceProvider;
+
+// Include Composer's autoloader to handle class loading.
+require_once '../vendor/autoload.php';
+
+// Define a custom attribute for drivers, implementing the DriverAttributeContract.
+#[Attribute(Attribute::TARGET_CLASS)]
+class GeneralExampleDriverAttribute implements DriverAttributeContract
+{
+    // This class is empty but serves as a marker for driver classes using attributes.
+}
+
+// Define a contract that drivers can implement, extending the base DriverContract.
+interface GeneralExampleDriverContract extends DriverContract
+{
+    // Interface body remains empty for this example, acting as a marker.
+}
+
+// Abstract class that implements the DriverContract, can be extended by concrete driver classes.
+abstract class AbstractGeneralExampleDriver implements DriverContract
+{
+    // Abstract class body is empty, serving as a base for specific drivers.
+}
+
+// Factory class configured to use the DriverManager with an attribute-based configuration.
+class AttributeDemoFactory
+{
+    public function __construct(DriverManager $driverManager)
+    {
+        // Configures the DriverManager to recognize drivers by the specified attribute.
+        $driverManager->configure(GeneralExampleDriverAttribute::class, null);
+    }
+}
+
+// Factory class configured to use the DriverManager with a contract-based configuration.
+class ContractDemoFactory
+{
+    public function __construct(DriverManager $driverManager)
+    {
+        // Configures the DriverManager to recognize drivers implementing the specified contract.
+        $driverManager->configure(null, GeneralExampleDriverContract::class);
+    }
+}
+
+// Factory class configured to use both attribute and contract-based configurations.
+class AttributeContractDemoFactory
+{
+    public function __construct(DriverManager $driverManager)
+    {
+        // Configures the DriverManager to recognize drivers both by attribute and by implementing a contract.
+        $driverManager->configure(GeneralExampleDriverAttribute::class, AbstractGeneralExampleDriver::class);
+    }
+}
+
+// Instantiate the ServiceManager and register the DriverManagerServiceProvider for dependency management.
+$serviceManager = new ServiceManager();
+$serviceManager->providers->registerProvider(DriverManagerServiceProvider::class);
+
+// Instantiate each factory class, triggering their respective configuration logic in the DriverManager.
+// These demonstrate different ways to utilize the DriverManager for managing drivers.
+$serviceManager->di->instantiate(AttributeDemoFactory::class, []);
+$serviceManager->di->instantiate(ContractDemoFactory::class, []);
+$serviceManager->di->instantiate(AttributeContractDemoFactory::class, []);

readme.md

@@ -0,0 +1,72 @@
+# CommonPHP Driver Management Library
+
+The CommonPHP Driver Management Library provides a robust framework for managing driver implementations in PHP applications. By leveraging attributes and contracts, it offers a flexible system to register, enable, and utilize various drivers seamlessly within your projects.
+
+## Features
+
+- **Flexible Driver Configuration**: Configure drivers using PHP 8 Attributes or by specifying driver contracts.
+- **Dynamic Driver Support Checking**: Determine if a class is supported as a driver based on its configuration.
+- **Driver Instantiation**: On-demand driver instantiation managed by the CommonPHP Service Management framework, ensuring dependency injection and singleton management.
+- **Comprehensive Exception Handling**: Detailed exception handling for configuration errors, unsupported drivers, and instantiation issues.
+
+## Installation
+
+Use Composer to integrate the Driver Management Library into your project:
+
+```bash
+composer require comphp/drivers
+```
+
+## Configuration
+
+### Define Driver Contracts or Attributes
+
+Implement `DriverContract` for interface/abstract class-based drivers or use `DriverAttributeContract` to mark drivers with attributes.
+
+### Register and Configure DriverManager
+
+```php
+use CommonPHP\Drivers\DriverManager;
+use CommonPHP\Drivers\ServiceProviders\DriverManagerServiceProvider;
+use CommonPHP\ServiceManagement\ServiceManager;
+
+// Initialize ServiceManager and register DriverManagerServiceProvider
+$serviceManager = new ServiceManager();
+$serviceManager->providers->registerProvider(DriverManagerServiceProvider::class);
+
+// Retrieve an instance of DriverManager
+$driverManager = $serviceManager->get(DriverManager::class);
+
+// Configure DriverManager with an attribute or contract class
+$driverManager->configure(
+    attributeClass: YourDriverAttribute::class,
+    contractClass: YourDriverContract::class
+);
+```
+
+## Usage
+
+### Enable a Driver
+
+Once a driver meets the configured criteria (attribute or contract), enable it using:
+
+```php
+$driverManager->enable(YourDriverClass::class);
+```
+
+### Utilize an Enabled Driver
+
+Retrieve and use an enabled driver:
+
+```php
+$driver = $driverManager->get(YourDriverClass::class);
+$driver->performAction();
+```
+
+## Contributing
+
+Contributions to the CommonPHP Driver Management Library are welcome. Please follow the contribution guidelines provided in the repository for submitting pull requests or issues.
+
+## License
+
+This library is released under the MIT license. See [LICENSE](LICENSE) for details.

src/Contracts/DriverAttributeContract.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * DriverAttributeContract.php
+ *
+ * Defines a contract for driver attributes within the CommonPHP Driver Management system. This interface
+ * is intentionally left empty to serve as a marker for PHP 8 Attributes that can be used to identify
+ * driver classes. By implementing this contract, attributes signal their capability to participate in
+ * the driver management process, allowing the DriverManager to recognize and manage them accordingly.
+ *
+ * Although empty, the presence of this contract is crucial for the architecture of the driver management
+ * system, providing a standardized way to designate attributes as part of the driver identification
+ * mechanism.
+ *
+ * @package CommonPHP\Drivers\Contracts
+ * @author Timothy McClatchey <[email protected]>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ */
+
+namespace CommonPHP\Drivers\Contracts;
+
+interface DriverAttributeContract
+{
+    // This interface is intentionally left empty as a marker for driver attributes.
+}

src/Contracts/DriverContract.php

@@ -0,0 +1,26 @@
+<?php
+/**
+ * DriverContract.php
+ *
+ * Defines a contract for drivers within the CommonPHP Driver Management system. This interface
+ * is intentionally left empty to serve as a marker for classes that can be considered drivers.
+ * Implementing this contract allows the DriverManager to recognize and manage these classes
+ * as part of the driver system.
+ *
+ * The absence of methods within this contract underscores its role as a flexible marker,
+ * enabling a wide variety of classes to qualify as drivers without imposing specific
+ * implementation requirements. It is an essential component of the driver management
+ * architecture, facilitating the dynamic discovery and utilization of drivers.
+ *
+ * @package CommonPHP\Drivers\Contracts
+ * @author Timothy McClatchey <[email protected]>
+ * @copyright 2024 CommonPHP.org
+ * @license http://opensource.org/licenses/MIT MIT License
+ */
+
+namespace CommonPHP\Drivers\Contracts;
+
+interface DriverContract
+{
+    // This interface is intentionally left empty as a marker
+}