ext_php_rs/
binary.rs

1//! Provides implementations for converting to and from Zend binary strings,
2//! commonly returned from functions such as [`pack`] and [`unpack`].
3//!
4//! [`pack`]: https://www.php.net/manual/en/function.pack.php
5//! [`unpack`]: https://www.php.net/manual/en/function.unpack.php
6
7use crate::ffi::{ext_php_rs_zend_string_init, zend_string};
8
9use std::{
10    convert::TryFrom,
11    iter::FromIterator,
12    ops::{Deref, DerefMut},
13};
14
15use crate::{
16    convert::{FromZval, IntoZval},
17    error::{Error, Result},
18    flags::DataType,
19    types::Zval,
20};
21
22/// Acts as a wrapper around [`Vec<T>`] where `T` implements [`Pack`]. Primarily
23/// used for passing binary data into Rust functions. Can be treated as a
24/// [`Vec`] in most situations, or can be 'unwrapped' into a [`Vec`] through the
25/// [`From`] implementation on [`Vec`].
26#[derive(Debug)]
27pub struct Binary<T: Pack>(Vec<T>);
28
29impl<T: Pack> Binary<T> {
30    /// Creates a new binary wrapper from a set of data which can be converted
31    /// into a vector.
32    ///
33    /// # Parameters
34    ///
35    /// * `data` - Data to store inside the binary wrapper.
36    pub fn new(data: impl Into<Vec<T>>) -> Self {
37        Self(data.into())
38    }
39}
40
41impl<T: Pack> Deref for Binary<T> {
42    type Target = Vec<T>;
43
44    fn deref(&self) -> &Self::Target {
45        &self.0
46    }
47}
48
49impl<T: Pack> DerefMut for Binary<T> {
50    fn deref_mut(&mut self) -> &mut Self::Target {
51        &mut self.0
52    }
53}
54
55impl<T: Pack> FromZval<'_> for Binary<T> {
56    const TYPE: DataType = DataType::String;
57
58    fn from_zval(zval: &Zval) -> Option<Self> {
59        zval.binary().map(Binary)
60    }
61}
62
63impl<T: Pack> TryFrom<Zval> for Binary<T> {
64    type Error = Error;
65
66    fn try_from(value: Zval) -> Result<Self> {
67        Self::from_zval(&value).ok_or_else(|| Error::ZvalConversion(value.get_type()))
68    }
69}
70
71impl<T: Pack> IntoZval for Binary<T> {
72    const TYPE: DataType = DataType::String;
73    const NULLABLE: bool = false;
74
75    fn set_zval(self, zv: &mut Zval, _: bool) -> Result<()> {
76        zv.set_binary(self.0);
77        Ok(())
78    }
79}
80
81impl<T: Pack> From<Binary<T>> for Vec<T> {
82    fn from(value: Binary<T>) -> Self {
83        value.0
84    }
85}
86
87impl<T: Pack> From<Vec<T>> for Binary<T> {
88    fn from(value: Vec<T>) -> Self {
89        Self::new(value)
90    }
91}
92
93impl<T: Pack> FromIterator<T> for Binary<T> {
94    fn from_iter<U: IntoIterator<Item = T>>(iter: U) -> Self {
95        Self(iter.into_iter().collect::<Vec<_>>())
96    }
97}
98
99/// Used to convert between Zend binary strings and vectors. Useful in
100/// conjunction with the [`pack`] and [`unpack`] functions built-in to PHP.
101///
102/// # Safety
103///
104/// The types cannot be ensured between PHP and Rust, as the data is represented
105/// as a string when crossing the language boundary. Exercise caution when using
106/// these functions.
107///
108/// [`pack`]: https://www.php.net/manual/en/function.pack.php
109/// [`unpack`]: https://www.php.net/manual/en/function.unpack.php
110pub unsafe trait Pack: Clone {
111    /// Packs a given vector into a Zend binary string. Can be passed to PHP and
112    /// then unpacked using the [`unpack`] function.
113    ///
114    /// # Parameters
115    ///
116    /// * `vec` - The vector to pack into a binary string.
117    ///
118    /// [`unpack`]: https://www.php.net/manual/en/function.unpack.php
119    fn pack_into(vec: Vec<Self>) -> *mut zend_string;
120
121    /// Unpacks a given Zend binary string into a Rust vector. Can be used to
122    /// pass data from `pack` in PHP to Rust without encoding into another
123    /// format. Note that the data *must* be all one type, as this
124    /// implementation only unpacks one type.
125    ///
126    /// # Safety
127    ///
128    /// There is no way to tell if the data stored in the string is actually of
129    /// the given type. The results of this function can also differ from
130    /// platform-to-platform due to the different representation of some
131    /// types on different platforms. Consult the [`pack`] function
132    /// documentation for more details.
133    ///
134    /// # Parameters
135    ///
136    /// * `s` - The Zend string containing the binary data.
137    ///
138    /// [`pack`]: https://www.php.net/manual/en/function.pack.php
139    fn unpack_into(s: &zend_string) -> Vec<Self>;
140}
141
142/// Implements the [`Pack`] trait for a given type.
143macro_rules! pack_impl {
144    ($t: ty) => {
145        pack_impl!($t, <$t>::BITS);
146    };
147
148    ($t: ty, $d: expr) => {
149        unsafe impl Pack for $t {
150            fn pack_into(vec: Vec<Self>) -> *mut zend_string {
151                let len = vec.len() * ($d as usize / 8);
152                let ptr = Box::into_raw(vec.into_boxed_slice());
153                unsafe { ext_php_rs_zend_string_init(ptr.cast(), len as _, false) }
154            }
155
156            fn unpack_into(s: &zend_string) -> Vec<Self> {
157                #[allow(clippy::cast_lossless)]
158                let bytes = ($d / 8) as u64;
159                let len = (s.len as u64) / bytes;
160                let mut result =
161                    Vec::with_capacity(len.try_into().expect("Capacity integer overflow"));
162                // TODO: Check alignment
163                #[allow(clippy::cast_ptr_alignment)]
164                let ptr = s.val.as_ptr().cast::<$t>();
165
166                // SAFETY: We calculate the length of memory that we can legally read based on
167                // the side of the type, therefore we never read outside the memory we
168                // should.
169                for i in 0..len {
170                    result.push(unsafe {
171                        *ptr.offset(i.try_into().expect("Offset integer overflow"))
172                    });
173                }
174
175                result
176            }
177        }
178    };
179}
180
181pack_impl!(u8);
182pack_impl!(i8);
183
184pack_impl!(u16);
185pack_impl!(i16);
186
187pack_impl!(u32);
188pack_impl!(i32);
189
190pack_impl!(u64);
191pack_impl!(i64);
192
193pack_impl!(isize);
194pack_impl!(usize);
195
196pack_impl!(f32, 32);
197pack_impl!(f64, 64);