feat: Implement EnumCase for direct access to enum cases and add tests

Author: jmjoy

phper-doc/doc/_06_module/_08_register_enum/index.md

@@ -225,19 +225,20 @@ $colorFromValue = Color::from("FF0000"); // Returns RED
 $colorOrNull = Color::tryFrom("INVALID"); // Returns null (when the value doesn't exist)
 ```
 
-## Accessing Enums from Rust Code
+## Using EnumCase for Direct Access
 
-After registering an enum, you might need to access it from Rust code. `PHPER` provides two ways to do this:
+When you call `add_case()` on an enum entity, it returns an `EnumCase` instance that you can use for direct access to that case later. This is more efficient than looking up the enum case by name each time you need it.
 
-1. Using the returned `Enum` instance when registering the enum
-2. Using `Enum::from_name` to look up an enum by name
-
-### Using the Returned `Enum` Instance
-
-When you register an enum using `module.add_enum()`, it returns an `Enum` instance that you can save and use later.
+Here's an example showing how to use EnumCase within static methods of the enum:
 
 ```rust,no_run
-use phper::{modules::Module, php_get_module, enums::{EnumEntity, Enum}};
+use phper::{
+    modules::Module, 
+    php_get_module, 
+    enums::EnumEntity, 
+    classes::Visibility,
+    alloc::ToRefOwned,
+};
 
 #[php_get_module]
 pub fn get_module() -> Module {
@@ -247,96 +248,148 @@ pub fn get_module() -> Module {
         env!("CARGO_PKG_AUTHORS"),
     );
 
-    // Create and register the enum
-    let mut status_entity = EnumEntity::new("Status");
-    status_entity.add_case("ACTIVE", ());
-    status_entity.add_case("INACTIVE", ());
+    // Create a pure enum
+    let mut pure_enum_entity = EnumEntity::new("PureEnum");
+    
+    // Store references to enum cases when adding them
+    let one_case = pure_enum_entity.add_case("ONE", ());
+    let _two_case = pure_enum_entity.add_case("TWO", ());
+    
+    // Add static method that returns the ONE case
+    pure_enum_entity.add_static_method("getOneCase", Visibility::Public, {
+        // Clone the EnumCase because it will be moved into the closure
+        move |_| {
+            // Get the case object directly from EnumCase
+            let one_obj = one_case.clone().get_mut_case();
+            let result = one_obj.to_ref_owned();
+            phper::ok(result)
+        }
+    });
+    
+    // Register the enum to the module
+    module.add_enum(pure_enum_entity);
+
+    // Create an int-backed enum
+    let mut int_enum_entity = EnumEntity::<i64>::new("IntEnum");
     
-    // Save the returned Enum instance
-    let status_enum: Enum = module.add_enum(status_entity);
+    // Store reference to LOW case
+    let low_case = int_enum_entity.add_case("LOW", 10);
+    let _high_case = int_enum_entity.add_case("HIGH", 100);
     
-    // Use the saved enum instance in a function
-    module.add_function("get_active_status", move |_| {
-        // Get the ACTIVE case from the enum
-        let active_case = status_enum.get_case("ACTIVE")?;
-        Ok::<_, phper::Error>(active_case)
+    // Add static method that returns the LOW case
+    int_enum_entity.add_static_method("getLowCase", Visibility::Public, {
+        move |_| {
+            let low_obj = low_case.clone().get_mut_case();
+            let result = low_obj.to_ref_owned();
+            phper::ok(result)
+        }
     });
+    
+    // Register the enum to the module
+    module.add_enum(int_enum_entity);
 
     module
 }
 ```
 
-### Using `Enum::from_name`
+This creates PHP enums with static methods that can access specific cases:
 
-If you don't have the original `Enum` instance, you can use `Enum::from_name` to look up an enum by its name.
+```php
+enum PureEnum {
+    case ONE;
+    case TWO;
+    
+    public static function getOneCase(): self {
+        return self::ONE;
+    }
+}
+
+enum IntEnum: int {
+    case LOW = 10;
+    case HIGH = 100;
+    
+    public static function getLowCase(): self {
+        return self::LOW;
+    }
+}
+```
+
+## Using Enum::from_name
+
+If you don't have direct access to the EnumCase, you can use `Enum::from_name()` to get an enum by its name, and then use `get_case()` or `get_mut_case()` to access specific cases:
 
 ```rust,no_run
-use phper::{enums::Enum, modules::Module, php_get_module};
+use phper::{
+    enums::Enum,
+    enums::EnumEntity,
+    classes::Visibility,
+    alloc::ToRefOwned,
+};
 
-#[php_get_module]
-pub fn get_module() -> Module {
-    let mut module = Module::new(
-        env!("CARGO_CRATE_NAME"),
-        env!("CARGO_PKG_VERSION"),
-        env!("CARGO_PKG_AUTHORS"),
-    );
+fn create_enum_with_dynamic_lookup() -> EnumEntity {
+    let mut enum_entity = EnumEntity::new("DynamicEnum");
+    enum_entity.add_case("ONE", ());
+    enum_entity.add_case("TWO", ());
     
-    // Register functions that use enums
-    module.add_function("get_status_case", |args| {
-        // Look up the Status enum by name
-        let status_enum = Enum::from_name("Status");
+    // Add a static method that looks up cases dynamically
+    enum_entity.add_static_method("getCaseByName", Visibility::Public, |args| {
+        // Get case name from parameters
+        let case_name = args[0].expect_z_str()?.to_string_lossy();
         
-        // Get the case name from the function arguments
-        let case_name = args[0].as_z_str()?.to_str()?;
+        // Use Enum::from_name to get the enum
+        let mut enum_obj = Enum::from_name("DynamicEnum");
         
-        // Get the requested enum case
-        let case = status_enum.get_case(case_name)?;
+        // Try to get the requested case
+        let case = unsafe { enum_obj.get_mut_case(&case_name)? };
+        let result = case.to_ref_owned();
         
-        Ok::<_, phper::Error>(case)
+        phper::ok(result)
     });
-
-    module
+    
+    enum_entity
 }
 ```
 
-## Getting Enum Cases
+> **Important**: The `get_case()` and `get_mut_case()` methods on `Enum` are marked as unsafe because they can cause segmentation faults if the case doesn't exist.
 
-Once you have an `Enum` instance, you can use the `get_case` method to access specific enum cases:
+## Bound Enum
 
-```rust,no_run
-// Get a case from a pure enum
-let status_enum = Enum::from_name("Status");
-let active_case = status_enum.get_case("ACTIVE")?;
-
-// Get a case from a backed enum
-let level_enum = Enum::from_name("Level");
-let high_level = level_enum.get_case("HIGH")?;
-```
-
-If you need to modify an enum case's properties, you can use `get_case_mut` to get a mutable reference:
+You can use the `bound_enum()` method to get a reference to the enum that can be used in methods or functions:
 
 ```rust,no_run
-// Get a mutable reference to an enum case
-let mut status_enum = Enum::from_name("Status");
-let mut active_case = status_enum.get_case_mut("ACTIVE")?;
+use phper::{enums::EnumEntity, classes::Visibility, alloc::ToRefOwned};
 
-// Now you can modify the case object if needed
+pub fn make_status_enum() -> EnumEntity {
+    let mut enum_entity = EnumEntity::new("Status");
+    enum_entity.add_case("Active", ());
+    enum_entity.add_case("Inactive", ());
+    
+    // Get a reference to the enum that will be created
+    let status_enum = enum_entity.bound_enum();
+    
+    // Add a static method that uses the bound enum
+    enum_entity.add_static_method("getActiveCase", Visibility::Public, move |_| {
+        // Use the bound enum to get the Active case
+        let active_case = unsafe { status_enum.clone().get_mut_case("Active")? };
+        phper::ok(active_case.to_ref_owned())
+    });
+    
+    enum_entity
+}
 ```
 
-If the specified case doesn't exist in the enum, both `get_case` and `get_case_mut` will return an `EnumCaseNotFoundError`.
-
 ## Complete Example
 
-Here's a comprehensive example using both pure and backed enums:
+Here's a comprehensive example using both pure and backed enums with static methods:
 
 ```rust,no_run
 use phper::{
     modules::Module, 
     php_get_module, 
     enums::EnumEntity, 
-    classes::Visibility
+    classes::Visibility,
+    alloc::ToRefOwned,
 };
-use std::convert::Infallible;
 
 #[php_get_module]
 pub fn get_module() -> Module {
@@ -348,19 +401,44 @@ pub fn get_module() -> Module {
 
     // Pure enum
     let mut status = EnumEntity::new("Status");
-    status.add_case("PENDING", ());
-    status.add_case("ACTIVE", ());
-    status.add_case("INACTIVE", ());
+    let pending_case = status.add_case("PENDING", ());
+    let active_case = status.add_case("ACTIVE", ());
+    let inactive_case = status.add_case("INACTIVE", ());
+    
+    // Add constants
     status.add_constant("VERSION", "1.0.0");
+    
+    // Add static method that returns the active state
+    status.add_static_method("getActiveStatus", Visibility::Public, {
+        move |_| {
+            let obj = active_case.clone().get_mut_case();
+            phper::ok(obj.to_ref_owned())
+        }
+    });
+    
+    // Add static method that returns status description
     status.add_static_method("getDescription", Visibility::Public, |_| {
-        Ok::<_, Infallible>("Status enumeration")
+        phper::ok("Status enumeration")
     });
     
     // Integer-backed enum
     let mut level = EnumEntity::<i64>::new("Level");
-    level.add_case("LOW", 1);
-    level.add_case("MEDIUM", 5);
-    level.add_case("HIGH", 10);
+    let low_case = level.add_case("LOW", 1);
+    let medium_case = level.add_case("MEDIUM", 5);
+    let high_case = level.add_case("HIGH", 10);
+    
+    // Add static method that returns level by value
+    level.add_static_method("getLevelByValue", Visibility::Public, {
+        move |args| {
+            let value: i64 = args[0].expect_long()?;
+            let case_obj = match value {
+                v if v < 3 => low_case.clone().get_mut_case(),
+                v if v < 8 => medium_case.clone().get_mut_case(),
+                _ => high_case.clone().get_mut_case(),
+            };
+            phper::ok(case_obj.to_ref_owned())
+        }
+    });
     
     // Register enums to the module
     module.add_enum(status);