Liberator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require eloquent/liberator
   

   Add to composer.json under require-dev if using for testing.

2. First Use Case:

   use Eloquent\Liberator\Liberator;
   
   $user = new User(); // Assume this is a model with private/protected properties
   $liberator = new Liberator($user);
   
   // Access private property
   $email = $liberator->get('email');
   // Set private property
   $liberator->set('email', '[email protected]');
   

3. Where to Look First:

   • Liberator Class Docs (if available)
   • src/Liberator.php for core functionality
   • tests/ for edge-case examples

Implementation Patterns

Common Workflows

1. Testing Private/Protected Logic:

   public function testPrivateMethod()
   {
       $user = new User();
       $liberator = new Liberator($user);
   
       // Test private method
       $result = $liberator->call('calculateBonus', [100]);
       $this->assertEquals(10, $result);
   }
   

2. Mocking in Unit Tests:

   $liberator = new Liberator($this->getMockBuilder(User::class)->getMock());
   $liberator->set('isAdmin', true);
   

3. Dynamic Property Access:

   // Bypass visibility for dynamic properties
   $liberator->set('dynamicProp', 'value');
   

Integration Tips

• Use in createApplication() (Laravel):

  $app->singleton(Liberator::class, function ($app) {
      return new Liberator($app->make(User::class));
  });
  

• Combine with Reflection:

  $reflection = new \ReflectionClass($user);
  $property = $reflection->getProperty('privateField');
  $property->setAccessible(true);
  $liberator->set($property->getName(), 'value');
  

• Leverage in Factories:

  $factory = new Liberator(new User());
  $factory->set('password', Hash::make('secret'));
  

Gotchas and Tips

Pitfalls

1. Security Risks:

   • Avoid using in production code. Liberator bypasses visibility intentionally, which can expose sensitive logic.
   • Tip: Restrict usage to tests or debug environments via config:

     if (!app()->environment('testing')) {
         throw new \RuntimeException('Liberator not allowed in production.');
     }
     

2. Performance Overhead:

   • Reflection-based access is slower than direct property access.
   • Tip: Cache Liberator instances for repeated use:

     static $cachedLiberator = null;
     if (!$cachedLiberator) {
         $cachedLiberator = new Liberator($user);
     }
     

3. Static Properties:

   • Liberator does not handle static properties by default.
   • Workaround:

     $liberator->callStatic('setStaticValue', ['key', 'value']);
     

4. Magic Methods:

   • May interfere with __get(), __set(), or __call() in the target class.
   • Tip: Test thoroughly if the target class uses magic methods.

Debugging Tips

• Verify Property/Method Existence:

  if (!$liberator->has('nonExistentMethod')) {
      throw new \InvalidArgumentException('Method does not exist.');
  }
  

• Check Visibility:

  $liberator->getVisibility('privateField'); // Returns 'private', 'protected', or 'public'
  

• Log Access:

  $liberator->setDebug(true);
  // Logs all access attempts to storage/logs/liberator.log
  

Extension Points

1. Custom Access Control:

   $liberator = new Liberator($user, [
       'allowedProperties' => ['email', 'name'],
       'allowedMethods' => ['getEmail', 'setName']
   ]);
   

2. Event Hooks:

   $liberator->onAccess(function ($property, $value) {
       // Log or validate before access
   });
   

3. Proxy Classes:
   • Extend Liberator to add domain-specific logic:

     class UserLiberator extends Liberator {
         public function hashPassword($password) {
             return $this->call('hashPassword', [$password]);
         }
     }