Laravel Cycle Orm Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wayofdev/laravel-cycle-orm-adapter
   

   Publish the config:

   php artisan vendor:publish --provider="WayOfDev\Cycle\Bridge\Laravel\CycleServiceProvider" --tag="config"
   

2. Configure Database: Update .env with your database credentials and run:

   php artisan cycle:migrate
   

3. First Use Case: Define a Cycle entity (e.g., app/Entities/User.php):

   namespace App\Entities;
   
   use Cycle\Annotated\Annotation\Column;
   use Cycle\Annotated\Annotation\Entity;
   
   #[Entity]
   class User
   {
       #[Column(type: 'primary')]
       public int $id;
   
       #[Column(type: 'string')]
       public string $name;
   }
   

   Use it in a controller:

   use App\Entities\User;
   use Cycle\ORM\Select;
   
   public function index()
   {
       $users = app(Select::class)->from(User::class)->fetchAll();
       return response()->json($users);
   }
   

Implementation Patterns

Core Workflows

1. Entity Management:

   • Use Cycle\ORM\Select for queries (replaces Eloquent’s Model::query()):

     $users = app(Select::class)->from(User::class)->where('name', 'John')->fetchAll();
     

   • Persist entities via Cycle\ORM\Repository:

     $repository = app(\Cycle\ORM\Repository::class);
     $repository->persist($user);
     $repository->run();
     

2. Validation Integration: Leverage Unique/Exists rules in Form Requests:

   use WayOfDev\Cycle\Bridge\Laravel\Rules\{Unique, Exists};
   
   public function rules(): array
   {
       return [
           'email' => [
               'required',
               new Unique($this->database, 'users', 'email')
           ],
           'role_id' => [
               'required',
               new Exists($this->database, 'roles', 'id')
           ]
       ];
   }
   

3. Testing:

   • Use PostFactory::new()->create() for test data.
   • Replace InteractsWithDatabase with WayOfDev\Cycle\Testing\Concerns\InteractsWithDatabase for assertions:

     $this->assertDatabaseHas('users', ['email' => 'test@example.com']);
     

4. Migrations: Use Cycle’s schema builder (via cycle:migrate):

   use Cycle\Migrations\Migration;
   
   class CreateUsersTable extends Migration
   {
       public function up(): void
       {
           $this->table('users')->column('name', 'string')->create();
       }
   }
   

Integration Tips

• Service Providers: Bind repositories/managers in CycleServiceProvider:

  $this->app->bind(\Cycle\ORM\Repository::class, function ($app) {
      return $app->make(\Cycle\ORM\Repository::class);
  });
  

• Query Scopes: Define reusable scopes in entities:

  #[Entity]
  class User
  {
      public static function active(): Select
      {
          return Select::from(self::class)->where('is_active', true);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Transaction Handling:

   • Cycle uses its own transaction manager. Avoid mixing with Laravel’s DB::transaction():

     // ❌ Avoid
     DB::transaction(fn() => $repository->run());
     
     // ✅ Use Cycle’s transaction
     $repository->runInTransaction(fn() => $repository->persist($user));
     

2. Soft Deletes:

   • Cycle’s soft deletes require explicit handling:

     $user->deletedAt = now();
     $repository->persist($user);
     

   • Use assertSoftDeleted in tests (requires WayOfDev\Cycle\Testing\Concerns\InteractsWithDatabase).

3. Factory Conflicts:

   • Ensure factory classes extend WayOfDev\Cycle\Factories\Factory (not Eloquent’s Factory):

     use WayOfDev\Cycle\Factories\Factory;
     
     class UserFactory extends Factory
     {
         protected function definition(): array
         {
             return ['name' => 'Test User'];
         }
     }
     

Debugging

• Query Logging: Enable Cycle’s query logging in config/cycle.php:

  'debug' => env('CYCLE_DEBUG', false),
  

• Entity Mapping: Verify annotations with:

  php artisan cycle:schema:dump
  

Extension Points

1. Custom Rules: Extend WayOfDev\Cycle\Bridge\Laravel\Rules\Rule for domain-specific validation:

   class ValidStatus extends Rule
   {
       public function passes($attribute, $value): bool
       {
           return in_array($value, ['active', 'inactive']);
       }
   }
   

2. Event Listeners: Use Cycle’s event system (e.g., EntityPersisted) via Laravel’s Events facade:

   event(new \Cycle\ORM\EntityPersisted($user));
   

3. Caching: Integrate with Laravel’s cache (e.g., Cache::remember):

   $users = Cache::remember('users', now()->addHours(1), fn() =>
       app(Select::class)->from(User::class)->fetchAll()
   );