PivotPHP Cycle ORM

PHP Version License Latest Stable Version PHPStan Tests

Robust and well-tested Cycle ORM integration for PivotPHP microframework

🚀 Features

📦 Installation

composer require pivotphp/cycle-orm

Development Setup

git clone https://github.com/PivotPHP/pivotphp-core.git
git clone https://github.com/PivotPHP/pivotphp-cycle-orm.git

cd pivotphp-cycle-orm
composer install

🔧 Quick Start

1. Register the Service Provider

use PivotPHP\Core\Core\Application;
use PivotPHP\Core\CycleORM\CycleServiceProvider;
$app = new Application();
$app->register(new CycleServiceProvider());

2. Configure Database

// config/cycle.php
return [
 'database' => [
 'default' => 'default',
 'databases' => [
 'default' => ['connection' => 'sqlite']
 ],
 'connections' => [
 'sqlite' => [
 'driver' => \Cycle\Database\Driver\SQLite\SQLiteDriver::class,
 'options' => [
 'connection' => 'sqlite:database.db',
 ]
 ]
 ]
 ]
];

3. Define Entities

use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\Column;
#[Entity(repository: UserRepository::class)]
class User
{
 #[Column(type: 'primary')]
 private int $id;
 #[Column(type: 'string')]
 private string $name;
 #[Column(type: 'string', unique: true)]
 private string $email;
 // Getters and setters...
}

4. Use in Routes

$app->get('/users', function (CycleRequest $request) {
 $users = $request->getRepository(User::class)->findAll();
 return $request->response()->json($users);
});
$app->post('/users', function (CycleRequest $request) {
 $user = new User();
 $user->setName($request->input('name'));
 $user->setEmail($request->input('email'));
 $request->persist($user);
 return $request->response()->json($user, 201);
});

🎯 Core Features

Repository Pattern

// Custom repository
class UserRepository extends Repository
{
 public function findByEmail(string $email): ?User
 {
 return $this->findOne(['email' => $email]);
 }
 public function findActive(): array
 {
 return $this->select()
 ->where('active', true)
 ->orderBy('created_at', 'DESC')
 ->fetchAll();
 }
}

Transaction Middleware

use PivotPHP\Core\CycleORM\Middleware\TransactionMiddleware;
// Automatic transaction handling
$app->post('/api/orders',
 new TransactionMiddleware(),
 function (CycleRequest $request) {
 // All database operations are wrapped in a transaction
 $order = new Order();
 $request->persist($order);
 // If an exception occurs, transaction is rolled back
 foreach ($request->input('items') as $item) {
 $orderItem = new OrderItem();
 $request->persist($orderItem);
 }
 return $request->response()->json($order);
 }
);

Query Monitoring

use PivotPHP\Core\CycleORM\Monitoring\QueryLogger;
// Enable query logging
$logger = $app->get(QueryLogger::class);
$logger->enable();
// Get query statistics
$stats = $logger->getStatistics();
// [
// 'total_queries' => 42,
// 'total_time' => 0.123,
// 'queries' => [...]
// ]

Health Checks

use PivotPHP\Core\CycleORM\Health\CycleHealthCheck;
$app->get('/health', function () use ($app) {
 $health = $app->get(CycleHealthCheck::class);
 $status = $health->check();
 return [
 'status' => $status->isHealthy() ? 'healthy' : 'unhealthy',
 'database' => $status->getData()
 ];
});

🛠️ Advanced Usage

Entity Validation Middleware

use PivotPHP\Core\CycleORM\Middleware\EntityValidationMiddleware;
$app->post('/users',
 new EntityValidationMiddleware(User::class, [
 'name' => 'required|string|min:3',
 'email' => 'required|email|unique:users,email'
 ]),
 $handler
);

Performance Profiling

use PivotPHP\Core\CycleORM\Monitoring\PerformanceProfiler;
$profiler = $app->get(PerformanceProfiler::class);
$profiler->startProfiling();
// Your database operations...
$profile = $profiler->stopProfiling();
// [
// 'duration' => 0.456,
// 'memory_peak' => 2097152,
// 'queries_count' => 15
// ]

Custom Commands

// Create entity command
php vendor/bin/pivotphp cycle:entity User
// Run migrations
php vendor/bin/pivotphp cycle:migrate
// Update schema
php vendor/bin/pivotphp cycle:schema
// Check database status
php vendor/bin/pivotphp cycle:status

🧪 Testing

# Run all tests
composer test
# Run specific test suite
composer test:unit
composer test:feature
composer test:integration
# Run with coverage (cross-platform)
composer test-coverage
# Platform-specific alternatives:
# Unix/Linux/macOS
./scripts/test-coverage.sh
# Windows CMD
scripts\test-coverage.bat
# PowerShell
scripts\test-coverage.ps1

Cross-Platform Compatibility

📚 Documentation

🤝 Contributing

📄 License

🙏 Credits