Register class
Registering classes is a bit more complicated than others.
First, you have to instantiate the class builder
ClassEntity, then register the parent class or
implements interfaces, add the properties and methods, finally add it into the
Module.
Here is the simplest example:
use phper::{classes::ClassEntity, modules::Module, php_get_module};
#[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"),
);
let foo = ClassEntity::new("Foo");
module.add_class(foo);
module
}
Similarly in PHP:
<?php
class Foo {}
Extends & implements
To allow a class to extend another, you can use ClassEntity.extends(StateClass<T>).
A StateClass can either be obtained by registering your own class against the module, or
by looking up the class by name (for example, for PHP built-in classes like Exception).
If you want class Foo extends Bar, and implements interface Stringable:
use phper::classes::{ClassEntity, ClassEntry, Interface};
use phper::{modules::Module, php_get_module};
let mut module = Module::new("test", "0.1", "");
let bar = module.add_class(ClassEntity::new("Bar"));
let mut foo = ClassEntity::new("Foo");
foo.extends(bar);
foo.implements(Interface::from_name("Stringable"));
You should implement the method Stringable::__toString after implementing
Stringable, otherwise the class Foo will become abstract class.
Final classes
To forbid extending a class, use ClassEntity::set_final:
use phper::classes::ClassEntity;
let mut foo = ClassEntity::new("Foo");
foo.set_final();
Userland code extending Foo then fails to compile with a fatal error, exactly
as for a final class declared in PHP. final classes are available in every
PHP version PHPER supports, so this needs no minimum version.
Note that this applies to classes registered by your extension too: if another
ClassEntity extends Foo, the error is raised while the module starts up
rather than when userland calls into it.
Readonly classes
To make every property of a class readonly, use ClassEntity::set_readonly:
use phper::classes::{ClassEntity, Visibility};
use phper::types::PropertyTypeHint;
let mut foo = ClassEntity::new("Foo");
foo.set_readonly();
foo.add_typed_property("bar", Visibility::Public, PropertyTypeHint::Int, None);
Similarly in PHP:
<?php
readonly class Foo {
public int $bar;
}
As in PHP, every property of a readonly class must be typed, non-static and have no default, or the module panics at startup. Dynamic properties are refused.
Readonly classes need PHP 8.2. On PHP 8.0 and 8.1 only dynamic properties are refused, and on PHP 7 the class is unchanged.
Add properties
Due to the limitation of PHP, you can only use copyable values as class properties.
use phper::classes::{ClassEntity, ClassEntry, Visibility};
let mut foo = ClassEntity::new("Foo");
foo.add_property("prop", Visibility::Public, "the prop value");
Typed properties
add_typed_property declares a property with a type. Its default is
Option<Scalar>, and None leaves the property uninitialized, so reading it
before a write throws Error. Call allow_null to make the type nullable.
use phper::classes::{ClassEntity, Visibility};
use phper::types::PropertyTypeHint;
let mut foo = ClassEntity::new("Foo");
foo.add_typed_property("count", Visibility::Public, PropertyTypeHint::Int, Some(0.into()));
foo.add_typed_property("name", Visibility::Public, PropertyTypeHint::String, None);
foo.add_typed_property(
"parent",
Visibility::Private,
PropertyTypeHint::ClassEntry(String::from(r"\MyNamespace\Node")),
Some(().into()),
)
.allow_null();
Similarly in PHP:
<?php
class Foo {
public int $count = 0;
public string $name;
private ?\MyNamespace\Node $parent = null;
}
The default is checked against the type as PHP checks a userland one, and the
module panics at startup if it does not match. A Mixed property takes any
default. A null default needs allow_null. An int default on a Float
property is converted to float. Array, Object, Iterable and class-typed
properties can only default to null, since Scalar holds neither arrays nor
objects. The check runs on every PHP version, including PHP 7.
Typed properties need PHP 8.0. On PHP 7 the property is declared untyped, with its default, or null if it has none.
Readonly properties
add_readonly_property declares a typed, uninitialized property that can be
written once.
use phper::classes::{ClassEntity, Visibility};
use phper::functions::Argument;
use phper::types::PropertyTypeHint;
let mut foo = ClassEntity::new("Foo");
foo.add_readonly_property("id", Visibility::Public, PropertyTypeHint::Int);
foo.add_method("__construct", Visibility::Public, |this, arguments| {
this.set_property("id", arguments[0].clone());
Ok::<_, phper::Error>(())
})
.argument(Argument::new("id"));
Similarly in PHP:
<?php
class Foo {
public readonly int $id;
public function __construct($id) {
$this->id = $id;
}
}
Readonly properties need PHP 8.1. On PHP 8.0 the property is a plain typed property, and on PHP 7 an untyped one.
PHP does not allow a default on a readonly property, nor a static one, so there is no way to declare either.
Before PHP 8.4, a method of Foo cannot initialize the property on an instance
of a userland subclass of Foo. set_property uses the object’s class as the
scope, and PHP 8.1 to 8.3 allow initialization only from the declaring class.
Promoted constructor properties are a compile-time feature of PHP and have no equivalent here. Declare the property and write it from the constructor.
Typed static properties
add_static_typed_property declares a static property with a type. It takes
the same arguments as add_typed_property, and its default is checked the same
way.
use phper::classes::{ClassEntity, Visibility};
use phper::types::PropertyTypeHint;
let mut foo = ClassEntity::new("Foo");
foo.add_static_typed_property("count", Visibility::Public, PropertyTypeHint::Int, Some(0.into()));
foo.add_static_typed_property("name", Visibility::Private, PropertyTypeHint::String, None);
Similarly in PHP:
<?php
class Foo {
public static int $count = 0;
private static string $name;
}
Typed static properties need PHP 8.0. On PHP 7 the property is declared untyped, with its default, or null if it has none.
PHP checks the type when userland assigns the property.
ClassEntry::set_static_property
does not, so a value of the wrong type is stored as given.
Add methods
Adding class methods is similar with adding module functions, the difference is that
adding class methods increases Visibility and $this object.
use phper::classes::{ClassEntity, ClassEntry, Visibility};
use phper::objects::StateObj;
use phper::values::ZVal;
let mut foo = ClassEntity::new("Foo");
foo.add_method(
"getProp",
Visibility::Public,
|this: &mut StateObj<()>, _: &mut [ZVal]| {
let prop = this.get_property("foo");
Ok::<_, phper::Error>(prop.clone())
},
);
Adding static class methods is more like adding module functions, because there is no
$this variable.
use phper::classes::{ClassEntity, ClassEntry, Visibility};
use phper::functions::Argument;
use phper::values::ZVal;
let mut foo = ClassEntity::new("Foo");
foo.add_static_method(
"staticSayHello",
Visibility::Public,
|arguments: &mut [ZVal]| {
let name = arguments[0].expect_z_str()?.to_str()?;
Ok::<_, phper::Error>(format!("Hello, {}!\n", name))
},
).argument(Argument::new("name"));
Argument and return type modifiers
Methods may add argument and return typehints as per functions. For example:
use phper::classes::{ClassEntity, ClassEntry, Visibility};
use phper::functions::{Argument, ReturnType};
use phper::types::{ArgumentTypeHint, ReturnTypeHint};
let mut foo = ClassEntity::new("Foo");
foo.add_method(
"test",
Visibility::Public,
|_this, _arguments| -> phper::Result<()> {
Ok(())
},
)
.argument(Argument::new("a_string").with_type_hint(ArgumentTypeHint::String))
.argument(Argument::new("an_interface").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface"))))
.return_type(ReturnType::new(ReturnTypeHint::Bool).allow_null());
Add constants
Interfaces can have public constants. Value can be string|int|bool|float|null.
use phper::classes::ClassEntity;
let mut foo = ClassEntity::new("Foo");
foo.add_constant("ONE", "one");
foo.add_constant("TWO", 2);
foo.add_constant("THREE", 3.0);
Handle state
The
ClassEntityrepresents the class entry hold the state as generic type, so you can wrap the Rust struct as state in PHP class, which is the common usage of class in php extensions (if using C/C++ to develop PHP extension, the PHP class commonly wrap the C/C++ pointer).
Imagine that we encapsulate Rust’s HashMap for PHP.
First, we register the class hold the state with type HashMap, then add the method
to insert key value pair.
use std::collections::HashMap;
use phper::classes::{ClassEntity, ClassEntry, Visibility};
use phper::functions::Argument;
let mut class =
ClassEntity::<HashMap<String, String>>::new_with_state_constructor(
"MyHashMap", HashMap::new);
class.add_method(
"insert",
Visibility::Public,
|this, arguments| {
let key = arguments[0].expect_z_str()?.to_str()?.to_string();
let value = arguments[1].expect_z_str()?.to_str()?.to_string();
let state = this.as_mut_state();
state.insert(key, value);
Ok::<_, phper::Error>(())
},
)
.argument(Argument::new("key"))
.argument(Argument::new("value"));
Equivalent to the following PHP code (hides the implementation details):
<?php
class MyHashMap {
public void insert() {
// ...
}
}
Circular class dependencies
If you wish to register classes which depend on each other, you can retrieve the bound class (StateClass<T>)
from a ClassEntity, and use it in functions and methods:
use phper::{
classes::{ClassEntity, StateClass, Visibility},
modules::Module,
};
let mut module = Module::new(
env!("CARGO_CRATE_NAME"),
env!("CARGO_PKG_VERSION"),
env!("CARGO_PKG_AUTHORS"),
);
let mut a_cls = ClassEntity::new("A");
let mut b_cls = ClassEntity::new("B");
let a_bound_class = a_cls.bound_class();
let b_bound_class = b_cls.bound_class();
a_cls.add_static_method("createB", Visibility::Public, move |_| {
let object = b_bound_class.init_object()?;
Ok::<_, phper::Error>(object)
});
b_cls.add_static_method("createA", Visibility::Public, move |_| {
let object = a_bound_class.init_object()?;
Ok::<_, phper::Error>(object)
});
module.add_class(a_cls);
module.add_class(b_cls);
This is equivalent to the following PHP code:
class A {
public static function createB(): B {
return new B();
}
}
class B {
public static function createA(): A {
return new A();
}
}