Added ext-php-rs guide (#52)

* Started work on guide, added types

* Rewrite argument parser to allow referencs

Primarly so that `&str` is a valid parameter type.

* Remove generic `Into<String>` conversion to exception

* Worked on guide, added macros

* Build guide when building docs

* Allow manual trigger of docs build

* `cargo fmt`

Author: davidcole1340

.github/workflows/docs.yml

@@ -1,5 +1,6 @@
 name: Deploy documentation
 on:
+  workflow_dispatch:
   push:
     branches:
       - master
@@ -32,13 +33,22 @@ jobs:
         with:
           version: ${{ matrix.llvm }}
           directory: ${{ runner.temp }}/llvm-${{ matrix.llvm }}
+      - name: Install mdbook
+        uses: actions-rs/install@v0.1
+        with:
+          crate: mdbook
+          version: latest
       - name: Build docs
         uses: actions-rs/cargo@v1
         env:
           LIBCLANG_PATH: ${{ runner.temp }}/llvm-${{ matrix.llvm }}/lib
         with:
           command: doc
           args: --release
+      - name: Build guide
+        run: |
+          mdbook build guide
+          mv guide/book target/doc/guide
       - name: Create index redirect
         run: |
           echo '<meta http-equiv=refresh content=0;url=/ext-php-rs/ext_php_rs>' > target/doc/index.html

README.md

@@ -2,7 +2,8 @@
 
 [<img align="right" src="https://discord.com/api/guilds/115233111977099271/widget.png?style=banner2">](https://discord.gg/dphp)
 
-Bindings and abstractions for the Zend API to build PHP extensions natively in Rust.
+Bindings and abstractions for the Zend API to build PHP extensions natively in
+Rust.
 
 ## Example
 
@@ -31,30 +32,43 @@ var_dump(hello_world("David")); // string(13) "Hello, David!"
 
 ## Features
 
-- **Easy to use:** The built-in macros can abstract away the need to interact with the Zend API, such as Rust-type function parameter abstracting away interacting with Zend values.
-- **Lightweight:** You don't have to use the built-in helper macros. It's possible to write your own glue code around your own functions.
-- **Extensible:** Implement `IntoZval` and `FromZval` for your own custom types, allowing the type to be used as function parameters and return types.
+- **Easy to use:** The built-in macros can abstract away the need to interact
+  with the Zend API, such as Rust-type function parameter abstracting away
+  interacting with Zend values.
+- **Lightweight:** You don't have to use the built-in helper macros. It's
+  possible to write your own glue code around your own functions.
+- **Extensible:** Implement `IntoZval` and `FromZval` for your own custom types,
+  allowing the type to be used as function parameters and return types.
 
 ## Goals
 
 Our main goal is to **make extension development easier.**
 
-- Writing extensions in C can be tedious, and with the Zend APIs limited documentation can be intimidating.
-- Rust's modern language features and feature-full standard library are big improvements on C.
-- Abstracting away the raw Zend APIs allows extensions to be developed faster and with more confidence.
-- Abstractions also allow us to support future (and potentially past) versions of PHP without significant changes to extension code.
+- Writing extensions in C can be tedious, and with the Zend APIs limited
+  documentation can be intimidating.
+- Rust's modern language features and feature-full standard library are big
+  improvements on C.
+- Abstracting away the raw Zend APIs allows extensions to be developed faster
+  and with more confidence.
+- Abstractions also allow us to support future (and potentially past) versions
+  of PHP without significant changes to extension code.
 
 ## Documentation
 
-The project is documented in-line, so viewing the `cargo` documentation is the best resource at the moment.
+The project is documented in-line, so viewing the `cargo` documentation is the
+best resource at the moment.
 
-We are currently unable to deploy our documentation to `docs.rs` due to the crate requiring PHP 8.0, which is unavailable in the default Ubuntu repositories.
-Documentation can be viewed [here](https://davidcole1340.github.io/ext-php-rs/). It is generated from the latest `master` branch. Documentation will be moved to `docs.rs` when Ubuntu updates its repositories to PHP 8.0.
+We are currently unable to deploy our documentation to `docs.rs` due to the
+crate requiring PHP 8.0, which is unavailable in the default Ubuntu
+repositories. Documentation can be viewed
+[here](https://davidcole1340.github.io/ext-php-rs/). It is generated from the
+latest `master` branch. Documentation will be moved to `docs.rs` when Ubuntu
+updates its repositories to PHP 8.0.
 
 ## Requirements
 
 - PHP 8.0 or later
-     - No support is planned for lower versions.
+  - No support is planned for lower versions.
 - Linux or Darwin-based OS
 - Rust - no idea which version
 - Clang 3.9 or greater
@@ -64,20 +78,26 @@ See the following links for the dependency crate requirements:
 - [`cc`](https://github.com/alexcrichton/cc-rs#compile-time-requirements)
 - [`bindgen`](https://rust-lang.github.io/rust-bindgen/requirements.html)
 
-
 ## Usage
 
-This project only works for PHP >= 8.0 (for now). Due to the fact that the PHP extension system relies heavily on C macros (which cannot be exported to Rust easily), structs have to be hard coded in.
+This project only works for PHP >= 8.0 (for now). Due to the fact that the PHP
+extension system relies heavily on C macros (which cannot be exported to Rust
+easily), structs have to be hard coded in.
 
 Check out one of the example projects:
 
-- [ext-skel](example/skel) - Testbed for testing the library. Check out previous commits as well to see what else is possible.
-- [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia) - Sequoia encryption PHP extension.
-- [opus-php](https://github.com/davidcole1340/opus-php/tree/rewrite_rs) - Work-in-progress extension to use the Opus library in PHP.
+- [ext-skel](example/skel) - Testbed for testing the library. Check out previous
+  commits as well to see what else is possible.
+- [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia) - Sequoia
+  encryption PHP extension.
+- [opus-php](https://github.com/davidcole1340/opus-php/tree/rewrite_rs) -
+  Work-in-progress extension to use the Opus library in PHP.
 
 ## Contributions
 
-Contributions are very much welcome. I am a novice Rust developer and any suggestions are wanted and welcome. Feel free to file issues and PRs through Github.
+Contributions are very much welcome. I am a novice Rust developer and any
+suggestions are wanted and welcome. Feel free to file issues and PRs through
+Github.
 
 Contributions welcome include:
 
@@ -98,9 +118,8 @@ dual licensed as above, without any additional terms or conditions.
 
 Licensed under either of
 
- * Apache License, Version 2.0
-   ([LICENSE_APACHE](LICENSE_APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license
-   ([LICENSE_MIT](LICENSE_MIT) or http://opensource.org/licenses/MIT)
+- Apache License, Version 2.0 ([LICENSE_APACHE](LICENSE_APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE_MIT](LICENSE_MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

example/skel/src/lib.rs

@@ -1,6 +1,6 @@
 mod allocator;
 
-use std::collections::HashMap;
+use std::{collections::HashMap, convert::TryFrom};
 
 use allocator::PhpAllocator;
 use ext_php_rs::{
@@ -127,11 +127,23 @@ pub fn skeleton_array(
     Ok(new)
 }
 
-#[php_function]
-pub fn test_array() -> Vec<i32> {
+#[php_function(optional = "i", defaults(i = 5))]
+pub fn test_array(i: i32, b: Option<i32>) -> Vec<i32> {
+    dbg!(i, b);
     vec![1, 2, 3, 4]
 }
 
+#[php_function(optional = "offset", defaults(offset = 0))]
+pub fn rust_strpos(haystack: &str, needle: &str, offset: i64) -> Option<usize> {
+    let haystack = haystack.chars().skip(offset as usize).collect::<String>();
+    haystack.find(needle)
+}
+
+#[php_function]
+pub fn example_exception() -> Result<i32, &'static str> {
+    Err("Bad here")
+}
+
 #[php_function]
 pub fn skel_unpack<'a>(
     mut arr: HashMap<String, String>,
@@ -149,6 +161,16 @@ pub fn test_extern() -> i32 {
     0
 }
 
+#[php_function]
+pub fn test_lifetimes<'a>() -> ZendHashTable<'a> {
+    ZendHashTable::try_from(&HashMap::<String, String>::new()).unwrap()
+}
+
+#[php_function]
+pub fn test_str(input: &str) -> &str {
+    input
+}
+
 #[no_mangle]
 pub extern "C" fn php_module_info(_module: *mut ModuleEntry) {
     info_table_start!();

ext-php-rs-derive/Cargo.toml

@@ -17,3 +17,5 @@ darling = "0.12"
 quote = "1.0.9"
 proc-macro2 = "1.0.26"
 lazy_static = "1.4.0"
+regex = "1.5"
+anyhow = "1.0"

ext-php-rs-derive/src/class.rs

@@ -1,4 +1,5 @@
-use crate::{error::Result, STATE};
+use crate::STATE;
+use anyhow::{bail, Result};
 use proc_macro2::{Ident, Span, TokenStream};
 use quote::quote;
 use syn::DeriveInput;
@@ -47,18 +48,17 @@ pub fn parser(input: DeriveInput) -> Result<TokenStream> {
         }
     };
 
-    let mut state = STATE.lock()?;
+    let mut state = STATE.lock();
 
     if state.built_module {
-        return Err("The `#[php_module]` macro must be called last to ensure functions and classes are registered.".into());
+        bail!("The `#[php_module]` macro must be called last to ensure functions and classes are registered.");
     }
 
     if state.classes.contains_key(&class_name) {
-        return Err(format!(
+        bail!(
             "A class has already been registered with the name `{}`.",
             class_name
-        )
-        .into());
+        );
     }
 
     state.classes.insert(class_name, Default::default());

ext-php-rs-derive/src/constant.rs

@@ -1,9 +1,10 @@
+use anyhow::{bail, Result};
 use darling::ToTokens;
 use proc_macro2::{Ident, Literal, TokenStream};
 use quote::quote;
 use syn::ItemConst;
 
-use crate::{error::Result, STATE};
+use crate::STATE;
 
 #[derive(Debug)]
 pub struct Constant {
@@ -13,10 +14,10 @@ pub struct Constant {
 }
 
 pub fn parser(input: ItemConst) -> Result<TokenStream> {
-    let mut state = STATE.lock()?;
+    let mut state = STATE.lock();
 
     if state.startup_function.is_some() {
-        return Err("Constants must be declared before you declare your startup function and module function.".into());
+        bail!("Constants must be declared before you declare your startup function and module function.");
     }
 
     state.constants.push(Constant {

ext-php-rs-derive/src/error.rs

@@ -1,16 +1,15 @@
+use anyhow::{anyhow, bail, Result};
 use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{punctuated::Punctuated, ForeignItemFn, ItemForeignMod, ReturnType, Signature, Token};
 
-use crate::error::Result;
-
 pub fn parser(input: ItemForeignMod) -> Result<TokenStream> {
     input
         .items
         .into_iter()
         .map(|item| match item {
             syn::ForeignItem::Fn(func) => parse_function(func),
-            _ => Err("Only `extern` functions are supported by PHP.".into()),
+            _ => bail!("Only `extern` functions are supported by PHP."),
         })
         .collect::<Result<Vec<_>>>()
         .map(|vec| quote! { #(#vec)* })
@@ -36,7 +35,9 @@ fn parse_function(mut func: ForeignItemFn) -> Result<TokenStream> {
             _ => None,
         })
         .collect::<Option<Punctuated<_, Token![,]>>>()
-        .ok_or("`self` parameters are not permitted inside `#[php_extern]` blocks.")?;
+        .ok_or_else(|| {
+            anyhow!("`self` parameters are not permitted inside `#[php_extern]` blocks.")
+        })?;
     let ret = build_return(&name, &sig.output, params);
 
     Ok(quote! {