Add Module::add_info method, supplement module document. (#98)

Author: jmjoy

examples/complex/src/lib.rs

@@ -94,5 +94,8 @@ pub fn get_module() -> Module {
         .argument(Argument::by_val("foo"));
     module.add_class(foo_class);
 
+    // register extra info
+    module.add_info("extra info key", "extra info value");
+
     module
 }

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

@@ -0,0 +1,45 @@
+# Hooks
+
+> PHP is a complex piece of machinery whose lifecycle really should be understood
+> by anyone who wants to understand how PHP operates.
+>
+> Refer: <https://www.phpinternalsbook.com/php7/extensions_design/php_lifecycle.html>
+
+PHP provides many hooks in lifecycle for extension to override.
+
+There are `MINIT`, `MSHUTDOWN`, `RINIT`, `RSHUTDOWN`, `GINIT`, `RSHUTDOWN`.
+
+Correspondingly, `PHPER` sets these hooks to complete some internal operations,
+such as registering extension information, registering functions, classes,
+constants, etc., but also exposes these hooks to users to overwrite.
+
+ The following is the corresponding relationship between PHP hooks and `Module`
+ methods:
+
+| PHP hooks | `Module` method                                          |
+| --------- | -------------------------------------------------------- |
+| MINIT     | [on_module_init](phper::modules::Module::on_module_init) |
+| MSHUTDOWN     | [on_module_shutdown](phper::modules::Module::on_module_shutdown) |
+| RINIT     | [on_request_init](phper::modules::Module::on_request_init) |
+| RSHUTDOWN     | [on_request_shutdown](phper::modules::Module::on_request_shutdown) |
+
+
+```rust,no_run
+use phper::{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"),
+    );
+
+    module.on_module_init(|_| {
+        // Do somethings in `MINIT` stage.
+        true
+    });
+
+    module
+}
+```

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

@@ -0,0 +1,82 @@
+# Register functions
+
+In `PHPER`, you can use [`add_function`](phper::modules::Module::add_function) to 
+register functions.
+
+```rust,no_run
+use phper::{modules::Module, php_get_module, functions::Argument, echo};
+
+#[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"),
+    );
+
+    module.add_function("say_hello", |arguments| -> phper::Result<()> {
+        let name = arguments[0].expect_z_str()?.to_str()?;
+        echo!("Hello, {}!\n", name);
+        Ok(())
+    }).argument(Argument::by_val("name"));
+
+    module
+}
+```
+
+This example registers a function called `say_hello` and accepts a parameter 
+`name` passed by value, just like these codes in PHP:
+
+```php
+<?php
+
+function say_hello($name) {
+    echo "Hello, {$name}\n";
+}
+```
+
+You can get the function info by `php --re <EXTENSION_NAME>`:
+
+```txt
+Extension [ <persistent> extension #56 hello version <no_version> ] {
+
+  - Functions {
+    Function [ <internal:hello> function say_hello ] {
+
+      - Parameters [1] {
+        Parameter #0 [ <required> $name ]
+      }
+    }
+  }
+}
+```
+
+It is useful to register the parameters of the function, which can limit the 
+number of parameters of the function.
+
+Especially, when the parameters need to be passed by reference.
+
+```rust,no_run
+use phper::{modules::Module, php_get_module, functions::Argument};
+
+#[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"),
+    );
+
+    module.add_function("add_count", |arguments| -> phper::Result<()> {
+        let count = arguments[0].expect_mut_z_ref()?;
+        *count.val_mut().expect_mut_long()? += 100;
+        Ok(())
+    }).argument(Argument::by_ref("count"));
+
+    module
+}
+```
+
+Here, the argument is registered as
+[`Argument::by_ref`](phper::functions::Argument::by_ref).  Therefore, the type of
+the `count` parameter is no longer long, but a reference.

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

@@ -0,0 +1,24 @@
+# Register constants
+
+In `PHPER`, you can use [`add_constant`](phper::modules::Module::add_constant) to 
+register constants.
+
+```rust,no_run
+use phper::{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"),
+    );
+
+    module.add_constant("FOO", 100i64);
+
+    module
+}
+```
+
+Because in PHP, you can also use copyable values as constants, such as long,
+double and string, so the value have to implement [`Scalar`](phper::types::Scalar).

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

@@ -0,0 +1,59 @@
+# Register ini settings
+
+In `PHPER`, you can use [`add_ini`](phper::modules::Module::add_ini) to 
+register ini settings.
+
+```rust,no_run
+use phper::{modules::Module, php_get_module, ini::Policy};
+
+#[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"),
+    );
+
+    module.add_ini("demo.enable", false, Policy::All);
+    module.add_ini("demo.foo", 100, Policy::All);
+
+    module
+}
+```
+
+About the policy of setting, you can refer to
+<https://www.php.net/manual/en/configuration.changes.modes.php>.
+
+## Configure ini settings
+
+The user can configure the ini settings in the `php.ini`. if not configure, the
+configuration item will use the default value.
+
+```ini
+demo.enable = On
+```
+
+You can show the ini settings by `php --ri <EXTENSION_NAME>`.
+
+```txt
+demo
+
+version => 0.0.0
+authors => PHPER Framework Team:jmjoy <[email protected]>
+
+Directive => Local Value => Master Value
+demo.enable => 1 => 1
+demo.num => 100 => 100
+```
+
+## Get ini settings
+
+After the ini settings registered, you can get it by
+[`ini_get`](phper::ini::ini_get).
+
+```rust,no_run
+use phper::ini::ini_get;
+
+let _foo = ini_get::<bool>("demo.enable");
+let _bar = ini_get::<i64>("demo.foo");
+```

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

@@ -0,0 +1,53 @@
+# Extension information
+
+By default, `PHPER` will auto register the `MINFO` handle, show the info about
+extension name, version, authors, and display configuration items.
+
+As you execute the command `php --ri <EXTENSION_NAME>`:
+
+```txt
+demo
+
+version => 0.0.0
+authors => PHPER Framework Team:jmjoy <[email protected]>
+
+Directive => Local Value => Master Value
+complex.enable => 0 => 0
+complex.foo => 100 => 100
+```
+
+If you want to add extra info items, you can use 
+[`Module::add_info`](phper::modules::Module::add_info) method.
+
+```rust,no_run
+use phper::{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"),
+    );
+
+    module.add_info("extra info key", "extra info value");
+
+    module
+}
+```
+
+Then build the extension and call `php --ri <EXTENSION_NAME>`:
+
+```txt
+demo
+
+version => 0.0.0
+authors => PHPER Framework Team:jmjoy <[email protected]>
+extra info key => extra info value
+
+Directive => Local Value => Master Value
+complex.enable => 0 => 0
+complex.foo => 100 => 100
+```
+
+The `extra info key` item is appeared.