Propel Boolean Extra Behavior Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add the package via Composer:

   composer require havvg/propel-boolean-extra-behavior
   

   Ensure Propel is properly installed in your Laravel project (e.g., via spatie/laravel-propeller or direct Propel integration).

2. Register the Behavior Add the behavior to your schema.xml for the relevant table(s):

   <table name="users">
       <column name="is_active" type="boolean" />
       <behavior name="boolean_extra" />
   </table>
   

3. First Use Case Access the generated methods in your model:

   $user = UserQuery::findOne(1);
   // Instead of:
   if ($user->getIsActive()) { ... }
   // Use:
   if ($user->isActive()) { ... }
   // Or for setting:
   $user->setActive(true); // Instead of $user->setIsActive(true)
   

Implementation Patterns

Workflows

1. Consistent Naming in Models Replace Propel’s default getIsX()/setIsX() with natural language methods:

   // Before
   if ($user->getIsActive()) { ... }
   $user->setIsActive(true);
   
   // After
   if ($user->isActive()) { ... }
   $user->setActive(true);
   

2. Integration with Laravel Eloquent (if using Propel alongside) If your project mixes Propel and Eloquent, create accessors in Eloquent models to mirror the behavior:

   // User.php (Eloquent)
   public function getIsActiveAttribute($value) {
       return $this->getIsActive(); // Delegate to Propel
   }
   

3. Dynamic Method Generation The behavior auto-generates methods for all boolean columns in the table. No manual mapping required.

Best Practices

• Use in Forms/Validation Leverage the readable methods in Form Requests or Form classes (e.g., Laravel Collective):

  $request->validate([
      'active' => 'required|boolean', // Maps to `is_active` column
  ]);
  

• API Responses Serialize boolean fields using the natural methods in API resources:

  public function toArray($request) {
      return [
          'active' => $this->isActive(), // Cleaner than `getIsActive()`
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Schema XML Must Be Updated Forgetting to add <behavior name="boolean_extra" /> to schema.xml means no methods are generated. Always rebuild Propel after adding the behavior:

   php vendor/bin/propel-build schema
   

2. Method Naming Collisions If your model already has methods like isActive(), Propel’s generated methods will overwrite them. Avoid naming conflicts by:

   • Prefixing Propel-generated methods (e.g., _isActive()).
   • Using Propel’s default getIsActive()/setIsActive() if readability isn’t critical.

3. Case Sensitivity in XML The behavior tag is case-sensitive. Use <behavior name="boolean_extra" /> exactly as shown.

Debugging

• Methods Not Generated? Verify the behavior is loaded by checking Propel’s behavior registry or running:

  php vendor/bin/propel-build model
  

  Then inspect the generated User.php for new methods.

• Boolean Values in Database Ensure your database column is strictly boolean (e.g., TINYINT(1) in MySQL). The behavior assumes true/false values.

Extension Points

1. Custom Method Names The package doesn’t support customizing method names (e.g., isEnabled() instead of isActive()). Workaround:

   • Use Propel’s postInsert/postUpdate to alias methods:

     public function postInsert(ConnectionInterface $con = null) {
         $this->setActive($this->getIsActive());
     }
     

2. Non-Standard Boolean Columns If your boolean column uses a non-standard name (e.g., flag), the behavior will generate isFlag()/setFlag(). No configuration is needed.

3. Testing Test boolean logic in PHPUnit by directly calling the generated methods:

   $user = new User();
   $user->setActive(true);
   $this->assertTrue($user->isActive());