docs(guide): add guide for IniBuilder

Author: Qard

docsrs_bindings.rs

@@ -204,11 +204,11 @@ pub type __uid_t = ::std::os::raw::c_uint;
 pub type __gid_t = ::std::os::raw::c_uint;
 pub type __ino_t = ::std::os::raw::c_ulong;
 pub type __mode_t = ::std::os::raw::c_uint;
-pub type __nlink_t = ::std::os::raw::c_ulong;
+pub type __nlink_t = ::std::os::raw::c_uint;
 pub type __off_t = ::std::os::raw::c_long;
 pub type __off64_t = ::std::os::raw::c_long;
 pub type __time_t = ::std::os::raw::c_long;
-pub type __blksize_t = ::std::os::raw::c_long;
+pub type __blksize_t = ::std::os::raw::c_int;
 pub type __blkcnt_t = ::std::os::raw::c_long;
 pub type __syscall_slong_t = ::std::os::raw::c_long;
 pub type gid_t = __gid_t;
@@ -768,19 +768,20 @@ pub type zend_class_arrayaccess_funcs = _zend_class_arrayaccess_funcs;
 pub struct stat {
     pub st_dev: __dev_t,
     pub st_ino: __ino_t,
-    pub st_nlink: __nlink_t,
     pub st_mode: __mode_t,
+    pub st_nlink: __nlink_t,
     pub st_uid: __uid_t,
     pub st_gid: __gid_t,
-    pub __pad0: ::std::os::raw::c_int,
     pub st_rdev: __dev_t,
+    pub __pad1: __dev_t,
     pub st_size: __off_t,
     pub st_blksize: __blksize_t,
+    pub __pad2: ::std::os::raw::c_int,
     pub st_blocks: __blkcnt_t,
     pub st_atim: timespec,
     pub st_mtim: timespec,
     pub st_ctim: timespec,
-    pub __glibc_reserved: [__syscall_slong_t; 3usize],
+    pub __glibc_reserved: [::std::os::raw::c_int; 2usize],
 }
 pub type zend_stream_fsizer_t =
     ::std::option::Option<unsafe extern "C" fn(handle: *mut ::std::os::raw::c_void) -> usize>;
@@ -1420,7 +1421,7 @@ pub struct _zend_execute_data {
     pub run_time_cache: *mut *mut ::std::os::raw::c_void,
     pub extra_named_params: *mut zend_array,
 }
-pub type __jmp_buf = [::std::os::raw::c_long; 8usize];
+pub type __jmp_buf = [::std::os::raw::c_ulonglong; 22usize];
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
 pub struct __jmp_buf_tag {
@@ -2732,3 +2733,42 @@ pub struct _sapi_post_entry {
         ),
     >,
 }
+#[doc = " A class which helps with constructing INI entries from the command\n line."]
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct php_ini_builder {
+    pub value: *mut ::std::os::raw::c_char,
+    pub length: usize,
+}
+extern "C" {
+    #[doc = " Prepend a string.\n\n @param src the source string\n @param length the size of the source string"]
+    pub fn php_ini_builder_prepend(
+        b: *mut php_ini_builder,
+        src: *const ::std::os::raw::c_char,
+        length: usize,
+    );
+}
+extern "C" {
+    #[doc = " Append an unquoted name/value pair."]
+    pub fn php_ini_builder_unquoted(
+        b: *mut php_ini_builder,
+        name: *const ::std::os::raw::c_char,
+        name_length: usize,
+        value: *const ::std::os::raw::c_char,
+        value_length: usize,
+    );
+}
+extern "C" {
+    #[doc = " Append a quoted name/value pair."]
+    pub fn php_ini_builder_quoted(
+        b: *mut php_ini_builder,
+        name: *const ::std::os::raw::c_char,
+        name_length: usize,
+        value: *const ::std::os::raw::c_char,
+        value_length: usize,
+    );
+}
+extern "C" {
+    #[doc = " Parse an INI entry from the command-line option \"--define\"."]
+    pub fn php_ini_builder_define(b: *mut php_ini_builder, arg: *const ::std::os::raw::c_char);
+}

guide/src/ini-builder.md

@@ -0,0 +1,40 @@
+# INI Builder
+
+When configuring a SAPI you may use `IniBuilder` to load INI settings as text.
+This is useful for setting up configurations required by the SAPI capabilities.
+
+INI settings applied to a SAPI through `sapi.ini_entries` will be immutable,
+meaning they cannot be changed at runtime. This is useful for applying settings
+to match hard requirements of the way your SAPI works.
+
+To apply _configurable_ defaults it is recommended to use a `sapi.ini_defaults`
+callback instead, which will allow settings to be changed at runtime.
+
+```rust,no_run
+use ext_php_rs::builder::{IniBuilder, SapiBuilder};
+
+# fn main() {
+// Create a new IniBuilder instance.
+let mut builder = IniBuilder::new();
+
+// Append a single key/value pair to the INIT buffer with an unquoted value.
+builder.unquoted("log_errors", "1");
+
+// Append a single key/value pair to the INI buffer with a quoted value.
+builder.quoted("default_mimetype", "text/html");
+
+// Append INI line text as-is. A line break will be automatically appended.
+builder.define("memory_limit=128MB");
+
+// Prepend INI line text as-is. No line break insertion will occur.
+builder.prepend("error_reporting=0\ndisplay_errors=1\n");
+
+// Construct a SAPI.
+let mut sapi = SapiBuilder::new("name", "pretty_name").build()
+  .expect("should build SAPI");
+
+// Dump INI entries from the builder into the SAPI.
+sapi.ini_entries = builder.finish();
+# }
+# main();
+```

src/builders/ini.rs

@@ -1,12 +1,9 @@
-use std::ops::Deref;
-use std::ffi::{c_char, CStr, CString, NulError};
 use crate::ffi::{
-    php_ini_builder,
-    php_ini_builder_prepend,
+    php_ini_builder, php_ini_builder_define, php_ini_builder_prepend, php_ini_builder_quoted,
     php_ini_builder_unquoted,
-    php_ini_builder_quoted,
-    php_ini_builder_define
 };
+use std::ffi::{c_char, CStr, CString, NulError};
+use std::ops::Deref;
 
 // Helpful for CString which only needs to live until immediately after C call.
 struct CStringScope(*mut c_char);
@@ -28,13 +25,19 @@ impl Deref for CStringScope {
 impl Drop for CStringScope {
     fn drop(&mut self) {
         // Convert back to a CString to ensure it gets dropped
-        drop(unsafe { CString::from_raw(self.0) })
+        drop(unsafe { CString::from_raw(self.0) });
     }
 }
 
 /// A builder for creating INI configurations.
 pub type IniBuilder = php_ini_builder;
 
+impl Default for IniBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl IniBuilder {
     /// Creates a new INI builder.
     ///
@@ -44,8 +47,9 @@ impl IniBuilder {
     /// # use ext_php_rs::builders::IniBuilder;
     /// let mut builder = IniBuilder::new();
     /// ```
+    #[must_use]
     pub fn new() -> IniBuilder {
-         IniBuilder {
+        IniBuilder {
             value: std::ptr::null_mut(),
             length: 0,
         }
@@ -57,6 +61,10 @@ impl IniBuilder {
     ///
     /// * `value` - The value to append.
     ///
+    /// # Errors
+    ///
+    /// Returns a `NulError` if the value contains a null byte.
+    ///
     /// # Examples
     ///
     /// ```
@@ -82,6 +90,10 @@ impl IniBuilder {
     /// * `name` - The name of the pair.
     /// * `value` - The value of the pair.
     ///
+    /// # Errors
+    ///
+    /// Returns a `NulError` if the value contains a null byte.
+    ///
     /// # Examples
     ///
     /// ```
@@ -114,6 +126,10 @@ impl IniBuilder {
     /// * `name` - The name of the pair.
     /// * `value` - The value of the pair.
     ///
+    /// # Errors
+    ///
+    /// Returns a `NulError` if the value contains a null byte.
+    ///
     /// # Examples
     ///
     /// ```
@@ -145,6 +161,10 @@ impl IniBuilder {
     ///
     /// * `value` - The value to define.
     ///
+    /// # Errors
+    ///
+    /// Returns a `NulError` if the value contains a null byte.
+    ///
     /// # Examples
     ///
     /// ```
@@ -177,7 +197,7 @@ impl IniBuilder {
             return std::ptr::null_mut();
         }
 
-        unsafe { CStr::from_ptr(self.value) }.as_ptr() as *mut c_char
+        unsafe { CStr::from_ptr(self.value) }.as_ptr().cast_mut()
     }
 }
 
@@ -188,40 +208,66 @@ mod tests {
     #[test]
     fn test_ini_builder_prepend() {
         let mut builder = IniBuilder::new();
-        builder.prepend("foo=bar").unwrap();
+        builder.prepend("foo=bar").expect("should prepend value");
 
         let ini = builder.finish();
         assert!(!ini.is_null());
-        assert_eq!(unsafe { CStr::from_ptr(ini) }.to_str().unwrap(), "foo=bar");
+        assert_eq!(
+            unsafe { CStr::from_ptr(ini) }
+                .to_str()
+                .expect("should convert to str"),
+            "foo=bar"
+        );
     }
 
     #[test]
     fn test_ini_builder_unquoted() {
         let mut builder = IniBuilder::new();
-        builder.unquoted("baz", "qux").unwrap();
+        builder
+            .unquoted("baz", "qux")
+            .expect("should add unquoted value");
 
         let ini = builder.finish();
         assert!(!ini.is_null());
-        assert_eq!(unsafe { CStr::from_ptr(ini) }.to_str().unwrap(), "baz=qux\n");
+        assert_eq!(
+            unsafe { CStr::from_ptr(ini) }
+                .to_str()
+                .expect("should convert to str"),
+            "baz=qux\n"
+        );
     }
 
     #[test]
     fn test_ini_builder_quoted() {
         let mut builder = IniBuilder::new();
-        builder.quoted("quux", "corge").unwrap();
+        builder
+            .quoted("quux", "corge")
+            .expect("should add quoted value");
 
         let ini = builder.finish();
         assert!(!ini.is_null());
-        assert_eq!(unsafe { CStr::from_ptr(ini) }.to_str().unwrap(), "quux=\"corge\"\n");
+        assert_eq!(
+            unsafe { CStr::from_ptr(ini) }
+                .to_str()
+                .expect("should convert to str"),
+            "quux=\"corge\"\n"
+        );
     }
 
     #[test]
     fn test_ini_builder_define() {
         let mut builder = IniBuilder::new();
-        builder.define("grault=garply").unwrap();
+        builder
+            .define("grault=garply")
+            .expect("should define value");
 
         let ini = builder.finish();
         assert!(!ini.is_null());
-        assert_eq!(unsafe { CStr::from_ptr(ini) }.to_str().unwrap(), "grault=garply\n");
+        assert_eq!(
+            unsafe { CStr::from_ptr(ini) }
+                .to_str()
+                .expect("should convert to str"),
+            "grault=garply\n"
+        );
     }
 }