pivotphp / cycle-orm
Robust and well-tested Cycle ORM integration for PivotPHP microframework with type safety and comprehensive testing
v1.0.0
2025-07-07 20:13 UTC
Requires
- php: ^8.1
- cycle/annotated: ^4.3
- cycle/migrations: ^4.2.5
- cycle/orm: ^2.10
- cycle/schema-builder: ^2.0
- pivotphp/core: *@dev
- spiral/tokenizer: ^3.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.76
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ^10.0
- squizlabs/php_codesniffer: ^3.13
README
Robust and well-tested Cycle ORM integration for PivotPHP microframework
๐ Features
- Seamless Integration: Deep integration with PivotPHP Core
- Type Safety: Full type safety with PHPStan Level 9
- Repository Pattern: Built-in repository pattern support
- Performance Monitoring: Query logging and performance profiling
- Middleware Support: Transaction and validation middleware
- Health Checks: Database health monitoring
- Zero Configuration: Works out of the box with sensible defaults
๐ฆ Installation
composer require pivotphp/cycle-orm
Development Setup
When developing locally with both pivotphp-core and pivotphp-cycle-orm:
- Clone both repositories in the same parent directory:
git clone https://github.com/CAFernandes/pivotphp-core.git git clone https://github.com/CAFernandes/pivotphp-cycle-orm.git
- Install dependencies:
cd pivotphp-cycle-orm
composer install
The composer.json
is configured to use the local path ../pivotphp-core
for development.
Note: The CI/CD pipeline automatically adjusts the composer configuration to use the GitHub repository instead of the local path.
๐ง 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 composer test-coverage
๐ Documentation
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
๐ License
PivotPHP Cycle ORM is open-sourced software licensed under the MIT license.
๐ Credits
- Created by Caio Alberto Fernandes
- Built on top of Cycle ORM
- Part of the PivotPHP ecosystem