add documentation pages

.gitignore

@@ -29,5 +29,5 @@ phpunit.xml
 phpstan.neon
 psalm.xml
 testbench.yaml
-/docs
+#/docs
 /coverage

README.md

@@ -9,15 +9,22 @@ It allows you to build vCard objects & export them to text or .vcf files.
 
 ## Installation
 
-You can install the package via composer:
+Via composer:
 
 ```bash
 composer require pleb/vcardio
 ```
 
+## Documentation
+
+- [Parsing data](docs/parsing.md)
+- [vCards collection](docs/collection.md)
+- [vCard builder](docs/builder.md)
+- [vCard object](docs/vcard.md)
+
 ## Usage
 
-### Parse vCards
+### Parsing data
 
 You can parse vCards objects from .vcf file or from raw data, and obtain an iterable collection of vCards.
 
@@ -34,9 +41,13 @@ X-MAIN-HOBBY:Bowling
 END:VCARD';
 
 $vCardsCollection = Pleb\VCardIO\VCardParser::parseRaw($vCardsRawData);
+```
 
-// RESULT:
+### The vCards collection
 
+The result of parsing is a collection of vCards:
+
+```php
 Pleb\VCardIO\VCardsCollection {
     vCards: [
         Pleb\VCardIO\Models\VCardV40 {
@@ -76,7 +87,21 @@ Pleb\VCardIO\VCardsCollection {
 }
 ```
 
-You can retreive single vCard objects by iterating on VCardsCollection, or by getting them by index:
+#### Manually build a vCards collection
+
+```php
+$vCardsCollection = (new Pleb\VCardIO\VCardsCollection())
+    ->addVCard($vCard1)
+    ->addVCard($vCard2);
+
+// OR
+
+$vCardsCollection = new Pleb\VCardIO\VCardsCollection([$vCard1, $vCard2]);
+```
+
+#### Manipulate collection
+
+The `VCardsCollection` object implements `ArrayAccess`, `Iterator` and `Countable` interfaces, so you can loop on it.
 
 ```php
 foreach($vCardsCollection as $vCard){
@@ -88,9 +113,32 @@ $vCard = $vCardsCollection->first();
 $vCard = $vCardsCollection->getVCard(0); // 1,2,...
 ```
 
-#### Support of old school Agent property
+### The vCard object
+
+A huge set of methods is implemented to read the vCard properties. You can see all available getters methods [on the vCard object documentation](docs/vcard.md).
+
+```php
+$vCard->getFullName();                      // :?string
+$vCard->getLastName();                      // :?string
+$vCard->getFirstName();                     // :?string
+$vCard->getEmails();                        // :array<string>
+$vCard->getPhones();                        // :array<string>
+$vCard->getX('main-hobby', multiple:false); // :?string|array
+$vCard->getX('main-hobby', multiple:true);  // :array
+// ...
+```
+
+#### Note on "Pseudo-singular" properties 
 
-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:
+[RFC 6350](https://datatracker.ietf.org/doc/html/rfc6350) allows most of properties to be present multiple times in a vCard. For example the `FN` (fullName) property can be present 1 or multiple times, and accompagnied by attributes to distinct them.
+
+In this package, we assume that some of properties (like fullName) got a **unique main value**. The vCard's *`getProperty()`* methods will return this main value, as well as the sub-object `$vCard->relevantData`.
+
+The complete set of value is stil available in the root of `$vCard` object.
+
+#### Note on the 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 nested vCards:
 
 ```txt
 BEGIN:VCARD
@@ -108,43 +156,23 @@ This package will parse it as a VCard's `agent` property:
 ```php
 Pleb\VCardIO\Models\VCardV30 {
     version: '3.0'
-    fn: [...],
+    // ...,
     agent: Pleb\VCardIO\Models\VCardV30 {
         version: "3.0"
-        fn: [...],
-        ...
+        // ...
     },
-    ...
+    // ...
 }
 ```
 
-### Read vCard object
-
-A huge set of methods is implemented to read the vCard properties.
-
-```php
-$vCard->getFullName();      // :string
-$vCard->getLastName();      // :string
-$vCard->getFirstName();     // :string
-$vCard->getEmails();        // :array<string>
-$vCard->getPhones();        // :array<string>
-$vCard->getX('main-hobby'); // :string|array
-// ...
-```
-
-> [!NOTE]
-> **"Pseudo-singular" properties:** [RFC 6350](https://datatracker.ietf.org/doc/html/rfc6350) allows most of properties to be present multiple times in a vCard. For example the `FN` (fullName) property can be present 1 or multiple times, and accompagnied by attributes to distinct them.
-> In this package, we assume that some of properties (like fullName) got a **unique main value**. The vCard's *`getProperty()`* methods will return this main value, as well as the sub-object `$vCard->relevantData`.
-> The complete set of value is stil available in the root of `$vCard` object.
-
-### Build vCard
+### The vCard builder
 
-You can create your vCard objects from scratch fluently by using the large set of methods implemented on the vCard builder.
+You can create your vCard objects from scratch fluently by using the large set of methods implemented on the vCard builder. You can see all available setters methods [on the vCard builder documentation](docs/builder.md).
 
 ```php
 $vCard = Pleb\VCardIO\VCardBuilder::make()
     ->fullName('Jeffrey Lebowski')
-    ->nickname('The Dude')
+    ->nickName('The Dude')
     ->birthday(new DateTime('1942-12-04'))
     ->x('main-hobby', 'Bowling')
     ->get();
@@ -154,19 +182,9 @@ Each method returns the builder instance, so you can chain them.
 
 Use the `get()` method to get your vCard.
 
-#### Build vCards collection
-
-```php
-$vCardsCollection = (new VCardsCollection())
-    ->addVCard($vCard1)
-    ->addVCard($vCard2);
-
-// OR
-
-$vCardsCollection = new VCardsCollection([$vCard1, $vCard2]);
-```
+### Print vCards
 
-### Print vCard
+#### Print a single vCard
 
 You can use `(string) $vCard` to display vCard contents:
 

composer.json

@@ -1,16 +1,17 @@
 {
     "name": "pleb/vcardio",
-    "description": "Parse & write vCard (vcf) files",
+    "description": "Parse vCards from files (.vcf) or raw data. Build vCards from scratch. Export vCards as string or file.",
     "keywords": [
         "vcard",
         "vcf"
     ],
-    "homepage": "https://github.com/pleb/vcardio",
+    "homepage": "https://github.com/PierreLebedel/vCardIO",
     "license": "MIT",
     "authors": [
         {
             "name": "Pierre Lebedel",
             "email": "[email protected]",
+            "homepage": "https://www.pierrelebedel.fr",
             "role": "Developer"
         }
     ],
@@ -45,6 +46,6 @@
             "phpstan/extension-installer": true
         }
     },
-    "minimum-stability": "dev",
+    "minimum-stability": "stable",
     "prefer-stable": true
 }

docs/agent.md

@@ -0,0 +1,35 @@
+[Documentation homepage](index.md)
+
+# vCard's `AGENT` property
+
+The old school `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:Jeffrey Lebowski
+AGENT:BEGIN:VCARD
+ VERSION:3.0
+ FN:Walter Sobchak
+ END:VCARD
+END:VCARD
+```
+
+This package will parse it as a VCard's `agent` property:
+
+```php
+Pleb\VCardIO\Models\VCardV30 {
+    version: '3.0'
+    fn: [...],
+    agent: Pleb\VCardIO\Models\VCardV30 {
+        version: "3.0"
+        fn: [...],
+        ...
+    },
+    ...
+}
+```
+
+## The vCard object
+
+View the [vCard object documentation](vcard.md).

docs/builder.md

@@ -0,0 +1,149 @@
+[Documentation homepage](index.md)
+
+# Builder
+
+## Build a vCard
+
+Each `VCardBuilder` setter returns the builder instance so you can chain them.
+
+```php
+$vCard = Pleb\VCardIO\VCardBuilder::make()
+    ->fullName('Jeffrey Lebowski')
+    ->nickName('The Dude')
+    ->birthday(new DateTime('1942-12-04'))
+    ->x('main-hobby', 'Bowling')
+    ->get();
+```
+
+## Available setters
+
+<!--
+Method | Params | Description
+--- | --- | ---
+`version` | `string\|VCardVersionEnum` | Set the vCard version.
+`agent` | `string\|AbstractVCard` | Set the agent.
+`fullName` | `string` | Set the full name.
+-->
+
+```php
+$vCardBuilder->version(string|VCardVersionEnum $version);
+
+$vCardBuilder->agent(string|AbstractVCard $agent);
+
+$vCardBuilder->fullName(?string $fullName);
+
+$vCardBuilder->name(
+    ?string $lastName = null,
+    ?string $firstName = null,
+    ?string $middleName = null,
+    ?string $namePrefix = null,
+    ?string $nameSuffix = null
+);
+
+$vCardBuilder->lastName(string $lastName);
+
+$vCardBuilder->firstName(string $firstName);
+
+$vCardBuilder->middleName(string $middleName);
+
+$vCardBuilder->namePrefix(string $namePrefix);
+
+$vCardBuilder->nameSuffix(string $nameSuffix);
+
+$vCardBuilder->email(string $email, array $types = []);
+
+$vCardBuilder->phone(string $number, array $types = ['voice']);
+
+$vCardBuilder->url(string $url);
+
+$vCardBuilder->photo(string $photo);
+
+$vCardBuilder->bday(DateTimeInterface $bday);
+$vCardBuilder->birthday(DateTimeInterface $bday);
+
+$vCardBuilder->anniversary(DateTimeInterface $anniversary);
+
+$vCardBuilder->kind(string $kind);
+
+$vCardBuilder->gender(string $gender);
+
+$vCardBuilder->organization(string $company, ?string $unit1, ?string $unit2);
+
+$vCardBuilder->title(string $title);
+
+$vCardBuilder->role(string $role);
+
+$vCardBuilder->member(string $uid);
+
+$vCardBuilder->address(
+    ?string $postOfficeAddress,
+    ?string $extendedAddress,
+    ?string $street,
+    ?string $locality,
+    ?string $region,
+    ?string $postalCode,
+    ?string $country,
+    array $types = []
+);
+
+$vCardBuilder->geo(float $latitude, float $longitude);
+
+$vCardBuilder->categories(array $categories);
+
+$vCardBuilder->category(string $category);
+
+$vCardBuilder->nickNames(array $nickNames);
+
+$vCardBuilder->nickName(string $nickName);
+
+$vCardBuilder->timeZone(DateTimeZone $timeZone);
+
+$vCardBuilder->uid(string $uid);
+$vCardBuilder->uuid(string $uuid);
+
+$vCardBuilder->calendarAddressUri(string $uri);
+
+$vCardBuilder->calendarUri(string $uri);
+
+$vCardBuilder->clientPidMap(int $pid, string $uri);
+
+$vCardBuilder->fbUrl(string $url);
+
+$vCardBuilder->impp(string $number, array $types = []);
+
+$vCardBuilder->key(string $key);
+
+$vCardBuilder->lang(string $lang, int $pref = 1);
+
+$vCardBuilder->langs(array $langs);
+
+$vCardBuilder->logo(string $logo);
+
+$vCardBuilder->note(string $note);
+
+$vCardBuilder->prodid(string $prodid);
+
+$vCardBuilder->related(string $related);
+
+$vCardBuilder->rev(DateTimeInterface $dateTime);
+$vCardBuilder->revision(DateTimeInterface $dateTime);
+
+$vCardBuilder->sound(string $sound);
+
+$vCardBuilder->source(string $source);
+
+$vCardBuilder->xml(string $xml);
+
+$vCardBuilder->x(string $name, string $value);
+
+```
+
+## Get the vCard object
+
+```php
+$vCard = Pleb\VCardIO\VCardBuilder::make()
+    // ...
+    ->get();
+```
+
+View the [vCard object documentation](vcard.md) for more information.