feat(helper): Add Reflector helper for class, property, type, and attribute metadata introspection.

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 0.2.1 Under development
 
+- Enh #0: Add `Reflector` helper for class, property, type, and attribute metadata introspection (@terabytesoftw)
+
 ## 0.2.0 February 25, 2024
 
 - Enh #6: Refactor codebase to improve performance (@terabytesoftw)

README.md

@@ -22,7 +22,7 @@
 
 <p align="center">
     <strong>Small, focused helpers for common PHP tasks</strong><br>
-    <em>Convert word casing, generate passwords, and list time zones with predictable output.</em>
+    <em>Convert word casing, inspect metadata, generate passwords, and list time zones with predictable output.</em>
 </p>
 
 ## Features
@@ -35,7 +35,7 @@
 ### Installation
 
 ```bash
-composer require php-forge/helper:^0.1
+composer require php-forge/helper:^0.2
 ```
 
 ### Quick start
@@ -115,12 +115,32 @@ $timezones = TimeZoneList::all();
 // [['timezone' => 'Pacific/Midway', 'name' => 'Pacific/Midway (UTC -11:00)', 'offset' => -39600], ...]
 ```
 
+#### Inspect class metadata with Reflector
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\Reflector;
+
+$shortName = Reflector::shortName(\App\Domain\User::class);
+$types = Reflector::propertyTypeNames(\App\Domain\User::class, 'email');
+$attributes = Reflector::propertyAttributes(\App\Domain\User::class, 'email');
+```
+
 ## Documentation
 
-For detailed setup, contribution flow, and test execution.
+For detailed configuration options and advanced usage.
 
+- 📚 [Installation Guide](docs/installation.md)
+- ⚙️ [Configuration Reference](docs/configuration.md)
+- 💡 [Usage Examples](docs/examples.md)
 - 🧪 [Testing Guide](docs/testing.md)
 - 🛠️ [Development Guide](docs/development.md)
+- 🔄 [Upgrade Guide](UPGRADE.md)
 
 ## Package information
 

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "php-forge/helper",
     "type": "library",
-    "description": "PHP Helper.",
+    "description": "PHPForge Helpers for Common PHP Tasks.",
     "keywords": [
         "php-forge",
         "helper",

docs/examples.md

@@ -0,0 +1,119 @@
+# Usage examples
+
+This document provides practical examples for word conversion, password generation, time zones, and reflection metadata.
+
+## Convert camelCase to snake_case
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\WordCaseConverter;
+
+$word = WordCaseConverter::camelToSnake('dateBirth');
+// date_birth
+```
+
+## Convert snake_case to camelCase
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\WordCaseConverter;
+
+$word = WordCaseConverter::snakeToCamel('date_birth');
+// dateBirth
+```
+
+## Convert text to title words
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\WordCaseConverter;
+
+$word = WordCaseConverter::toTitleWords('dateOfMessage');
+// Date Of Message
+```
+
+## Generate passwords
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\PasswordGenerator;
+
+$password = PasswordGenerator::generate(12);
+// e.g. aB3#kL9!mN2@
+```
+
+## Retrieve all time zones
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\TimeZoneList;
+
+$timezones = TimeZoneList::all();
+// [['timezone' => 'Pacific/Midway', 'name' => 'Pacific/Midway (UTC -11:00)', 'offset' => -39600], ...]
+```
+
+## Inspect class metadata with Reflector
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\Reflector;
+
+$shortName = Reflector::shortName(\App\Domain\User::class);
+$hasEmail = Reflector::hasProperty(\App\Domain\User::class, 'email');
+$typeNames = Reflector::propertyTypeNames(\App\Domain\User::class, 'email');
+$attributes = Reflector::propertyAttributes(\App\Domain\User::class, 'email');
+```
+
+## Reflector cache lifecycle in long-running workers
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PHPForge\Helper\Reflector;
+
+$size = Reflector::cacheSize();
+
+if ($size > 400) {
+    Reflector::clearCache();
+}
+```
+
+## Next steps
+
+- 📚 [Installation guide](installation.md)
+- 🧪 [Testing guide](testing.md)
+- 🛠️ [Development guide](development.md)

docs/installation.md

@@ -0,0 +1,40 @@
+# Installation guide
+
+## System requirements
+
+- [`PHP`](https://www.php.net/downloads) 8.1 or higher.
+- [`Composer`](https://getcomposer.org/download/) for dependency management.
+
+## Installation
+
+### Method 1: Using [Composer](https://getcomposer.org/download/) (recommended)
+
+Install the package.
+
+```bash
+composer require php-forge/helper:^0.2
+```
+
+### Method 2: Manual installation
+
+Add to your `composer.json`.
+
+```json
+{
+    "require": {
+        "php-forge/helper": "^0.2"
+    }
+}
+```
+
+Then run.
+
+```bash
+composer update
+```
+
+## Next steps
+
+- 💡 [Usage examples](examples.md)
+- 🧪 [Testing guide](testing.md)
+- 🛠️ [Development guide](development.md)

src/Exception/Message.php

@@ -23,6 +23,20 @@ enum Message: string
      */
     case PASSWORD_LENGTH_TOO_SHORT = "Password length must be at least '%d' characters.";
 
+    /**
+     * Error message for missing reflected property.
+     *
+     * Format: "Property '%s' does not exist in '%s'."
+     */
+    case REFLECTOR_PROPERTY_NOT_FOUND = "Property '%s' does not exist in '%s'.";
+
+    /**
+     * Error message for invalid reflection target.
+     *
+     * Format: "Invalid reflection target '%s'."
+     */
+    case REFLECTOR_TARGET_INVALID = "Invalid reflection target '%s'.";
+
     /**
      * Returns the formatted message string for the error case.
      *