readme & collection to string

CHANGELOG.md

@@ -2,6 +2,6 @@
 
 All notable changes to `vCardIO` will be documented in this file.
 
-## [1.0.0] - 2024-XX-XX
+## [1.0.0] - 2024-10-29
 ### Changed
 - Create project first release

README.md

@@ -1,4 +1,4 @@
-# Read & write vCard (vcf) files
+# vCardIO - Read & write vCard (vcf) files
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/pleb/vcardio.svg?style=flat-square)](https://packagist.org/packages/pleb/vcardio)
 [![Tests](https://img.shields.io/github/actions/workflow/status/PierreLebedel/vCardIO/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/PierreLebedel/vCardIO/actions/workflows/run-tests.yml)
@@ -26,38 +26,125 @@ $vCardsCollection = VCardParser::parseFile('./contacts.vcf');
 $vCardsRawData = 'BEGIN:VCARD
 VERSION:4.0
 FN:John Doe
+BDAY:19020202
+X-CUSTOM-VALUE;TYPE=MD:ReadMe
 END:VCARD';
 $vCardsCollection = Pleb\VCardIO\VCardParser::parseRaw($vCardsRawData);
 
 // RESULT:
 
 Pleb\VCardIO\VCardsCollection {
     vCards: [
-        Pleb\VCardIO\VCard {
+        Pleb\VCardIO\Models\VCardV40 {
             version: '4.0'
-            formattedData: {
-                fullName: 'John Doe',
-                // ...
+            fn: [
+                {
+                    value: 'John Doe',
+                    attributes: []
+                }
+            ],
+            bday: {
+                dateTime: DateTime @-2143152000,
+                format: "Ymd",
+                formatted: "190200202",
+                extactYear: true
             },
-            rawData: {
-                fn: 'John Doe',
-                // ...
+            x: [
+                {
+                    name: "custom-value"
+                    value: "ReadMe"
+                    attributes: [
+                        'type' => ['md']
+                    ]
+                }
+            ],
+            ...
+        },
+    ],
+}
+```
+
+#### Support of old school Agent property
+
+The `AGENT` property is not longer supported by the vCard specification, but if you parse old data, you can see something like this, with imbricated vCards:
+
+```txt
+BEGIN:VCARD
+VERSION:3.0
+FN:John Doe
+AGENT:BEGIN:VCARD
+ VERSION:3.0
+ FN:John David
+ END:VCARD
+END:VCARD
+```
+
+This package will parse it as a `VCards`'s `agent` property:
+
+```php
+Pleb\VCardIO\VCardsCollection {
+    vCards: [
+        Pleb\VCardIO\Models\VCardV30 {
+            version: '3.0'
+            fn: [...],
+            agent: Pleb\VCardIO\Models\VCardV30 {
+                version: "3.0"
+                fn: [...],
+                ...
             },
-            invalidData: {},
-            unprocessedData: {},
+            ...
         },
     ],
 }
 ```
 
-### Read data
+### Build vCards
+
+A large set of methods is implemented on the vCard builder to set all the properties fluently.
+
+```php
+$vCard = Pleb\VCardIO\VCardBuilder::make()
+    ->fullname('John Doe')
+    ->birthday(new DateTime('1902-02-02'))
+    ->x('custom-value', 'ReadMe')
+    ->x('other', 'VCF')
+    ->get();
+```
+### Print vCards
+
+You can use `(string) $vCard` to display vCard contents :
 
 ```php
-$vCardsCollection = VCardParser::parseFile('./contacts.vcf');
+echo nl2br((string) $vCard);
+```
+```txt
+BEGIN:VCARD
+VERSION:4.0
+FN:John Doe
+BDAY:19020202
+X-CUSTOM-VALUE:ReadMe
+X-OTHER:VCF
+REV:20241029
+PRODID:-//Pleb//Pleb vCardIO 1.0.0 //EN
+END:VCARD
+```
 
-foreach($vCards as $vCard){
+The same is true for vCards collections :
 
-}
+```php
+$vCardsCollection = VCardParser::parseFile('./contacts.vcf');
+echo nl2br((string) $vCardsCollection);
+```
+```txt
+BEGIN:VCARD
+VERSION:4.0
+FN:John Doe
+END:VCARD
+BEGIN:VCARD
+VERSION:3.0
+FN:John Doed
+END:VCARD
+...
 ```
 
 ## Code formatting

src/VCardBuilder.php

@@ -213,7 +213,7 @@ public function photo(string $photo): self
         return $this;
     }
 
-    public function birthday(DateTimeInterface $bday): self
+    public function bday(DateTimeInterface $bday): self
     {
         $property = $this->getProperty('bday');
         if ($property) {
@@ -223,6 +223,11 @@ public function birthday(DateTimeInterface $bday): self
         return $this;
     }
 
+    public function birthday(DateTimeInterface $bday): self
+    {
+        return $this->bday($bday);
+    }
+
     public function anniversary(DateTimeInterface $anniversary): self
     {
         $property = $this->getProperty('anniversary');

src/VCardsCollection.php

@@ -52,6 +52,15 @@ public function first(): ?AbstractVCard
         return $this->vCards[0] ?? null;
     }
 
+    public function __toString() :string
+    {
+        $collectionString = '';
+        foreach($this->vCards as $vCard){
+            $collectionString .= (string) $vCard;
+        }
+        return $collectionString;
+    }
+
     /**
      * Countable interface implementation
      */