Add format methods

Author: wazabii8

README.md

@@ -1,293 +1,139 @@
+# Darn Tidy Object (DTO)
 
-# MaplePHP - Data Transfer Object (DTO)
+DTO stands for **Darn Tidy Object**, a playful twist on the traditional Data Transfer Object. But this isn’t your average DTO. It’s a fully-loaded toolkit for **traversing, transforming, and tidying up structured data** in PHP with style, power, and simplicity.
 
-The MaplePHP DTO library simplifies working with structured data in PHP by wrapping it into objects. This allows easy traversal and transformation through a chainable interface, ensuring consistent, safe data handling and reducing the risk of direct data manipulation.
 
-- **Encapsulation**: Encapsulates data within objects.
-- **Immutability**: Ensures data integrity by preventing accidental modification.
-- **Validation**: Facilitates data validation, ensuring the data conforms to specific types or formats.
-- **Data Transformation**: Easily modify and format data using built-in methods.
-- **Low Coupling**: Promotes separation of concerns, reducing dependencies between different parts of your code.
-- **Improved Readability**: Makes code cleaner and easier to understand.
-- **Simplified Testing**: DTOs are easier to test, as they contain only data and transformation logic.
+## 📦 Installation
 
----
-
-**Note:** MaplePHP DTO also includes polyfill classes for Multibyte String and Iconv support.
-
-## **1. Creating a DTO Object**
-
-The simplest way to start using **MaplePHP DTO** is with the `Traverse` class:
-
-```php
-use MaplePHP\DTO\Traverse;
-
-$obj = Traverse::value([
-    "firstname" => "<em>daniel</em>",
-    "lastname" => "doe",
-    "price" => "1999.99",
-    "date" => "2023-08-21 14:35:12",
-    "feed" => [
-        "t1" => ["firstname" => "<em>john 1</em>", "lastname" => "doe-1", 'salary' => 40000],
-        "t2" => ["firstname" => "<em>jane 2</em>", "lastname" => "doe-2", 'salary' => 20000]
-    ]
-]);
+```bash
+composer require maplephp/dto
 ```
 
-Now, `$obj` behaves like an object where you can access its properties directly.
+## 📦 Installation
 
----
-
-## **2. Accessing Data**
-
-### **Direct Property Access**
-
-```php
-echo $obj->firstname;
-// Output: <em>daniel</em>
+```bash
+composer require maplephp/dto
 ```
 
-### **Safe Fallback for Missing Values**
+## 📘 Documentation
+- [Why DTO?](http://localhost:3000/docs/intro#why-dto)
+- [Traverse Collection](http://localhost:3000/docs/traverse)
+- [Format string](http://localhost:3000/docs/format-string)
+- [Format Number](http://localhost:3000/docs/format-number)
+- [Format Clock](http://localhost:3000/docs/format-clock)
+- [Format Dom](http://localhost:3000/docs/format-dom)
 
-```php
-echo $obj->feed->t1->doNotExist->fallback('lorem')->strUcFirst();
-// Output: Lorem
-```
 
----
+## How It Works
 
-## **3. Working with Collections**
+DTO wraps your data arrays into a powerful, fluent object structure. Instead of cluttered array access, your code becomes expressive and self-documenting.
 
-### **Iterating Over Arrays**
+### Before DTO
 
 ```php
-foreach ($obj->feed->fetch() as $row) {
-    echo $row->firstname->strStripTags()->strUcFirst();
-}
-// Output:
-// John 1
-// Jane 2
+$name = isset($data['user']['profile']['name'])
+    ? ucfirst(strip_tags($data['user']['profile']['name']))
+    : 'Guest';
 ```
 
-### **Filtering Data (`filter`)**
-
-Filters an array based on a callback function.
+### With DTO
 
 ```php
-$filtered = $obj->feed->filter(fn($row) => $row->salary->get() > 30000);
-echo $filtered->count();
-// Output: 1
+$name = $obj->user->profile->name
+    ->strStripTags()
+    ->strUcFirst()
+    ->fallback('Guest')
+    ->get();
 ```
 
-### **Finding Specific Values**
-
-```php
-echo $obj->shopList->search('cheese');
-// Output: 3
-```
-
-```php
-echo $obj->feed->pluck('lastname')->toArray()[1];
-// Output: doe-2
-```
+Much tidier, right?
 
 ---
 
-## **4. Transforming Collections**
-
-### **Mapping (`map`)**
+## ✨ Core Features
 
-Applies a function to each element.
+### Smart Data Traversal
 
-```php
-$mapped = $obj->shopList->map(fn($item) => strtoupper($item));
-print_r($mapped->toArray());
-```
-**Output:**
-```php
-['SOAP', 'TOOTHBRUSH', 'MILK', 'CHEESE', 'POTATOES', 'BEEF', 'FISH']
-```
-
-### **Reducing (`reduce`)**
-
-Combines values into a single result.
+Access deeply nested data without ever worrying about undefined keys.
 
 ```php
-$sum = $obj->feed->reduce(fn($carry, $item) => $carry + $item->salary->get(), 0);
-echo $sum;
-// Output: 60000
-```
-
-### **Sorting (`reverse`, `shuffle`)**
-
-```php
-echo $obj->shopList->reverse()->eq(0);
-// Output: fish
-```
+echo $obj->article->tagline->strToUpper();  
+// Result: 'HELLO WORLD'
 
-```php
-echo $obj->shopList->shuffle()->eq(0); // Random Output
-```
-
-### **Chunking and Slicing (`chunk`, `slice`, `splice`)**
-
-```php
-echo $obj->shopList->chunk(3)->count();
-// Output: 3
-```
-
-```php
-echo $obj->shopList->slice(1, 2)->count();
-// Output: 2
-```
-
-```php
-$spliced = $obj->shopList->splice(1, 2, ['replaced'])->toArray();
-print_r($spliced);
-```
-**Output:**
-```php
-['soap', 'replaced', 'potatoes', 'beef', 'fish']
+echo $obj->article->content->strExcerpt()->strUcFirst();  
+// Result: 'Lorem ipsum dolor sit amet...'
 ```
 
 ---
 
-## **5. Modifying Collections**
-
-### **Adding and Removing Items**
+### Built-In Data Transformation
 
-```php
-echo $obj->shopList->push('barbie')->count();
-// Output: 8
-```
+Transform values directly using built-in helpers like:
 
-```php
-echo $obj->shopList->pop($value)->count();
-echo $value;
-// Output: fish
-```
+#### Strings (`str`)
 
 ```php
-echo $obj->shopList->shift($value)->count();
-echo $value;
-// Output: soap
+echo $obj->title->strSlug();  
+// Result: 'my-awesome-title'
 ```
 
----
-
-## **6. Advanced Traversal & Recursion**
-
-### **Walking Through Nested Structures (`walk`, `walkRecursive`)**
+#### Numbers (`num`)
 
 ```php
-$value = "";
-$obj->feed->walkRecursive(function ($val) use (&$value) {
-    $value .= strip_tags(str_replace(" ", "", $val));
-});
-echo $value;
-// Output: john1doe-1400001jane2doe-2200002
-```
-
-### **Flattening Data (`flatten`, `flattenWithKeys`)**
+echo $obj->filesize->numToFilesize();  
+// Result: '1.95 kb'
 
-```php
-$flatten = $obj->feed->flatten()->map(fn($row) => $row->strToUpper())->toArray();
+echo $obj->price->numRound(2)->numToCurrency("USD");  
+// Result: $1,999.99
 ```
 
----
-
-## **7. String, Number, and Date Handling**
-
-### **String Manipulations**
+#### Dates (`clock`)
 
 ```php
-echo $obj->firstname->strStripTags()->strUcFirst();
-// Output: Daniel
-```
-
-### **Number Formatting**
+echo $obj->created_at->clockFormat('d M, Y', 'sv_SE');  
+// Result: '21 augusti 2025'
 
-```php
-echo $obj->price->numToFilesize();
-// Output: 1.95 kb
+echo $obj->created_at->clockIsToday();  
+// Result: true
 ```
 
-```php
-echo $obj->price->numRound(2)->numCurrency("SEK", 2);
-// Output: 1 999,99 kr
-```
-
-### **Date Handling**
+#### HTML DOM Builder (`dom`)
 
 ```php
-echo $obj->date->clockFormat("y/m/d, H:i");
-// Output: 23/08/21, 14:35
+echo $obj->heading->domTag("h1.title");  
+// Result: <h1 class="title">My Heading</h1>
 ```
 
+Or nest elements with ease:
+
 ```php
-\MaplePHP\DTO\Format\Clock::setDefaultLanguage('sv_SE');
-echo $obj->date->clockFormat('d M');
-// Output: 21 augusti
+echo $obj->title->domTag("h1.title")->domTag("header");  
+// Result: <header><h1 class="title">Hello</h1></header>
 ```
 
 ---
 
-## **8. Array Utility Methods**
+### Built-In Collection Support
 
-### **Merging and Replacing Arrays**
+Work with arrays of objects just as cleanly:
 
 ```php
-$merged = $obj->shopList->merge(['eggs', 'bread']);
-print_r($merged->toArray());
-```
-**Output:**
-```php
-['soap', 'toothbrush', 'milk', 'cheese', 'potatoes', 'beef', 'fish', 'eggs', 'bread']
+foreach ($obj->users->fetch() as $user) {
+    echo $user->firstName->strUcFirst();
+}
 ```
 
-```php
-$replaced = $obj->shopList->replaceRecursive([0 => 'soap_bar']);
-print_r($replaced->toArray());
-```
-**Output:**
-```php
-['soap_bar', 'toothbrush', 'milk', 'cheese', 'potatoes', 'beef', 'fish']
-```
+---
 
-### **Computing Differences (`diff`, `diffAssoc`, `diffKey`)**
+### Modify Data on the Fly
 
-```php
-$diff = $obj->shopList->diff(['milk', 'cheese']);
-print_r($diff->toArray());
-```
-**Output:**
-```php
-['soap', 'toothbrush', 'potatoes', 'beef', 'fish']
-```
+Change values directly without verbose conditionals:
 
 ```php
-$diffAssoc = $obj->shopList->diffAssoc(['soap', 'toothbrush']);
-print_r($diffAssoc->toArray());
+$updated = $obj->shoppingList->replace([0 => 'Shampoo']);
+print_r($updated->toArray());
 ```
-**Output:**
-```php
-['milk', 'cheese', 'potatoes', 'beef', 'fish']
-```
-
-### **Extracting Keys (`keys`, `pluck`)**
 
-```php
-print_r($obj->shopList->keys()->toArray());
-```
-**Output:**
-```php
-[0, 1, 2, 3, 4, 5, 6]
-```
+---
 
-```php
-print_r($obj->feed->pluck('lastname')->toArray());
-```
-**Output:**
-```php
-['doe-1', 'doe-2']
-```
+Now go forth, write cleaner code, and let DTO handle the messy parts.