Merge remote-tracking branch 'joel/feat/iterator'

Author: danog

allowed_bindings.rs

@@ -94,6 +94,7 @@ bind! {
     zend_internal_arg_info,
     zend_is_callable,
     zend_is_identical,
+    zend_is_iterable,
     zend_long,
     zend_lookup_class_ex,
     zend_module_entry,
@@ -163,6 +164,7 @@ bind! {
     IS_UNDEF,
     IS_VOID,
     IS_PTR,
+    IS_ITERABLE,
     MAY_BE_ANY,
     MAY_BE_BOOL,
     PHP_INI_USER,

docsrs_bindings.rs

@@ -97,6 +97,7 @@ pub const IS_RESOURCE: u32 = 9;
 pub const IS_REFERENCE: u32 = 10;
 pub const IS_CONSTANT_AST: u32 = 11;
 pub const IS_CALLABLE: u32 = 12;
+pub const IS_ITERABLE: u32 = 13;
 pub const IS_VOID: u32 = 14;
 pub const IS_MIXED: u32 = 16;
 pub const IS_INDIRECT: u32 = 12;
@@ -1655,6 +1656,9 @@ extern "C" {
         named_params: *mut HashTable,
     );
 }
+extern "C" {
+    pub fn zend_is_iterable(iterable: *mut zval) -> bool;
+}
 pub const _zend_expected_type_Z_EXPECTED_LONG: _zend_expected_type = 0;
 pub const _zend_expected_type_Z_EXPECTED_LONG_OR_NULL: _zend_expected_type = 1;
 pub const _zend_expected_type_Z_EXPECTED_BOOL: _zend_expected_type = 2;

guide/src/types/iterable.md

@@ -0,0 +1,59 @@
+# `Iterable`
+
+`Iterable`s are represented either by an `array` or `Traversable` type.
+
+| `T` parameter | `&T` parameter | `T` Return type | `&T` Return type | PHP representation               |
+|---------------|----------------|-----------------| ---------------- |----------------------------------|
+| Yes           | No             | No              | No               | `ZendHashTable` or `ZendIterator` |
+
+Converting from a zval to a `Iterable` is valid when the value is either an array or an object 
+that implements the `Traversable` interface. This means that any value that can be used in a
+`foreach` loop can be converted into a `Iterable`.
+
+## Rust example
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+# use ext_php_rs::types::Iterable;
+#[php_function]
+pub fn test_iterable(mut iterable: Iterable) {
+    for (k, v) in iterable.iter().expect("cannot get iterable") {
+        println!("k: {} v: {}", k, v.string().unwrap());
+    }
+}
+# fn main() {}
+```
+
+## PHP example
+
+```php
+<?php
+
+$generator = function() {
+    yield 'hello' => 'world';
+    yield 'rust' => 'php';
+    yield 'okk';
+};
+
+$array = [
+    'hello' => 'world',
+    'rust' => 'php',
+    'okk',
+];
+
+test_iterable($generator());
+test_iterable($array);
+```
+
+Output:
+
+```text
+k: hello v: world
+k: rust v: php
+k: 0 v: okk
+k: hello v: world
+k: rust v: php
+k: 0 v: okk
+```

guide/src/types/iterator.md

@@ -0,0 +1,50 @@
+# `ZendIterator`
+
+`ZendIterator`s are represented by the `Traversable` type.
+
+| `T` parameter | `&T` parameter | `T` Return type | `&T` Return type | PHP representation |
+|---------------| -------------- |-----------------| ---------------- | ------------------ |
+| No            | Yes            | No              | No               | `ZendIterator`    |
+
+Converting from a zval to a `ZendIterator` is valid when there is an associated iterator to 
+the variable. This means that any value, at the exception of an `array`, that can be used in 
+a `foreach` loop can be converted into a `ZendIterator`. As an example, a `Generator` can be
+used but also a the result of a `query` call with `PDO`.
+
+## Rust example
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+# use ext_php_rs::types::ZendIterator;
+#[php_function]
+pub fn test_iterator(iterator: &mut ZendIterator) {
+    for (k, v) in iterator.iter().expect("cannot get iterator") {
+        println!("k: {} v: {}", k, v.string().unwrap());
+    }
+}
+# fn main() {}
+```
+
+## PHP example
+
+```php
+<?php
+
+$generator = function() {
+    yield 'hello' => 'world';
+    yield 'rust' => 'php';
+    yield 'okk';
+};
+
+test_iterator($generator());
+```
+
+Output:
+
+```text
+k: hello v: world
+k: rust v: php
+k: 0 v: okk
+```

src/describe/stub.rs

@@ -172,6 +172,7 @@ impl ToStub for DataType {
                 DataType::Reference => "reference",
                 DataType::Callable => "callable",
                 DataType::Bool => "bool",
+                DataType::Iterable => "iterable",
                 _ => "mixed",
             }
         )

src/flags.rs

@@ -9,6 +9,7 @@ use crate::ffi::{
     E_COMPILE_WARNING, E_CORE_ERROR, E_CORE_WARNING, E_DEPRECATED, E_ERROR, E_NOTICE, E_PARSE,
     E_RECOVERABLE_ERROR, E_STRICT, E_USER_DEPRECATED, E_USER_ERROR, E_USER_NOTICE, E_USER_WARNING,
     E_WARNING, IS_ARRAY, IS_CALLABLE, IS_CONSTANT_AST, IS_DOUBLE, IS_FALSE, IS_INDIRECT, IS_LONG,
+    IS_ITERABLE, 
     IS_MIXED, IS_NULL, IS_OBJECT, IS_PTR, IS_REFERENCE, IS_RESOURCE, IS_STRING, IS_TRUE,
     IS_TYPE_COLLECTABLE, IS_TYPE_REFCOUNTED, IS_UNDEF, IS_VOID, PHP_INI_ALL, PHP_INI_PERDIR,
     PHP_INI_SYSTEM, PHP_INI_USER, ZEND_ACC_ABSTRACT, ZEND_ACC_ANON_CLASS,
@@ -49,6 +50,7 @@ bitflags! {
         const ConstantExpression = IS_CONSTANT_AST;
         const Void = IS_VOID;
         const Ptr = IS_PTR;
+        const Iterable = IS_ITERABLE;
 
         const InternedStringEx = Self::String.bits();
         const StringEx = Self::String.bits() | Self::RefCounted.bits();
@@ -237,6 +239,7 @@ pub enum DataType {
     Double,
     String,
     Array,
+    Iterable,
     Object(Option<&'static str>),
     Resource,
     Reference,
@@ -277,6 +280,7 @@ impl DataType {
             DataType::Mixed => IS_MIXED,
             DataType::Bool => _IS_BOOL,
             DataType::Ptr => IS_PTR,
+            DataType::Iterable => IS_ITERABLE,
         }
     }
 }
@@ -383,6 +387,7 @@ impl Display for DataType {
             DataType::Mixed => write!(f, "Mixed"),
             DataType::Ptr => write!(f, "Pointer"),
             DataType::Indirect => write!(f, "Indirect"),
+            DataType::Iterable => write!(f, "Iterable"),
         }
     }
 }

src/types/array.rs

@@ -10,6 +10,7 @@ use std::{
     u64,
 };
 
+use crate::types::iterator::IterKey;
 use crate::{
     boxed::{ZBox, ZBoxable},
     convert::{FromZval, IntoZval},
@@ -463,7 +464,7 @@ impl ZendHashTable {
     /// assert!(!ht.has_numerical_keys());
     /// ```
     pub fn has_numerical_keys(&self) -> bool {
-        !self.iter().any(|(_, k, _)| k.is_some())
+        !self.iter().any(|(k, _)| !k.is_numerical())
     }
 
     /// Checks if the hashtable has numerical, sequential keys.
@@ -492,7 +493,7 @@ impl ZendHashTable {
         !self
             .iter()
             .enumerate()
-            .any(|(i, (k, strk, _))| i as u64 != k || strk.is_some())
+            .any(|(i, (k, _))| IterKey::Long(i as u64) != k)
     }
 
     /// Returns an iterator over the key(s) and value contained inside the
@@ -505,12 +506,12 @@ impl ZendHashTable {
     ///
     /// let mut ht = ZendHashTable::new();
     ///
-    /// for (idx, key, val) in ht.iter() {
+    /// for (key, val) in ht.iter() {
     /// //   ^ Index if inserted at an index.
     /// //        ^ Optional string key, if inserted like a hashtable.
     /// //             ^ Inserted value.
     ///
-    ///     dbg!(idx, key, val);
+    ///     dbg!(key, val);
     /// }
     #[inline]
     pub fn iter(&self) -> Iter {
@@ -546,10 +547,7 @@ unsafe impl ZBoxable for ZendHashTable {
 impl Debug for ZendHashTable {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_map()
-            .entries(
-                self.iter()
-                    .map(|(k, k2, v)| (k2.unwrap_or_else(|| k.to_string()), v)),
-            )
+            .entries(self.iter().map(|(k, v)| (k.to_string(), v)))
             .finish()
     }
 }
@@ -594,7 +592,7 @@ impl<'a> Iter<'a> {
 }
 
 impl<'a> Iterator for Iter<'a> {
-    type Item = (u64, Option<String>, &'a Zval);
+    type Item = (IterKey, &'a Zval);
 
     fn next(&mut self) -> Option<Self::Item> {
         let key_type = unsafe {
@@ -622,9 +620,10 @@ impl<'a> Iterator for Iter<'a> {
                 &mut self.pos as *mut HashPosition,
             )
         };
-        let r: (u64, Option<String>, &Zval) = match key.is_long() {
-            true => (key.long().unwrap_or(0) as u64, None, value),
-            false => (self.current_num, key.try_into().ok(), value),
+
+        let r = match IterKey::from_zval(&key) {
+            Some(key) => (key, value),
+            None => (IterKey::Long(self.current_num), value),
         };
 
         unsafe {
@@ -679,9 +678,10 @@ impl<'a> DoubleEndedIterator for Iter<'a> {
                 &mut self.pos as *mut HashPosition,
             )
         };
-        let r: (u64, Option<String>, &Zval) = match key.is_long() {
-            true => (key.long().unwrap_or(0) as u64, None, value),
-            false => (self.current_num, key.try_into().ok(), value),
+
+        let r = match IterKey::from_zval(&key) {
+            Some(key) => (key, value),
+            None => (IterKey::Long(self.current_num), value),
         };
 
         unsafe {
@@ -715,7 +715,7 @@ impl<'a> Iterator for Values<'a> {
     type Item = &'a Zval;
 
     fn next(&mut self) -> Option<Self::Item> {
-        self.0.next().map(|(_, _, zval)| zval)
+        self.0.next().map(|(_, zval)| zval)
     }
 
     fn count(self) -> usize
@@ -734,7 +734,7 @@ impl<'a> ExactSizeIterator for Values<'a> {
 
 impl<'a> DoubleEndedIterator for Values<'a> {
     fn next_back(&mut self) -> Option<Self::Item> {
-        self.0.next_back().map(|(_, _, zval)| zval)
+        self.0.next_back().map(|(_, zval)| zval)
     }
 }
 
@@ -780,9 +780,9 @@ where
     fn try_from(value: &'a ZendHashTable) -> Result<Self> {
         let mut hm = HashMap::with_capacity(value.len());
 
-        for (idx, key, val) in value.iter() {
+        for (key, val) in value.iter() {
             hm.insert(
-                key.unwrap_or_else(|| idx.to_string()),
+                key.to_string(),
                 V::from_zval(val).ok_or_else(|| Error::ZvalConversion(val.get_type()))?,
             );
         }
@@ -849,7 +849,7 @@ where
     fn try_from(value: &'a ZendHashTable) -> Result<Self> {
         let mut vec = Vec::with_capacity(value.len());
 
-        for (_, _, val) in value.iter() {
+        for (_, val) in value.iter() {
             vec.push(T::from_zval(val).ok_or_else(|| Error::ZvalConversion(val.get_type()))?);
         }
 

src/types/iterable.rs

@@ -0,0 +1,57 @@
+use super::array::Iter as ZendHashTableIter;
+use super::iterator::Iter as ZendIteratorIter;
+use crate::convert::FromZval;
+use crate::flags::DataType;
+use crate::types::iterator::IterKey;
+use crate::types::{ZendHashTable, ZendIterator, Zval};
+
+/// This type represents a PHP iterable, which can be either an array or an object implementing
+/// the Traversable interface.
+#[derive(Debug)]
+pub enum Iterable<'a> {
+    Array(&'a ZendHashTable),
+    Traversable(&'a mut ZendIterator),
+}
+
+impl<'a> Iterable<'a> {
+    /// Creates a new rust iterator from a PHP iterable.
+    pub fn iter(&mut self) -> Option<Iter> {
+        match self {
+            Iterable::Array(array) => Some(Iter::Array(array.iter())),
+            Iterable::Traversable(traversable) => Some(Iter::Traversable(traversable.iter()?)),
+        }
+    }
+}
+
+impl<'a> FromZval<'a> for Iterable<'a> {
+    const TYPE: DataType = DataType::Iterable;
+
+    fn from_zval(zval: &'a Zval) -> Option<Self> {
+        if let Some(array) = zval.array() {
+            return Some(Iterable::Array(array));
+        }
+
+        if let Some(traversable) = zval.traversable() {
+            return Some(Iterable::Traversable(traversable));
+        }
+
+        None
+    }
+}
+
+/// Rust iterator over a PHP iterable.
+pub enum Iter<'a> {
+    Array(ZendHashTableIter<'a>),
+    Traversable(ZendIteratorIter<'a>),
+}
+
+impl<'a> Iterator for Iter<'a> {
+    type Item = (IterKey, &'a Zval);
+
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            Iter::Array(array) => array.next(),
+            Iter::Traversable(traversable) => traversable.next(),
+        }
+    }
+}