Register Enums
PHP 8.1 and above introduced the Enum functionality.
PHPERallowing you to create PHP enums using Rust code.
In PHPER, you can use the add_enum method to register enums.
According to PHP’s enum specification, PHPER supports three types of enums:
- Pure enums (without values)
- Integer-backed enums
- String-backed enums
Creating Pure Enums
Pure enums are the simplest type of enum, having only member names without associated values. Use EnumEntity<()> to create a pure enum (or simply use EnumEntity::new() since () is the default type parameter).
use phper::{modules::Module, php_get_module, enums::EnumEntity, classes::Visibility};
#[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"),
);
// Create a pure enum
let mut status = EnumEntity::new("Status");
// Add enum cases (without values)
status.add_case("PENDING", ());
status.add_case("ACTIVE", ());
status.add_case("INACTIVE", ());
// Register the enum to the module
module.add_enum(status);
module
}
This is equivalent to the following PHP code:
enum Status {
case PENDING;
case ACTIVE;
case INACTIVE;
}
Creating Integer-Backed Enums
Integer-backed enums associate each enum member with an integer value. Use EnumEntity<i64> to create an integer-backed enum.
use phper::{modules::Module, php_get_module, enums::EnumEntity};
#[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"),
);
// Create an integer-backed enum
let mut level = EnumEntity::<i64>::new("Level");
// Add enum cases with their associated integer values
level.add_case("LOW", 1);
level.add_case("MEDIUM", 5);
level.add_case("HIGH", 10);
// Register the enum to the module
module.add_enum(level);
module
}
This is equivalent to the following PHP code:
enum Level: int {
case LOW = 1;
case MEDIUM = 5;
case HIGH = 10;
}
Creating String-Backed Enums
String-backed enums associate each enum member with a string value. Use EnumEntity<String> to create a string-backed enum.
use phper::{modules::Module, php_get_module, enums::EnumEntity};
#[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"),
);
// Create a string-backed enum
let mut color = EnumEntity::<String>::new("Color");
// Add enum cases with their associated string values
color.add_case("RED", "FF0000".to_string());
color.add_case("GREEN", "00FF00".to_string());
color.add_case("BLUE", "0000FF".to_string());
// Register the enum to the module
module.add_enum(color);
module
}
This is equivalent to the following PHP code:
enum Color: string {
case RED = "FF0000";
case GREEN = "00FF00";
case BLUE = "0000FF";
}
Adding Constants
Enums can contain constants. Use the add_constant method to add constants to an enum.
use phper::{modules::Module, php_get_module, enums::EnumEntity};
let mut status = EnumEntity::new("Status");
// Add enum cases
status.add_case("PENDING", ());
status.add_case("ACTIVE", ());
// Add constants
status.add_constant("VERSION", "1.0.0");
status.add_constant("MAX_ATTEMPTS", 3);
This is equivalent to the following PHP code:
enum Status {
case PENDING;
case ACTIVE;
public const VERSION = "1.0.0";
public const MAX_ATTEMPTS = 3;
}
Adding Static Methods
You can add static methods to enums. Use the add_static_method method to add a static method to an enum.
use phper::{modules::Module, php_get_module, enums::EnumEntity, classes::Visibility};
use std::convert::Infallible;
let mut status = EnumEntity::new("Status");
// Add enum cases
status.add_case("PENDING", ());
status.add_case("ACTIVE", ());
// Add static method
status.add_static_method("getDescription", Visibility::Public, |_| {
Ok::<_, Infallible>("Status enumeration for tracking item states")
});
This is equivalent to the following PHP code:
enum Status {
case PENDING;
case ACTIVE;
public static function getDescription(): string {
return "Status enumeration for tracking item states";
}
}
Implementing Interfaces
You can make enums implement interfaces. Use the implements method to make an enum implement a specific interface.
use phper::{modules::Module, php_get_module, enums::EnumEntity, classes::Interface};
let mut color = EnumEntity::<String>::new("Color");
// Add enum cases
color.add_case("RED", "FF0000".to_string());
color.add_case("GREEN", "00FF00".to_string());
// Implement interface
color.implements(Interface::from_name("JsonSerializable"));
// Note: You need to add necessary methods to satisfy interface requirements
// For example, JsonSerializable interface requires the implementation of jsonSerialize method
Using Built-in Enum Methods
PHP enums come with some built-in methods. Pure enums (UnitEnum) have the cases() method, while backed enums (BackedEnum) additionally have the from() and tryFrom() methods.
// Examples of using built-in methods in PHP
$allCases = Color::cases(); // Returns an array of all enum cases
// Only available for backed enums
$colorFromValue = Color::from("FF0000"); // Returns RED
$colorOrNull = Color::tryFrom("INVALID"); // Returns null (when the value doesn't exist)
Using EnumCase for Direct Access
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.
Here’s an example showing how to use EnumCase within static methods of the enum:
use phper::{
modules::Module,
php_get_module,
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"),
);
// 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");
// 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);
// 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
}
This creates PHP enums with static methods that can access specific cases:
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:
use phper::{
enums::Enum,
enums::EnumEntity,
classes::Visibility,
alloc::ToRefOwned,
};
fn create_enum_with_dynamic_lookup() -> EnumEntity {
let mut enum_entity = EnumEntity::new("DynamicEnum");
enum_entity.add_case("ONE", ());
enum_entity.add_case("TWO", ());
// 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();
// Use Enum::from_name to get the enum
let mut enum_obj = Enum::from_name("DynamicEnum");
// Try to get the requested case
let case = unsafe { enum_obj.get_mut_case(&case_name)? };
let result = case.to_ref_owned();
phper::ok(result)
});
enum_entity
}
Important: The
get_case()andget_mut_case()methods onEnumare marked as unsafe because they can cause segmentation faults if the case doesn’t exist.
Bound Enum
You can use the bound_enum() method to get a reference to the enum that can be used in methods or functions:
use phper::{enums::EnumEntity, classes::Visibility, alloc::ToRefOwned};
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
}
Complete Example
Here’s a comprehensive example using both pure and backed enums with static methods:
use phper::{
modules::Module,
php_get_module,
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"),
);
// Pure enum
let mut status = EnumEntity::new("Status");
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, |_| {
phper::ok("Status enumeration")
});
// Integer-backed enum
let mut level = EnumEntity::<i64>::new("Level");
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);
module.add_enum(level);
module
}
Note: PHP enums require PHP 8.1 or higher. Make sure your extension sets the correct PHP version requirements.