omaralalwi/php-builders

sample php traits to add ability to use builder design patterns with easy in PHP applications

1.0.1 2025-01-16 23:02 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

• omar alalwi

• php
• traits
• builders
• fluent-interface
• design-patterns
• builder-pattern
• omaralalwi
• php-builders
• php-patterns
• object-creation

README

PHP Builders is a lightweight PHP library designed to simplify the implementation of the Builder design pattern in PHP applications.

Table of Contents

• Installation
• Usage
  • By Extending Fluentbuilder in Builder Class
  • By Include Traits in Builder Class
  • Cast Builder Class
    • Return as Array
    • Return as Object
    • Return as JSON
• Custom Execution Logic
• Contributing
• Security
• License

Installation

Install the package via Composer using the following command:

composer require omaralalwi/php-builders

Usage

Note: if you not use any PHP frameworks like (symfony,laravel,codeigniter,Yii,cakePHP..etc), you should add this line:

require_once __DIR__ . '/vendor/autoload.php';

First Way

By Extending FluentBuilder in Builder Class

The FluentBuilder class integrates all available traits, enabling you to utilize all package features by simply extending this class.

namespace App\Builders;

use Omaralalwi\PhpBuilders\FluentBuilder;

class UserBuilder extends FluentBuilder
{
    protected string $name;
    protected string $email;

    public function setName(string $name): self
    {
        $this->name = $name;
        return $this;
    }

    public function setEmail(string $email): self
    {
        $this->email = $email;
        return $this;
    }

    public function sendEmail(): self
    {
        // Logic for sending an email
        return $this;
    }
}

second Way

By Include Traits

simplify you can achieve same result by include Buildable, Arrayable, Objectable, Jsonable traits directly in builder class, without extending the FluentBuilder class.

namespace App\Builders;

use Omaralalwi\PhpBuilders\Traits\{Buildable, Arrayable, Objectable, Jsonable};
use App\Models\User;

class UserBuilder
{
   use Buildable,
        Arrayable,
        Objectable,
        Jsonable;
        
        // same code in first way example
}

cast Builder Class

use UserBuilder as following:

$user = UserBuilder::build()
    ->setName('PHP Builders')
    ->setEmail('[e-mail]')
    ->sendEmail();

then cast it to needed type as following:

Return as Array

Convert the built instance to an array using the toArray() method:

$userAsArray = $user->toArray();
print_r($userAsArray);
/*
Output:
Array
(
    [name] => PHP Builders
    [email] => [e-mail]
)
*/

Return as Object

Convert the built instance to an object using the toObject() method:

$userAsObject = $user->toObject();
print_r($userAsObject);
/*
Output:
stdClass Object
(
    [name] => PHP Builders
    [email] => [e-mail]
)
*/

Return as JSON

Convert the built instance to JSON using the toJson() method:

$userAsJson = $user->toJson();
echo $userAsJson;
/*
Output:
{"name":"PHP Builders","email":"[e-mail]"}
*/

Custom Execution Logic

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,
        ]);
    }
}

$createdUser = UserBuilder::build()
    ->setName('PHP Builders')
    ->setEmail('[e-mail]')
    ->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! To propose improvements or report issues, please open an issue or submit a pull request on the GitHub repository.

Security

If you discover any security-related issues, please email the author at: [e-mail].

License

This project is open-source and licensed under the MIT License.