docs(macro): update documentation with new #[php] attr

Refs: #391

Author: Xenira

crates/macros/src/class.rs

@@ -14,6 +14,9 @@ pub struct StructAttributes {
     /// The name of the PHP class. Defaults to the same name as the struct.
     #[darling(flatten)]
     rename: PhpRename,
+    /// A modifier function which should accept one argument, a `ClassBuilder`,
+    /// and return the same object. Allows the user to modify the class before
+    /// it is built.
     modifier: Option<syn::Ident>,
     /// An expression of `ClassFlags` to be applied to the class.
     flags: Option<syn::Expr>,

crates/macros/src/constant.rs

@@ -4,7 +4,7 @@ use quote::{format_ident, quote};
 use syn::ItemConst;
 
 use crate::helpers::get_docs;
-use crate::parsing::{PhpRename, Visibility};
+use crate::parsing::PhpRename;
 use crate::prelude::*;
 
 const INTERNAL_CONST_DOC_PREFIX: &str = "_internal_const_docs_";
@@ -15,7 +15,8 @@ const INTERNAL_CONST_NAME_PREFIX: &str = "_internal_const_name_";
 pub(crate) struct PhpConstAttribute {
     #[darling(flatten)]
     pub(crate) rename: PhpRename,
-    pub(crate) vis: Option<Visibility>,
+    // TODO: Implement const Visibility
+    // pub(crate) vis: Option<Visibility>,
     pub(crate) attrs: Vec<syn::Attribute>,
 }
 

crates/macros/src/lib.rs

@@ -32,6 +32,7 @@
   - [Constants](./macros/constant.md)
   - [PHP Functions](./macros/extern.md)
   - [`ZvalConvert`](./macros/zval_convert.md)
+  - [`Attributes`](./macros/php.md)
 - [Exceptions](./exceptions.md)
 - [INI Settings](./ini-settings.md)
 

guide/src/SUMMARY.md

@@ -6,6 +6,13 @@ that implements `IntoConst`.
 The `wrap_constant!()` macro can be used to simplify the registration of constants.
 It sets the name and doc comments for the constant.
 
+You can rename the const with options:
+
+- `name` - Allows you to rename the property, e.g.
+  `#[php(name = "new_name")]`
+- `rename` - Allows you to rename the property using rename rules, e.g.
+  `#[php(rename = PascalCase)]`
+
 ## Examples
 
 ```rust,no_run
@@ -16,13 +23,18 @@ use ext_php_rs::prelude::*;
 #[php_const]
 const TEST_CONSTANT: i32 = 100;
 
+#[php_const]
+#[php(name = "I_AM_RENAMED")]
+const TEST_CONSTANT_THE_SECOND: i32 = 42;
+
 #[php_const]
 const ANOTHER_STRING_CONST: &'static str = "Hello world!";
 
 #[php_module]
 pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
     module
         .constant(wrap_constant!(TEST_CONSTANT))
+        .constant(wrap_constant!(TEST_CONSTANT_THE_SECOND))
         .constant(("MANUAL_CONSTANT", ANOTHER_STRING_CONST, &[]))
 }
 # fn main() {}
@@ -34,5 +46,6 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 <?php
 
 var_dump(TEST_CONSTANT); // int(100)
+var_dump(I_AM_RENAMED); // int(42)
 var_dump(MANUAL_CONSTANT); // string(12) "Hello world!"
 ```

guide/src/macros/constant.md

@@ -37,15 +37,16 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 ```
 
 Default parameter values can also be set for optional parameters. This is done
-through the `defaults` attribute option. When an optional parameter has a
+through the `#[php(defaults)]` attribute option. When an optional parameter has a
 default, it does not need to be a variant of `Option`:
 
 ```rust,no_run
 # #![cfg_attr(windows, feature(abi_vectorcall))]
 # extern crate ext_php_rs;
 use ext_php_rs::prelude::*;
 
-#[php_function(defaults(offset = 0))]
+#[php_function]
+#[php(defaults(offset = 0))]
 pub fn rusty_strpos(haystack: &str, needle: &str, offset: i64) -> Option<usize> {
     let haystack: String = haystack.chars().skip(offset as usize).collect();
     haystack.find(needle)
@@ -98,7 +99,8 @@ use ext_php_rs::prelude::*;
 
 /// `age` will be deemed required and nullable rather than optional,
 /// while description will be optional.
-#[php_function(optional = "description")]
+#[php_function]
+#[php(optional = "description")]
 pub fn greet(name: String, age: Option<i32>, description: Option<String>) -> String {
     let mut greeting = format!("Hello, {}!", name);
 

guide/src/macros/function.md

@@ -14,10 +14,13 @@ used from PHP without fiddling around with zvals.
 - [`php_const`] - Used to export a Rust constant to PHP as a global constant.
 - [`php_extern`] - Attribute used to annotate `extern` blocks which are deemed as
   PHP functions.
+- [`php`] - Used to modify the default behavior of the above macros. This is a
+    generic attribute that can be used on most of the above macros.
 
 [`php_module`]: ./module.md
 [`php_function`]: ./function.md
 [`php_class`]: ./classes.md
 [`php_impl`]: ./impl.md
 [`php_const`]: ./constant.md
 [`php_extern`]: ./extern.md
+[`php`]: ./php.md

guide/src/macros/index.md

@@ -0,0 +1,53 @@
+# `#[php]` Attributes
+
+There are a number of attributes that can be used to annotate elements in your
+extension.
+
+Multiple `#[php]` attributes will be combined. For example, the following will
+be identical:
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+#[php_function]
+#[php(name = "hi_world")]
+#[php(defaults(a = 1, b = 2))]
+fn hello_world(a: i32, b: i32) -> i32 {
+    a + b
+}
+# fn main() {}
+```
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+#[php_function]
+#[php(name = "hi_world", defaults(a = 1, b = 2))]
+fn hello_world(a: i32, b: i32) -> i32 {
+    a + b
+}
+# fn main() {}
+```
+
+Which attributes are available depends on the element you are annotating:
+
+| Attribute        | `const` | `fn` | `struct` | `struct` Field | `impl` | `impl` `const` | `impl` `fn` |
+| ---------------- | ------- | ---- | -------- | -------------- | ------ | -------------- | ----------- |
+| name             | ✅      | ✅   | ✅       | ✅             | ❌     | ✅             | ✅          |
+| rename           | ✅      | ✅   | ✅       | ✅             | ❌     | ✅             | ✅          |
+| rename_methods   | ❌      | ❌   | ❌       | ❌             | ✅     | ❌             | ❌          |
+| rename_constants | ❌      | ❌   | ❌       | ❌             | ✅     | ❌             | ❌          |
+| flags            | ❌      | ❌   | ✅       | ✅             | ❌     | ❌             | ❌          |
+| prop             | ❌      | ❌   | ❌       | ✅             | ❌     | ❌             | ❌          |
+| extends          | ❌      | ❌   | ✅       | ❌             | ❌     | ❌             | ❌          |
+| implements       | ❌      | ❌   | ✅       | ❌             | ❌     | ❌             | ❌          |
+| modifier         | ❌      | ❌   | ✅       | ❌             | ❌     | ❌             | ❌          |
+| defaults         | ❌      | ✅   | ❌       | ❌             | ❌     | ❌             | ✅          |
+| optional         | ❌      | ✅   | ❌       | ❌             | ❌     | ❌             | ✅          |
+| vis              | ❌      | ✅   | ❌       | ❌             | ❌     | ❌             | ✅          |
+| getter           | ❌      | ❌   | ❌       | ❌             | ❌     | ❌             | ✅          |
+| setter           | ❌      | ❌   | ❌       | ❌             | ❌     | ❌             | ✅          |
+| constructor      | ❌      | ❌   | ❌       | ❌             | ❌     | ❌             | ✅          |
+| abstract_method  | ❌      | ❌   | ❌       | ❌             | ❌     | ❌             | ✅          |

guide/src/macros/php.md

@@ -15,7 +15,8 @@ register functions, classes, constants and startup function when declaring
 the module.
 
 ```rs
-#[php_module(startup = "startup_function")]
+#[php_module]
+#[php(startup = "startup_function")]
 pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
     module
         .class::<TestClass>()
@@ -44,6 +45,13 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 }
 ```
 
+**Supported `#[php]` attributes:**
+- `#[php(name = "NEW_NAME")]` - Renames the function
+- `#[php(rename = case)]` - Changes the case of the function name
+- `#[php(vis = "public")]` - Changes the visibility of the function
+- `#[php(defaults(a = 5, test = 100))]` - Sets default values for function arguments
+- `#[php(variadic)]` - Marks the function as variadic. The last argument must be a `&[&Zval]`
+
 ### Classes
 
 Mostly unchanged in terms of the class and impl definitions, however you now
@@ -55,24 +63,23 @@ use ext_php_rs::prelude::*;
 #[php_class]
 #[derive(Debug)]
 pub struct TestClass {
-    #[prop]
+    #[php(prop)]
     a: i32,
-    #[prop]
+    #[php(prop)]
     b: i32,
 }
 
 #[php_impl]
 impl TestClass {
-    #[rename("NEW_CONSTANT_NAME")]
+    #[php(name = "NEW_CONSTANT_NAME")]
     pub const SOME_CONSTANT: i32 = 5;
     pub const SOME_OTHER_STR: &'static str = "Hello, world!";
 
     pub fn __construct(a: i32, b: i32) -> Self {
         Self { a: a + 10, b: b + 10 }
     }
 
-    #[optional(test)]
-    #[defaults(a = 5, test = 100)]
+    #[php(defaults(a = 5, test = 100))]
     pub fn test_camel_case(&self, a: i32, test: i32) {
         println!("a: {} test: {}", a, test);
     }
@@ -95,6 +102,20 @@ pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
 }
 ```
 
+**Supported `#[php]` attributes (`struct`):**
+- `#[php(name = "NEW_NAME")]` - Renames the class
+- `#[php(rename = case)]` - Changes the case of the class name
+- `#[php(vis = "public")]` - Changes the visibility of the class
+- `#[php(extends = "ParentClass")]` - Extends a parent class
+- `#[php(implements = "Interface")]` - Implements an interface
+- `#[php(prop)]` - Marks a field as a property
+
+**Supported `#[php]` attributes (`impl`):**
+- `#[php(rename_consts = case)]` - Changes the case of the constant names. Can be overridden by attributes on the constants.
+- `#[php(rename_methods = case)]` - Changes the case of the method names. Can be overridden by attributes on the methods.
+
+For elements in the `#[php_impl]` block see the respective function and constant attributes.
+
 ### Constants
 
 Mostly unchanged in terms of constant definition, however you now need to
@@ -106,14 +127,24 @@ use ext_php_rs::prelude::*;
 #[php_const]
 const SOME_CONSTANT: i32 = 100;
 
+#[php_const]
+#[php(name = "HELLO_WORLD")]
+const SOME_OTHER_CONSTANT: &'static str = "Hello, world!";
+
 #[php_module]
 pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
     module
         .constant(wrap_constant!(SOME_CONSTANT)) // SOME_CONSTANT = 100
+        .constant(wrap_constant!(SOME_OTHER_CONSTANT)) // HELLO_WORLD = "Hello, world!"
         .constant(("CONST_NAME", SOME_CONSTANT, &[])) // CONST_NAME = 100
 }
 ```
 
+**Supported `#[php]` attributes:**
+- `#[php(name = "NEW_NAME")]` - Renames the constant
+- `#[php(rename = case)]` - Changes the case of the constant name
+- `#[php(vis = "public")]` - Changes the visibility of the constant
+
 ### Extern
 
 No changes.
@@ -144,8 +175,24 @@ fn startup_function(ty: i32, mod_num: i32) -> i32 {
     0
 }
 
-#[php_module(startup = "startup_function")]
+#[php_module]
+#[php(startup = "startup_function")]
 pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
     module
 }
 ```
+
+### `#[php]` Attributes
+
+Attributes like `#[rename]` or `#[prop]` have been moved to the `#[php]` attribute.
+
+The `#[php]` attribute on an item are combined with each other. This means that
+the following variants are equivalent:
+```rs
+#[php(rename = case)]
+#[php(vis = "public")]
+```
+
+```rs
+#[php(rename = case, vis = "public")]
+```