PHPserz

https://docs.rs/phpserz/0.3.0
Admin
PHPserz is a Rust crate for parsing and deserializing PHP serialization format with support for PHP...
Tokens:43,252
Snippets:343
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### PHP Serialized Output Example

Source: https://docs.rs/phpserz/0.3.0/phpserz

The resulting PHP serialized string from the above PHP code. This string can be used as input for deserialization in Rust.

```text
O:7:"Example":5:{s:4:"name";s:8:"John Doe";s:12:"\0Example\0age";i:42;s:11:"\0*\0isActive";b:1;s:6:"scores";a:3:{i:0;d:95.5;i:1;d:88.0;i:2;d:92.3;}s:8:"metadata";a:2:{s:2:"id";i:12345;s:4:"tags";a:3:{i:0;s:3:"php";i:1;s:4:"rust";i:2;s:13:"serialization";}}}
```

--------------------------------

### Generate PHP Serialized Output

Source: https://docs.rs/phpserz/0.3.0/index.html

Example of generating PHP serialized output using a PHP script. This demonstrates the expected format for serialized PHP objects.

```php
<?php
class Example {
    public $name = "John Doe";
    private $age = 42;
    protected $isActive = true;
    public $scores = [95.5, 88.0, 92.3];
    public $metadata = [
        "id" => 12345,
        "tags" => ["php", "rust", "serialization"]
    ];
}

$example = new Example();
$serialized = serialize($example);
echo $serialized;

```

--------------------------------

### Try reading next token as i64

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Attempts to parse the next token as a signed 64-bit integer. Requires the data to start with 'i:'.

```rust
    #[inline]
    pub(crate) fn try_read_i64(&mut self) -> Option<i64> {
        let data = self.data;
        match data {
            [b'i', b':', rest @ ..] => {
                let (int, data) = to_i64(rest).ok()?;
                self.data = data;
                Some(int)
            }
            _ => None,
        }
    }
```

--------------------------------

### Test Reading PHP Sequence Start

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Tests the `try_read_seq_start` method for parsing the beginning of a PHP sequence (array). It checks the expected number of elements, the parser's position, and the next token. Covers cases with empty and non-empty sequences, and non-array input.

```rust
    #[rstest]
    #[case(b"a:0:{}i:7;", 0, 5, PhpToken::End)]
    #[case(
        b"a:3:{i:0;s:3:"foo"";i:1;s:3:"bar"";i:2;s:3:"baz"";}",
        3,
        5,
        PhpToken::Integer(0)
    )]
    #[case(b"a:12:{}", 12, 6, PhpToken::End)]
    fn test_try_read_seq_start(
        #[case] input: &[u8],
        #[case] expected_elements: u32,
        #[case] expected_position: usize,
        #[case] next_token: PhpToken<'_>,
    ) {
        let mut parser = PhpParser::new(input);

        assert_eq!(parser.try_read_seq_start(), Some(expected_elements));
        assert_eq!(parser.position(), expected_position);
        assert_eq!(parser.read_token().unwrap(), next_token);
    }
```

```rust
    #[test]
    fn test_try_read_seq_start_returns_none_without_consuming_non_array_token() {
        let mut parser = PhpParser::new(b"i:42;");

        assert_eq!(parser.try_read_seq_start(), None);
        assert_eq!(parser.position(), 0);
        assert_eq!(parser.read_token().unwrap(), PhpToken::Integer(42));
    }
```

--------------------------------

### Create PhpDeserializer from bytes

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Instantiate a new PhpDeserializer with the provided byte slice. This is the primary way to start deserializing PHP data.

```rust
pub const fn new(data: &'de [u8]) -> Self {
        PhpDeserializer {
            parser: PhpParser::new(data),
        }
    }
```

--------------------------------

### Try reading next token as f64

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Attempts to parse the next token as a 64-bit float. Requires the data to start with 'd:' and end with ';'.

```rust
    #[inline]
    pub(crate) fn try_read_f64(&mut self) -> Option<f64> {
        let data = self.data;
        match data {
            [b'd', b':', rest @ ..] => {
                let (float, len) = fast_float2::parse_partial(rest).ok()?;
                let (tail, rest) = rest[len..].split_first()?;
                if tail != &b';' {
                    return None;
                }

                self.data = rest;
                Some(float)
            }
            _ => None,
        }
    }
```

--------------------------------

### Try reading next token as array header

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Attempts to parse the next token as an array header. Requires the data to start with 'a:', followed by a u32 element count, and then '{'.

```rust
    #[inline]
    pub(crate) fn try_read_seq_start(&mut self) -> Option<u32> {
        let data = self.data;
        match data {
            [b'a', b':', rest @ ..] => {
                let (elements, rest) = read_u32(rest, b':').ok()?;
                match rest {
                    [b'{', rest @ ..] => {
                        self.data = rest;
                        Some(elements)
                    }
                    _ => None,
                }
            }
            _ => None,
        }
    }
```

--------------------------------

### Reading Object Properties

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Demonstrates reading an object token and then sequentially reading its string properties. This snippet is part of a larger example showing how to parse complex serialized PHP objects.

```rust
let serialized = b"O:7:\"Example\":5:{s:4:\"name\";s:8:\"John Doe\";s:12:\"\0Example\0age\";i:42;s:11:\"\0*\0isActive\";b:1;s:6:\"scores\";a:3:{i:0;d:95.5;i:1;d:88.0;i:2;d:92.3;}s:8:\"metadata\";a:2:{s:2:\"id\";i:12345;s:4:\"tags\";a:3:{i:0;s:3:\"php\";i:1;s:4:\"rust\";i:2;s:13:\"serialization\";}}}";
        let mut parser = PhpParser::new(&serialized[..]);

        assert_eq!(
            parser.read_token()?,
            PhpToken::Object {
                class: PhpBstr::new(b"Example"),
                properties: 5
            }
        );

        let PhpToken::String(prop) = parser.read_token()? else {
            panic!("Expected a string token");
        };

        assert_eq!(prop, PhpBstr::new(b"name"));
        let prop = prop.to_property();
        assert_eq!(prop.to_str()?, "name");
        assert_eq!(prop.visibility(), PhpVisibility::Public);

        Ok(())
```

--------------------------------

### Get PhpProperty visibility

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Returns the visibility (Public, Protected, or Private) of the PHP property. This is an inline, constant-time operation.

```rust
pub const fn visibility(&self) -> PhpVisibility {
    self.visibility
}
```

--------------------------------

### Deserialize Externally Tagged Newtype Enum

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Demonstrates deserializing into a newtype enum variant using external tagging. This example shows the structure but not the deserialization logic itself.

```rust
#[derive(Debug, Deserialize, PartialEq)]
enum Message {
    Text(String),
    Number(i32),
}
```

--------------------------------

### Interoperability: From Parser to Deserializer and Back

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Demonstrates creating a `PhpDeserializer` from an existing `PhpParser` and then converting the deserializer back into a parser. This allows for incremental parsing and deserialization of complex PHP data structures.

```rust
// Create a parser with a complex structure
let input = b"i:42;s:5:\"hello\";b:1;";
let mut parser = PhpParser::new(input);

// Parse the first token manually
let token = parser.next_token().unwrap().unwrap();
assert_eq!(token, PhpToken::Integer(42));

// Create a deserializer from the parser at its current position
let mut deserializer = PhpDeserializer::from_parser(parser);

// Deserialize the next item (a string)
let result: String = Deserialize::deserialize(&mut deserializer).unwrap();
assert_eq!(result, "hello");

// Get the parser back
let mut parser = deserializer.into_parser();

// Continue parsing with the parser
let token = parser.next_token().unwrap().unwrap();
assert_eq!(token, PhpToken::Boolean(true));

// Verify no more tokens
```

--------------------------------

### position

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Get the current position of the parser within the input data.

```APIDOC
## position

### Description
Get the current position of the parser.

### Signature
`pub fn position(&self) -> usize`
```

--------------------------------

### Get Error Kind

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

Retrieves the specific kind of error that occurred. This is a constant function.

```rust
pub const fn kind(&self) -> &ErrorKind
```

--------------------------------

### Create PhpParser Instance

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpParser.html

Instantiate a new PhpParser from a byte slice representing PHP serialized data.

```rust
use phpserz::PhpParser;
let mut parser = PhpParser::new(b"i:42;");
```

--------------------------------

### Get underlying bytes of PhpBstr

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Retrieves the raw byte slice from a `PhpBstr`. This is a constant-time operation.

```rust
pub const fn as_bytes(&self) -> &'a [u8] {
    self.data
}
```

--------------------------------

### Implement Error Trait - Deprecated Cause

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

Deprecated method for getting the cause of the error. Replaced by Error::source.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Get underlying bytes of PhpProperty

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Retrieves the raw byte slice representing the property name. This is an inline, constant-time operation.

```rust
pub const fn as_bytes(&self) -> &'a [u8] {
    self.name
}
```

--------------------------------

### From and Into Implementations

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

Facilitates conversions between types. `From<T>` allows creating a type from another, while `Into<U>` allows converting a type into another if `From<T>` is implemented for `U`.

```rust
fn from(t: T) -> T
```

```rust
fn into(self) -> U
```

--------------------------------

### try_read_seq_start

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Attempts to read the next token as an array header, expecting a prefix of 'a:'. It returns the number of elements in the array if successful.

```APIDOC
## try_read_seq_start

### Description
Attempts to parse the start of a sequence (array) from the current data buffer. The data must start with the prefix `a:` followed by a u32 representing the number of elements, and then an opening brace `{`.

### Method
`pub(crate) fn try_read_seq_start(&mut self) -> Option<u32>`

### Parameters
None

### Returns
- `Some(u32)`: If an array header is successfully parsed, returns the number of elements.
- `None`: If the data does not conform to the expected array header format or parsing fails.
```

--------------------------------

### Get Error Position

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

Retrieves the optional position within the data where the error occurred. Returns None if the position is not applicable.

```rust
pub const fn position(&self) -> Option<usize>
```

--------------------------------

### Get Current Parser Position

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Returns the current byte offset within the original input data. Useful for error reporting.

```rust
/// Get the current position of the parser.
#[must_use]
pub fn position(&self) -> usize {
    self.original_len - self.data.len()
}
```

--------------------------------

### Manual PHP Token Parsing

Source: https://docs.rs/phpserz/0.3.0/phpserz/index.html

Shows how to manually parse PHP serialized data token by token using `PhpParser`. This provides lower-level control for inspecting the data.

```rust
use phpserz::{Error, PhpParser, PhpToken, PhpBstr, PhpVisibility};

let serialized = b"O:7:\"Example\":5:{s:4:\"name\";s:8:\"John Doe\";s:12:\"\0Example\0age\";i:42;s:11:\"\0*\0isActive\";b:1;s:6:\"scores\";a:3:{i:0;d:95.5;i:1;d:88.0;i:2;d:92.3;}";s:8:\"metadata\";a:2:{s:2:\"id\";i:12345;s:4:\"tags\";a:3:{i:0;s:3:\"php\";i:1;s:4:\"rust\";i:2;s:13:\"serialization\";}}}";

let mut parser = PhpParser::new(&serialized[..]);

assert_eq!(
    parser.read_token().unwrap(),
    PhpToken::Object {
        class: PhpBstr::new(b"Example"),
        properties: 5
    }
);

let PhpToken::String(prop) = parser.read_token().unwrap() else {
    panic!("Expected a string token");
};

assert_eq!(prop, PhpBstr::new(b"name"));
let prop = prop.to_property();
assert_eq!(prop.to_str().unwrap(), "name");
assert_eq!(prop.visibility(), PhpVisibility::Public);

// ...

```

--------------------------------

### CloneToUninit Implementation (Experimental)

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

An experimental nightly-only feature that allows cloning a value into uninitialized memory. Use with caution as it requires careful memory management.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Get Owned Version of Data

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Creates owned data from borrowed data, usually by cloning. This is part of the ToOwned trait implementation.

```rust
fn to_owned(&self) -> T
```

--------------------------------

### Create PhpParser from bytes

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Initializes a new `PhpParser` with the given byte slice. It stores the original length for potential future use.

```rust
pub const fn new(data: &'a [u8]) -> Self {
    Self {
        original_len: data.len(),
        data,
    }
}
```

--------------------------------

### PhpBstr::new

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpBstr.html

Creates a new PhpBstr from a slice of bytes.

```APIDOC
## PhpBstr::new

### Description
Create a new byte string from a slice of bytes.

### Signature
`pub const fn new(data: &'a [u8]) -> Self`
```

--------------------------------

### Create PhpDeserializer from existing parser

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Create a PhpDeserializer using an already initialized PhpParser. Useful when part of the data has already been processed.

```rust
pub const fn from_parser(parser: PhpParser<'de>) -> Self {
        PhpDeserializer {
            parser
        }
    }
```

--------------------------------

### Implement Error Trait - Deprecated Description

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

Deprecated method for getting a string description of the error. Use the Display impl or to_string() instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### PhpProperty Methods

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Provides methods to interact with PhpProperty instances.

```APIDOC
## PhpProperty

A PHP object property with its name and visibility.

### Methods

#### `as_bytes(&self) -> &'a [u8]`

Get the underlying bytes of the property name.

#### `to_str(self) -> Result<&'a str, Error>`

Convert the property name to a string.

#### `visibility(&self) -> PhpVisibility`

Get the visibility of the property.
```

--------------------------------

### TryFrom and TryInto Implementations

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

Provides fallible conversions between types. `TryFrom<U>` attempts a conversion that might fail, returning a `Result`. `TryInto<U>` is the reciprocal.

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Get Property Visibility

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Returns the visibility of the PHP property (e.g., public, private, protected). The PhpVisibility enum defines the possible visibility states.

```rust
pub const fn visibility(&self) -> PhpVisibility
```

--------------------------------

### try_read_i64

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Attempts to read the next token from the parser's data as a signed 64-bit integer. It expects the data to be prefixed with 'i:'.

```APIDOC
## try_read_i64

### Description
Attempts to parse a signed 64-bit integer from the current data buffer. The data must start with the prefix `i:` followed by the integer representation.

### Method
`pub(crate) fn try_read_i64(&mut self) -> Option<i64>`

### Parameters
None

### Returns
- `Some(i64)`: If an integer is successfully parsed, returns the integer value.
- `None`: If the data does not start with `i:` or if parsing fails.
```

--------------------------------

### Get Underlying Bytes of Property Name

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Retrieves the raw byte slice representing the property name. This is useful for low-level manipulation or when working with byte-oriented operations.

```rust
pub const fn as_bytes(&self) -> &'a [u8]
```

--------------------------------

### Peek and Read Token Position

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Demonstrates how to peek at the next token without advancing the parser's position, and then read the token to advance the position. This is useful for inspecting upcoming data before consuming it.

```rust
assert_eq!(parser.position(), 17);

        // Peek the third token
        let token_kind = parser.peek_token().unwrap().unwrap();
        assert_eq!(token_kind, PhpTokenKind::Boolean);
        assert_eq!(parser.position(), 17, "Position should not change after peeking");

        // Read the third token
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::Boolean(true));
        assert_eq!(parser.position(), 21);
```

--------------------------------

### Nested Object Deserialization with PhpDeserializer

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Deserialize nested objects from a PHP string representation. The `PhpDeserializer::from_parser` method allows deserialization to start from any point in the parsed input.

```rust
    #[test]
    fn test_nested_object_with_from_parser() {
        // Create a nested object structure
        let input = b"O:7:\"Example\":1:{s:4:\"user\";O:4:\"User\":2:{s:4:\"name\";s:5:\"Alice\";s:3:\"age\";i:30;}}";
        let mut parser = PhpParser::new(input);

        // Skip to the 'user' object
        parser.next_token().unwrap(); // Skip outer object
        parser.next_token().unwrap(); // Skip "user" string

        // Create a deserializer from the parser at user object position
        let mut deserializer = PhpDeserializer::from_parser(parser);

        // Deserialize just the User object
        let user: Person = Deserialize::deserialize(&mut deserializer).unwrap();

        assert_eq!(
            user,
            Person {
                name: "Alice".to_string(),
                age: 30
            }
        );

        // Get the parser back
        let mut parser = deserializer.into_parser();
        assert_eq!(parser.read_token().unwrap(), PhpToken::End);

        // Verify we're at the end
        assert_eq!(parser.position(), input.len());
    }
}
```

--------------------------------

### PhpParser::new

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpParser.html

Creates a new PhpParser instance from a byte slice representing PHP serialized data.

```APIDOC
## PhpParser::new

### Description
Create a new parser from a slice of bytes.

### Signature
```rust
pub const fn new(data: &'a [u8]) -> Self
```
```

--------------------------------

### StructuralPartialEq Implementation for PhpTokenKind

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

Provides structural equality comparison for PhpTokenKind. This is often used in more advanced scenarios involving type system analysis.

```rust
impl StructuralPartialEq for PhpTokenKind
```

--------------------------------

### Deserialize Valid UTF-8 String

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Deserializes a PHP string containing valid UTF-8 characters using `deserialize_str`. This example demonstrates successful deserialization of a string representing emojis.

```rust
let input = b"s:8:\"\xF0\x9F\x91\x8B\xF0\x9F\x8C\x8D\";"; // "\xF0\x9F\x91\x8B\xF0\x9F\x8C\x8D" is "👋🌍"
let mut deserializer = PhpDeserializer::new(&input[..]);
let result: ExplicitStr = Deserialize::deserialize(&mut deserializer).unwrap();
assert_eq!(result, ExplicitStr("👋🌍".to_string()));
```

--------------------------------

### Create PhpBstr from Bytes

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpBstr.html

Creates a new PhpBstr instance from a slice of bytes. This is the primary way to initialize a byte string.

```rust
pub const fn new(data: &'a [u8]) -> Self
```

--------------------------------

### Deserialize PHP Data with Serde

Source: https://docs.rs/phpserz/0.3.0/phpserz/index.html

Demonstrates deserializing PHP serialized data into Rust structs using the `serde` feature. Requires the `serde` and `phpserz` crates with the `serde` feature enabled.

```rust
#[cfg(feature = "serde")] {
use phpserz::PhpDeserializer;
use serde::Deserialize;
use std::collections::BTreeMap;

#[derive(Debug, Deserialize, PartialEq)]
struct Example {
    name: String,
    age: i32,
    #[serde(rename = "isActive")]
    is_active: bool,
    scores: BTreeMap<u32, f64>,
    metadata: Metadata,
}

#[derive(Debug, Deserialize, PartialEq)]
struct Metadata {
    id: i32,
    tags: BTreeMap<u32, String>,
}

let serialized = b"O:7:\"Example\":5:{s:4:\"name\";s:8:\"John Doe\";s:12:\"\0Example\0age\";i:42;s:11:\"\0*\0isActive\";b:1;s:6:\"scores\";a:3:{i:0;d:95.5;i:1;d:88.0;i:2;d:92.3;}";s:8:\"metadata\";a:2:{s:2:\"id\";i:12345;s:4:\"tags\";a:3:{i:0;s:3:\"php\";i:1;s:4:\"rust\";i:2;s:13:\"serialization\";}}}";

let mut deserializer = PhpDeserializer::new(serialized);
let example = Example::deserialize(&mut deserializer).unwrap();

assert_eq!(
    example,
    Example {
        name: "John Doe".to_string(),
        age: 42,
        is_active: true,
        scores: BTreeMap::from([
            (0, 95.5),
            (1, 88.0),
            (2, 92.3),
        ]),
        metadata: Metadata {
            id: 12345,
            tags: BTreeMap::from([
                (0, "php".to_string()),
                (1, "rust".to_string()),
                (2, "serialization".to_string())
            ]),
        }
    }
);
}

```

--------------------------------

### Borrow and BorrowMut Implementations

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

Enables borrowing references to PhpTokenKind values. BorrowMut allows mutable borrowing, facilitating in-place modifications.

```rust
fn borrow(&self) -> &T
```

```rust
fn borrow_mut(&mut self) -> &mut T
```

--------------------------------

### Deserialize i64 with optional direct read

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Implements `serde::Deserializer::deserialize_i64`. Attempts to read a 64-bit integer directly; if unsuccessful, falls back to `deserialize_any`.

```rust
fn deserialize_i64<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: de::Visitor<'de>,
    {
        match self.parser.try_read_i64() {
            Some(i) => visitor.visit_i64(i),
            None => self.deserialize_any(visitor),
        }
    }
```

--------------------------------

### Deserialize PHP Data with Serde

Source: https://docs.rs/phpserz/0.3.0/index.html

Demonstrates deserializing PHP serialized data into Rust structs using the `serde` feature. Requires the `serde` feature flag to be enabled.

```rust
#[cfg(feature = "serde")] {
use phpserz::PhpDeserializer;
use serde::Deserialize;
use std::collections::BTreeMap;

#[derive(Debug, Deserialize, PartialEq)]
struct Example {
    name: String,
    age: i32,
    #[serde(rename = "isActive")]
    is_active: bool,
    scores: BTreeMap<u32, f64>,
    metadata: Metadata,
}

#[derive(Debug, Deserialize, PartialEq)]
struct Metadata {
    id: i32,
    tags: BTreeMap<u32, String>,
}

let serialized = b"O:7:\"Example\":5:{s:4:\"name\";s:8:\"John Doe\";s:12:\"\0Example\0age\";i:42;s:11:\"\0*\0isActive\";b:1;s:6:\"scores\";a:3:{i:0;d:95.5;i:1;d:88.0;i:2;d:92.3;}\
    s:8:\"metadata\";a:2:{s:2:\"id\";i:12345;s:4:\"tags\";a:3:{i:0;s:3:\"php\";i:1;s:4:\"rust\";i:2;s:13:\"serialization\";}}}";

let mut deserializer = PhpDeserializer::new(serialized);
let example = Example::deserialize(&mut deserializer).unwrap();

assert_eq!(
    example,
    Example {
        name: "John Doe".to_string(),
        age: 42,
        is_active: true,
        scores: BTreeMap::from([
            (0, 95.5),
            (1, 88.0),
            (2, 92.3),
        ]),
        metadata: Metadata {
            id: 12345,
            tags: BTreeMap::from([
                (0, "php".to_string()),
                (1, "rust".to_string()),
                (2, "serialization".to_string())
            ]),
        }
    }
);
}

```

--------------------------------

### PhpParser

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

A parser for the PHP serialized format.

```APIDOC
## PhpParser<'a>

### Description
A parser for the PHP serialized format.

### Methods

#### `new(data: &'a [u8]) -> Self`
Create a new parser from a slice of bytes.
```

--------------------------------

### PartialEq Implementation for PhpTokenKind

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

Enables comparison of PhpTokenKind values for equality. This is fundamental for checking if two tokens are of the same kind.

```rust
fn eq(&self, other: &PhpTokenKind) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### Implement From<T> for T

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

A trivial implementation that returns the argument unchanged. This is a blanket implementation for any type `T`.

```rust
fn from(t: T) -> T
```

--------------------------------

### Compare PhpProperty for Equality

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Tests if two PhpProperty instances are equal based on their name and visibility. This is part of the PartialEq trait implementation.

```rust
fn eq(&self, other: &PhpProperty<'a>) -> bool
```

--------------------------------

### try_read_f64

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Attempts to read the next token from the parser's data as a double-precision floating-point number. It expects the data to be prefixed with 'd:'.

```APIDOC
## try_read_f64

### Description
Attempts to parse a double-precision floating-point number from the current data buffer. The data must start with the prefix `d:` followed by the float representation, and end with a semicolon.

### Method
`pub(crate) fn try_read_f64(&mut self) -> Option<f64>`

### Parameters
None

### Returns
- `Some(f64)`: If a float is successfully parsed, returns the float value.
- `None`: If the data does not start with `d:`, is malformed, or parsing fails.
```

--------------------------------

### Deserialize PHP tokens to Rust values

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Internal helper to map PhpToken variants to corresponding `serde::Visitor` methods. Handles primitive types, arrays, objects, and custom objects.

```rust
fn deserialize_token<V>(&mut self, visitor: V, token: PhpToken<'de>) -> Result<V::Value, Error>
    where
        V: de::Visitor<'de>,
    {
        match token {
            PhpToken::Null => visitor.visit_unit(),
            PhpToken::Boolean(b) => visitor.visit_bool(b),
            PhpToken::Integer(i) => visitor.visit_i64(i),
            PhpToken::Float(f) => visitor.visit_f64(f),
            PhpToken::String(s) => visitor.visit_borrowed_bytes(s.as_bytes()),
            PhpToken::Array { elements } => visitor.visit_map(PhpMapAccess {
                de: self,
                remaining: elements,
            }),
            PhpToken::Object { properties, .. } => visitor.visit_map(PhpMapAccess {
                de: self,
                remaining: properties,
            }),
            PhpToken::CustomObject { payload, .. } => {
                visitor.visit_borrowed_bytes(payload.as_bytes())
            }
            PhpToken::Reference { id, .. } => visitor.visit_i64(id),
            _ => Err(Error::from(ErrorKind::Deserialize {
                message: "Unexpected token".to_string(),
                position: Some(self.parser.position()),
            })),
        }
    }
```

--------------------------------

### Compare PhpProperty for Inequality

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Tests if two PhpProperty instances are not equal. This is part of the PartialEq trait implementation.

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### impl<'de> Deserializer<'de> for &'_ mut PhpDeserializer<'de>

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Implementation of the serde::Deserializer trait for PhpDeserializer.

```APIDOC
## impl<'de> Deserializer<'de> for &'_ mut PhpDeserializer<'de>

### Description
This block implements the `serde::Deserializer` trait for a mutable reference to `PhpDeserializer`. It defines how various data types can be deserialized from PHP serialized format.

### Methods
- `deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Attempts to deserialize any valid PHP token.
- `deserialize_bool<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes a boolean value.
- `deserialize_i8<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes an i8 value by delegating to `deserialize_i64`.
- `deserialize_i16<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes an i16 value by delegating to `deserialize_i64`.
- `deserialize_i32<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes an i32 value by delegating to `deserialize_i64`.
- `deserialize_i64<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes an i64 value, attempting to read it directly or falling back to `deserialize_any`.
- `deserialize_u8<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes a u8 value by delegating to `deserialize_i64`.
- `deserialize_u16<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes a u16 value by delegating to `deserialize_i64`.
- `deserialize_u32<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes a u32 value by delegating to `deserialize_i64`.
- `deserialize_u64<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes a u64 value by delegating to `deserialize_i64`.
- `deserialize_f32<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes an f32 value by delegating to `deserialize_f64`.
- `deserialize_f64<V>(self, visitor: V) -> Result<V::Value, Self::Error>`: Deserializes an f64 value, attempting to read it directly or falling back to `deserialize_any`.
```

--------------------------------

### Test Position Tracking During Tokenization

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Verifies that the parser correctly tracks its current position within the input byte stream after parsing each token. Demonstrates parsing integers and strings.

```rust
let input = b"i:42;s:5:\"hello\";";
let mut parser = PhpParser::new(input);

assert_eq!(parser.position(), 0, "Initial position should be 0");

// Parse the integer
let token = parser.next_token().unwrap().unwrap();
assert_eq!(token, PhpToken::Integer(42));
assert_eq!(
    parser.position(),
    5,
    "Position after parsing 'i:42;' should be 5"
);

// Parse the string
let token = parser.next_token().unwrap().unwrap();
assert_eq!(token, PhpToken::String(PhpBstr::new(b"hello")));
assert_eq!(
    parser.position(),
    17,
    "Position after parsing full input should be 17"
);

// Verify no more tokens
assert!(parser.next_token().unwrap().is_none());
assert_eq!(
    parser.position(),
    17,
    "Position should not change when reaching end of input"
);
```

--------------------------------

### Position Tracking with Complex Structures

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Illustrates position tracking when parsing a complex PHP serialized structure, including arrays, integers, and strings. It verifies that the parser's position updates correctly after each token is read.

```rust
let input = b"a:1:{i:0;s:5:\"hello\";}";
        let mut parser = PhpParser::new(input);

        // Read array start
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::Array { elements: 1 });
        assert_eq!(parser.position(), 5, "Position after array start should be 5");

        // Peek next token (should be integer)
        let token_kind = parser.peek_token().unwrap().unwrap();
        assert_eq!(token_kind, PhpTokenKind::Integer);
        assert_eq!(parser.position(), 5, "Position should not change after peeking");

        // Read integer
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::Integer(0));
        assert_eq!(parser.position(), 9, "Position after integer should be 9");

        // Read string
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::String(PhpBstr::new(b"hello")));
        assert_eq!(parser.position(), 21, "Position after string should be 21");

        // Read end token
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::End);
        assert_eq!(parser.position(), 22, "Position after end token should be 22");
```

--------------------------------

### Manual Token Parsing

Source: https://docs.rs/phpserz/0.3.0/phpserz

Low-level parsing of PHP serialized data using `PhpParser`. This allows for granular inspection of tokens and their properties.

```rust
use phpserz::{Error, PhpParser, PhpToken, PhpBstr, PhpVisibility};

let serialized = b"O:7:\"Example\":5:{s:4:\"name\";s:8:\"John Doe\";s:12:\"\0Example\0age\";i:42;s:11:\"\0*\0isActive\";b:1;s:6:\"scores\";a:3:{i:0;d:95.5;i:1;d:88.0;i:2;d:92.3;}s:8:\"metadata\";a:2:{s:2:\"id\";i:12345;s:4:\"tags\";a:3:{i:0;s:3:\"php\";i:1;s:4:\"rust\";i:2;s:13:\"serialization\";}}}";

let mut parser = PhpParser::new(&serialized[..]);

assert_eq!(
    parser.read_token().unwrap(),
    PhpToken::Object {
        class: PhpBstr::new(b"Example"),
        properties: 5
    }
);

let PhpToken::String(prop) = parser.read_token().unwrap() else {
    panic!("Expected a string token");
};

assert_eq!(prop, PhpBstr::new(b"name"));
let prop = prop.to_property();
assert_eq!(prop.to_str().unwrap(), "name");
assert_eq!(prop.visibility(), PhpVisibility::Public);

// ...

```

--------------------------------

### PhpDeserializer::new

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpDeserializer.html

Creates a new PhpDeserializer instance from a slice of bytes representing PHP serialized data.

```APIDOC
## PhpDeserializer::new

### Description
Creates a new deserializer from a slice of bytes.

### Signature
```rust
pub const fn new(data: &'de [u8]) -> Self
```

### Parameters
* `data` (&'de [u8]): A slice of bytes containing the PHP serialized data.
```

--------------------------------

### Deserialize Char with Fast Path in Rust

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Demonstrates deserializing a multi-byte character (emoji) into a Rust char using the fast path optimization for short strings. This occurs when trailing data ensures sufficient buffer space.

```rust
let input = b"s:4:\"\xF0\x9F\x98\x80\";s:1:\"z\";";
let mut deserializer = PhpDeserializer::new(&input[..]);
let result: char = Deserialize::deserialize(&mut deserializer).unwrap();
assert_eq!(result, '😀');
```

--------------------------------

### Deserialize f64 with optional direct read

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Implements `serde::Deserializer::deserialize_f64`. Attempts to read a 64-bit float directly; if unsuccessful, falls back to `deserialize_any`.

```rust
fn deserialize_f64<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: de::Visitor<'de>,
    {
        match self.parser.try_read_f64() {

```

--------------------------------

### Implement Error Trait - Provide (Nightly)

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

A nightly-only experimental API for providing type-based access to error context. Requires the `error_generic_member_access` feature.

```rust
fn provide<'a>(&'a self, request: &mut Request<'a>)
```

--------------------------------

### PhpDeserializer::into_parser

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpDeserializer.html

Consumes the PhpDeserializer instance and returns the underlying PhpParser. This allows for continued parsing after deserialization is complete.

```APIDOC
## PhpDeserializer::into_parser

### Description
Consume this deserializer and return the underlying parser. This allows you to continue parsing after deserialization is complete.

### Signature
```rust
pub fn into_parser(self) -> PhpParser<'de>
```

### Returns
(PhpParser<'de>): The underlying PhpParser instance.
```

--------------------------------

### Position Tracking with Nested Structures

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Shows how the parser's position is managed when dealing with nested PHP serialized arrays. It verifies that the position increases correctly as nested elements are parsed.

```rust
let input = b"a:1:{i:0;a:1:{i:0;s:5:\"hello\";}}";
        let mut parser = PhpParser::new(input);

        // Read outer array start
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::Array { elements: 1 });
        let pos_after_outer_array = parser.position();

        // Read key
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::Integer(0));

        // Read inner array start
        let token = parser.next_token().unwrap().unwrap();
        assert_eq!(token, PhpToken::Array { elements: 1 });
        let pos_after_inner_array = parser.position();
        assert!(pos_after_inner_array > pos_after_outer_array, "Position should increase after reading inner array");

        let tokens = std::iter::from_fn(|| parser.next_token().unwrap());

        assert_eq!(tokens.count(), 4);
        assert_eq!(parser.position(), input.len(), "Position should be at the end of input");
```

--------------------------------

### Test Deserializing Null in PHP

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Verifies that the deserializer correctly handles PHP null values, mapping them to Rust Option::None.

```rust
#[test]
fn test_deserialize_null() {
    let input = b"N;";
    let mut deserializer = PhpDeserializer::new(&input[..]);
    let result: Option<String> = Deserialize::deserialize(&mut deserializer).unwrap();
    assert_eq!(result, None);
}
```

--------------------------------

### PhpProperty

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Represents a PHP object property with its name and visibility.

```APIDOC
## PhpProperty<'a>

### Description
A PHP object property with its name and visibility.

### Methods

#### `as_bytes(&self) -> &'a [u8]`
Get the underlying bytes of the property name.

#### `to_str(self) -> Result<&'a str, Error>`
Convert the property name to a string. Returns an error if the bytes are not valid UTF-8.

#### `visibility(&self) -> PhpVisibility`
Get the visibility of the property.
```

--------------------------------

### Clone From Another PhpProperty

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpProperty.html

Performs copy-assignment from a source PhpProperty to the current one. This is part of the Clone trait implementation.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### Compare PhpBstr for Equality

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.PhpBstr.html

Implements the PartialEq trait for PhpBstr, enabling equality comparisons between two instances.

```rust
fn eq(&self, other: &PhpBstr<'a>) -> bool
```

--------------------------------

### Deserialize any value

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Implements `serde::Deserializer::deserialize_any`. Reads the next token from the parser and dispatches it for deserialization.

```rust
fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Self::Error>
    where
        V: de::Visitor<'de>,
    {
        let token = self.parser.read_token()?;
        self.deserialize_token(visitor, token)
    }
```

--------------------------------

### Serde-specific Error Constructors

Source: https://docs.rs/phpserz/0.3.0/phpserz/struct.Error.html

Constructors for creating specific types of deserialization errors when the `serde` feature is enabled.

```APIDOC
## impl Error for Error (Available on crate feature `serde` only)

### fn custom<T: Display>(msg: T) -> Self
Raised when there is general error when deserializing a type.

### fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self
Raised when a `Deserialize` receives a type different from what it was expecting.

### fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self
Raised when a `Deserialize` receives a value of the right type but that is wrong for some other reason.

### fn invalid_length(len: usize, exp: &dyn Expected) -> Self
Raised when deserializing a sequence or map and the input data contains too many or too few elements.

### fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self
Raised when a `Deserialize` enum type received a variant with an unrecognized name.

### fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self
Raised when a `Deserialize` struct type received a field with an unrecognized name.

### fn missing_field(field: &'static str) -> Self
Raised when a `Deserialize` struct type expected to receive a required field with a particular name but that field was not present in the input.

### fn duplicate_field(field: &'static str) -> Self
Raised when a `Deserialize` struct type received more than one of the same field.
```

--------------------------------

### PhpToken

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Represents a token in the PHP serialized format.

```APIDOC
## PhpToken<'a>

### Description
A token in the PHP serialized format.

### Variants

- **Null**: The null token.
- **Boolean(bool)**: The boolean token.
- **Integer(i64)**: The integer token.
- **Float(f64)**: The float token.
- **String(PhpBstr<'a>)**: The string token.
- **Array { elements: u32 }**: The array token.
- **Object { class: PhpBstr<'a>, properties: u32 }**: The object token.
- **CustomObject { class: PhpBstr<'a>, payload: PhpBstr<'a> }**: A custom-serialized object token.
- **End**: The end of an array or object.
- **Reference { id: i64, kind: PhpReferenceKind }**: The reference token.
```

--------------------------------

### Deserialize PHP Sequence to Vec

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/de.rs.html

Demonstrates deserializing a PHP sequence into a Rust Vec. Handles empty sequences correctly.

```rust
let input = b"a:0:{}";
let mut deserializer = PhpDeserializer::new(&input[..]);
let result = ExplicitSeq::deserialize(&mut deserializer).unwrap();
assert_eq!(result, ExplicitSeq(vec![]));
```

--------------------------------

### PartialEq Trait Implementation

Source: https://docs.rs/phpserz/0.3.0/phpserz/enum.PhpTokenKind.html

Allows comparison of PhpTokenKind instances for equality.

```APIDOC
### impl PartialEq for PhpTokenKind

#### fn eq(&self, other: &PhpTokenKind) -> bool
Tests for `self` and `other` values to be equal, and is used by `==`.

#### fn ne(&self, other: &Rhs) -> bool
Tests for `!=`.
```

--------------------------------

### PhpReferenceKind

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

The kind of PHP reference token.

```APIDOC
## PhpReferenceKind

### Description
The kind of PHP reference token.

### Variants

- **Repeated**: A repeated object back-reference encoded with the lowercase `r` marker.
- **Alias**: A PHP variable alias (`&`) encoded with the uppercase `R` marker.
```

--------------------------------

### Test Reading PHP Integers

Source: https://docs.rs/phpserz/0.3.0/src/phpserz/parser.rs.html

Tests the `try_read_i64` method for parsing PHP integers. It verifies the parsed integer value, the parser's position after reading, and the subsequent token. Also checks behavior when the input is not an integer.

```rust
    #[rstest]
    #[case(b"i:-3;s:2:"ok"";", -3, 5, PhpToken::String(PhpBstr::new(b"ok")))]
    #[case(b"i:42;i:7;", 42, 5, PhpToken::Integer(7))]
    fn test_try_read_i64(
        #[case] input: &[u8],
        #[case] expected: i64,
        #[case] expected_position: usize,
        #[case] next_token: PhpToken<'_>,
    ) {
        let mut parser = PhpParser::new(input);

        assert_eq!(parser.try_read_i64(), Some(expected));
        assert_eq!(parser.position(), expected_position);
        assert_eq!(parser.read_token().unwrap(), next_token);
    }
```

```rust
    #[test]
    fn test_try_read_i64_returns_none_without_consuming_non_integer_token() {
        let mut parser = PhpParser::new(b"s:2:"ok"";);

        assert_eq!(parser.try_read_i64(), None);
        assert_eq!(parser.position(), 0);
        assert_eq!(
            parser.read_token().unwrap(),
            PhpToken::String(PhpBstr::new(b"ok"))
        );
    }
```
Tokens:
Raw