Documentation for new mixed key / integer key capabilities.

Author: StringEpsilon

PhpSerializerNET/Attributes/PhpProperty.cs

@@ -14,14 +14,20 @@ public class PhpPropertyAttribute : Attribute {
 		public long Key { get; set; }
 		public bool IsInteger { get; private set; } = false;
 
+		/// <summary>
+		/// Define the property key, as a string, for de/serialization.
+		/// </summary>
 		public PhpPropertyAttribute(string name) {
 			this.Name = name;
 		}
 
 		/// <summary>
-		/// Define an integer key for a given property.
+		/// Define an integer key for de/serialization.
 		/// Note: This also affects serialization into object notation, as that is a legal way of representing an object.
 		/// </summary>
+		/// <remark>
+		/// Deserialization of objects and arrays with mixed keys may yield unexpected results and or exceptions on certain target types.
+		/// </remarks>
 		public PhpPropertyAttribute(long key) {
 			this.Key = key;
 			this.IsInteger = true;

docs/Attributes/PhpProperty.md

@@ -4,18 +4,40 @@
 
 **Table of contents**
 1. [PhpProperty](#PhpProperty)
+	1. [Signatures](#signatures)
+1. [Examples](#Examples)
 	1. [Example 1: Serialize](#Example-1:-Serialize)
-	2. [Example 2: Deserialize with classname](#Example-1:-Deserialize-with-classname)
-	3. [Example 3: Deserialization with actual name.](#Example-1:-Deserialize-with-actual-name)
+	2. [Example 2: Serialize with integer keys](#Example-1:-Serialize)
+	3. [Example 3: Deserialize with classname](#Example-3:-Deserialize)
+	4. [Example 4: Deserialization with actual name.](#Example-4:-Deserialization-with-actual-name)
+	4. [Example 5: Deserialize with integer names](#Example-5:-Deserialize-with-integer-names)
 
----
 
 # PhpProperty
 
 Specifiy the name of the property in the serialization data, for both serialization and deserialization.
 
 Please be aware that the actual name of the property may be used as a fallback for assignment. See [example 3](#Example-1:-Deserialize-with-actual-name).
 
+## Signatures
+
+You can use the PhpProperty attribute with both a string and an integer argument.
+
+```cs
+[PhpProperty("string")]
+```
+
+```cs
+[PhpProperty(42)]
+```
+
+Indicating that the de/serialization should use the string and integer values as the key for the property respectively.
+
+**Important**:
+Deserialization of objects and arrays with integer keys may yield unexpected results and or exceptions on certain target types. `PhpObjectDictionary` and `PhpDynamicObject` only supports string keys, for example, and will throw an exception.
+
+# Examples
+
 ## Example 1: Serialize
 
 
@@ -34,8 +56,26 @@ var serialized = PhpSerialization.Serialize(
 // a:2:{s:3:"Foo";s:3:"abc";s:3:"Bar";s:3:"xyz";}
 ```
 
+## Example 1: Serialize with integer keys
+
+
+```C#
+public class ExampleClass {
+	[PhpProperty1(0)]
+	public string FirstElement { get; set; }
+	[PhpProperty(1)]
+	public string SecondElement { get; set; }
+}
+
+var serialized = PhpSerialization.Serialize(
+	new ExampleClass(){ FirstElement = "abc", SecondElement = "xyz"}
+);
+// "serialized" will be:
+// a:2:{i:0;s:3:"abc";i:1;s:3:"xyz";}
+```
+
 
-## Example 2: Deserialize with classname
+## Example 3: Deserialize
 
 ```C#
 public class ExampleClass {
@@ -53,21 +93,37 @@ var deserialized = PhpSerialization.Deserialize<ExampleClass>(
 // deserialized.SecondElement == "xyz"
 ```
 
-## Example 3: Deserialization with actual name.
+## Example 4: Deserialization with actual name
 
 ```C#
 public class ExampleClass {
-	[PhpProperty("Foo")]
 	public string FirstElement { get; set; }
-	[PhpProperty("Bar")]
 	public string SecondElement { get; set; }
 }
 
 var deserialized = PhpSerialization.Deserialize<ExampleClass>(
-	"a:2:{s:12:\"FirstElement\";s:13:\"abc\";s:3:\"SecondElement\";s:3:\"xyz\";}"
+	"a:2:{s:12:\"FirstElement\";s:13:\"abc\";s:13:\"SecondElement\";s:3:\"xyz\";}"
 );
 
 // The serialization uses the actual property names, so they will be used for assignment. Hence:
+// deserialized.FirstElement == "abc"
+// deserialized.SecondElement == "xyz"
+```
+
+## Example 5: Deserialize with integer names
+
+```C#
+public class ExampleClass {
+	[PhpProperty(0)]
+	public string FirstElement { get; set; }
+	[PhpProperty(1)]
+	public string SecondElement { get; set; }
+}
+
+var deserialized = PhpSerialization.Deserialize<ExampleClass>(
+	"a:2:{i:0;s:3:\"abc\";i:1;s:3:\"xyz\";}"
+);
+
 // deserialized.FirstElement == "abc"
 // deserialized.SecondElement == "xyz"
 ```

docs/Types/PhpDynamicObject.md

@@ -9,6 +9,10 @@ Implements [`IPhpObject`](./IPhpObject.md).
 
 A dynamic object that can hold any property, used for deserializing object notation while providing a way to access the specified classname.
 
+**Important**:
+
+`PhpObjectDictionary` only supports string keys. You can not deserialize PHP objects with integer keys using this type. This may be addressed in future releases.
+
 ## Methods
 
 ### SetClassName
@@ -45,4 +49,5 @@ myObject.SetClassName("Person");
 
 PhpSerialization.Serialize(myObject);
 // O:6:"Person":2:{s:9:"firstname";s:6:"Joseph";s:8:"lastname";s:6:"Bishop";}
-```
+```
+

docs/Types/PhpObjectDictionary.md

@@ -21,4 +21,8 @@ objectDictionary.SetClassName("Person");
 
 PhpSerialization.Serialize(myObject);
 // O:6:"Person":2:{s:9:"firstname";s:6:"Joseph";s:8:"lastname";s:6:"Bishop";}
-```
+```
+
+**Important**:
+
+`PhpObjectDictionary` only supports string keys. You can not deserialize PHP objects with integer keys using this type. This may be addressed in future releases.