Builder Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nayjest/builder
   

   No service provider or facade needed—just autoload the Nayjest\Builder\Builder class.

2. First Use Case: Build a simple configuration array or object:

   use Nayjest\Builder\Builder;
   
   $config = (new Builder())
       ->set('database', 'mysql')
       ->set('host', 'localhost')
       ->set('port', 3306)
       ->get();
   // Returns: ['database' => 'mysql', 'host' => 'localhost', 'port' => 3306]
   

3. Where to Look First:

   • Source Code (minimal, ~100 lines).
   • Focus on Builder::set(), Builder::get(), and method chaining.

Implementation Patterns

Core Workflows

1. Fluent Configuration Composition:

   $user = (new Builder())
       ->set('name', 'John Doe')
       ->set('roles', ['admin', 'user'])
       ->set('active', true)
       ->get();
   

2. Nested Structures:

   $apiConfig = (new Builder())
       ->set('base_uri', 'https://api.example.com')
       ->set('headers', (new Builder())
           ->set('Accept', 'application/json')
           ->set('Authorization', 'Bearer token')
           ->get()
       )
       ->get();
   

3. Laravel Integration:

   • Service Container Binding:

     $this->app->bind('config.builder', function () {
         return new Builder();
     });
     

   • Dynamic Configuration:

     $settings = app('config.builder')
         ->set('theme', request('theme', 'default'))
         ->set('locale', app()->getLocale())
         ->get();
     

4. Object Construction:

   class User {
       public $name;
       public $email;
   }
   
   $user = (new Builder())
       ->setObject(new User())
       ->set('name', 'Jane Smith')
       ->set('email', '[email protected]')
       ->getObject();
   

5. Reusable Builders:

   class UserBuilder extends Builder {
       public function withDefaultRoles() {
           return $this->set('roles', ['user']);
       }
   }
   
   $admin = (new UserBuilder())
       ->withDefaultRoles()
       ->set('roles', ['admin'])
       ->get();
   

Gotchas and Tips

Pitfalls

1. Immutable State:

   • Builder::get() returns a copy of the internal array. Modify the result without affecting the builder:

     $data = (new Builder())->set('key', 'value')->get();
     $data['key'] = 'new_value'; // Original builder remains unchanged.
     

2. Object Mutation:

   • setObject() modifies the passed object by reference. Avoid unexpected side effects:

     $user = new User();
     (new Builder())->setObject($user)->set('name', 'Alice');
     // $user->name is now 'Alice' (modified in-place).
     

3. No Deep Cloning:

   • Nested builders (e.g., set('headers', (new Builder())->...)) are not deeply cloned on get(). Use clone explicitly if needed.

4. Last Release Age:

   • Last updated in 2016. Test thoroughly for edge cases (e.g., PHP 8.x compatibility). Fork if critical bugs arise.

Debugging Tips

1. Inspect State:

   $builder = (new Builder())->set('key', 'value');
   var_dump($builder->getInternal()); // Debug raw state.
   

2. Method Chaining Validation:

   • Ensure all methods return $this for fluent chaining. Override if extending:

     class CustomBuilder extends Builder {
         public function customMethod() {
             $this->set('custom', true);
             return $this; // Critical for chaining!
         }
     }
     

Extension Points

1. Custom Setters:

   class QueryBuilder extends Builder {
       public function where($field, $value) {
           $this->set("where.$field", $value);
           return $this;
       }
   }
   
   $query = (new QueryBuilder())
       ->where('status', 'active')
       ->get();
   // Returns: ['where.status' => 'active']
   

2. Validation Hooks:

   class ValidatedBuilder extends Builder {
       public function get() {
           if (!$this->has('required_field')) {
               throw new \RuntimeException('Missing required field!');
           }
           return parent::get();
       }
   }
   

3. Laravel Service Provider Integration:

   $this->app->extend('config.builder', function ($builder) {
       $builder->set('app.env', env('APP_ENV'));
       return $builder;
   });
   

Performance Notes

• Avoid Overuse: For simple key-value pairs, native arrays may suffice.
• Memory: Deeply nested builders can increase memory usage. Flatten structures where possible.