Merge pull request #1 from omaralalwi/feat/ability-to-return-json

Feat / add ability to json cast

Author: omaralalwi

README.md

@@ -3,31 +3,50 @@
 [![Latest Version](https://img.shields.io/github/release/omaralalwi/php-builders.svg?style=flat-square)](https://github.com/omaralalwi/php-builders/releases)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
 
-**PHP Builders** is a sample PHP library that provides traits to implement the Builder design pattern easily in PHP applications. It allows developers to create builder classes that can construct complex objects in a fluent and readable manner.
+**PHP Builders** is a lightweight PHP library designed to simplify the implementation of the Builder design pattern in PHP applications. 
+
+---
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Creating a Builder Class](#creating-a-builder-class)
-  - [Using the Builder](#using-the-builder)
+  - [By Extending `Fluentbuilder` in Builder Class](#by-extending-fluentbuilder-in-builder-class)
+  - [By Include Traits in Builder Class](#by-include-traits)
+  - [Cast Builder Class](#cast-builder-class)
+    - [Return as Array](#return-as-array)
+    - [Return as Object](#return-as-object)
+    - [Return as JSON](#return-as-json)
+- [Custom Execution Logic](#custom-execution-logic)
 - [Contributing](#contributing)
 - [Security](#security)
 - [License](#license)
 
+---
+
 ## Installation
 
-You can install the package via Composer. Run the following command in your terminal:
+Install the package via Composer using the following command:
 
 ```bash
 composer require omaralalwi/php-builders
 ```
 
+---
+
 ## Usage
 
-### Creating a Builder Class
+**Note**: if you not use any PHP frameworks like (symfony,laravel,codeigniter,Yii,cakePHP..etc), you should add this line:
+
+```php
+require_once __DIR__ . '/vendor/autoload.php';
+```
+
+**First Way**
+
+### By Extending FluentBuilder in Builder Class
 
-To create a builder class, extend the `FluentBuilder` class and define your properties and methods.
+The `FluentBuilder` class integrates all available traits, enabling you to utilize all package features by simply extending this class.
 
 ```php
 namespace App\Builders;
@@ -38,7 +57,7 @@ class UserBuilder extends FluentBuilder
 {
     protected string $name;
     protected string $email;
-    
+
     public function setName(string $name): self
     {
         $this->name = $name;
@@ -50,58 +69,154 @@ class UserBuilder extends FluentBuilder
         $this->email = $email;
         return $this;
     }
-    
+
     public function sendEmail(): self
     {
-       // handle send email to user or make any action
-       // then return instance of self
-       return $this;
+        // Logic for sending an email
+        return $this;
     }
-    
-    // add any another functions then call them as you need
 }
 ```
 
-### Using the Builder
+**second Way**
 
-You can convert the built instance to an array or an object using the `toArray()` and `toObject()` methods.
+### By Include Traits
 
-#### Return Array
+simplify you can achieve same result by include `Buildable`, `Arrayable`, `Objectable`, `Jsonable` traits directly in builder class, without extending the `FluentBuilder` class.
 
 ```php
-$userArray = UserBuilder::build()
-    ->setName('PHP Builders')
-    ->setEmail('[email protected]')
-    ->sendEmail()
-    ->toArray();
+namespace App\Builders;
+
+use Omaralalwi\PhpBuilders\Traits\{Buildable, Arrayable, Objectable, Jsonable};
+use App\Models\User;
 
-getType($userArray) // Array
-$userArray['name'] // PHP Builders
-$userArray['email'] // [email protected]
+class UserBuilder
+{
+   use Buildable,
+        Arrayable,
+        Objectable,
+        Jsonable;
+        
+        // same code in first way example
+}
 ```
 
-#### Return Object
+### cast Builder Class
+
+use `UserBuilder` as following:
 
 ```php
-$userObject = UserBuilder::build()
+$user = UserBuilder::build()
     ->setName('PHP Builders')
-    ->setEmail('[email protected]')
-    ->sendEmail()
-    ->toObject();
+    ->setEmail('[email protected]')
+    ->sendEmail();
+```
+then cast it to needed type as following:
+
+**Return as Array**
+
+Convert the built instance to an array using the `toArray()` method:
+
+```php
+$userAsArray = $user->toArray();
+print_r($userAsArray);
+/*
+Output:
+Array
+(
+    [name] => PHP Builders
+    [email] => [email protected]
+)
+*/
+```
+
+**Return as Object**
 
-getType($userArray) // object
-$userArray->name // PHP Builders
-$userArray->email // [email protected]
+Convert the built instance to an object using the `toObject()` method:
+
+```php
+$userAsObject = $user->toObject();
+print_r($userAsObject);
+/*
+Output:
+stdClass Object
+(
+    [name] => PHP Builders
+    [email] => [email protected]
+)
+*/
 ```
 
+**Return as JSON**
+
+Convert the built instance to JSON using the `toJson()` method:
+
+```php
+$userAsJson = $user->toJson();
+echo $userAsJson;
+/*
+Output:
+{"name":"PHP Builders","email":"[email protected]"}
+*/
+```
+
+---
+
+#### Custom Execution Logic
+
+```php
+namespace App\Builders;
+
+use Omaralalwi\PhpBuilders\FluentBuilder;
+use App\Models\User;
+
+class UserBuilder extends FluentBuilder
+{
+   // same code in previous example, just we added execute method .
+   
+    public function execute(): User
+    {
+        // Pre-store logic (e.g., validation, preprocessing)
+        return $this->store();
+    }
+
+    protected function store(): User
+    {
+        return User::create([
+            'name' => $this->name,
+            'email' => $this->email,
+        ]);
+    }
+}
+```
+
+```php
+$createdUser = UserBuilder::build()
+    ->setName('PHP Builders')
+    ->setEmail('[email protected]')
+    ->execute();
+/*
+$createdUser is an instance of the User model.
+*/
+```
+
+> **Note:** Traits like `Arrayable`, `Objectable`, and `Jsonable` can also be included in your builder class as needed if you choose not to extend `FluentBuilder`.
+
+---
+
 ## Contributing
 
-Contributions are welcome! If you have suggestions for improvements or new features, feel free to open an issue or submit a pull request on the [GitHub repository](https://github.com/omaralalwi/php-builders).
+Contributions are welcome! To propose improvements or report issues, please open an issue or submit a pull request on the [GitHub repository](https://github.com/omaralalwi/php-builders).
+
+---
 
 ## Security
 
-If you discover any security-related issues, please email creator : `[email protected]`.
+If you discover any security-related issues, please email the author at: `[email protected]`.
+
+---
 
 ## License
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+This project is open-source and licensed under the [MIT License](LICENSE).
+

composer.json

@@ -18,7 +18,7 @@
     "homepage": "https://github.com/omaralalwi/php-builders",
     "license": "MIT",
     "type": "library",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "authors": [
         {
             "name": "omar alalwi",

src/FluentBuilder.php

@@ -2,9 +2,12 @@
 
 namespace Omaralalwi\PhpBuilders;
 
-use Omaralalwi\PhpBuilders\Traits\{Buildable, Arrayable, Objectable};
+use Omaralalwi\PhpBuilders\Traits\{Buildable, Arrayable, Objectable, Jsonable};
 
 class FluentBuilder
 {
-    use Buildable, Arrayable, Objectable;
+    use Buildable,
+        Arrayable,
+        Objectable,
+        Jsonable;
 }

src/Traits/Jsonable.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Omaralalwi\PhpBuilders\Traits;
+
+trait Jsonable
+{
+    public function toJson(): string
+    {
+        $properties = [];
+        $reflection = new \ReflectionClass($this);
+        foreach ($reflection->getProperties() as $property) {
+            $property->setAccessible(true);
+            $properties[$property->getName()] = $property->getValue($this);
+        }
+        return json_encode($properties);
+    }
+}