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,37 @@
+# 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};
+
+// 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();
+```

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);
@@ -45,7 +42,7 @@ impl IniBuilder {
     /// let mut builder = IniBuilder::new();
     /// ```
     pub fn new() -> IniBuilder {
-         IniBuilder {
+        IniBuilder {
             value: std::ptr::null_mut(),
             length: 0,
         }
@@ -177,7 +174,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() as *mut i8
     }
 }
 
@@ -188,40 +185,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"
+        );
     }
 }