https://github.com/pivotphp/pivotphp-cycle-orm
Complete Cycle ORM integration for PivotPHP - zero-config database layer with high performance and type safety for the evolutionary microframework.
https://github.com/pivotphp/pivotphp-cycle-orm
cycle-orm database helixphp integration mariadb mysql orm performance php postgresql type-safe zero-config
Last synced: about 22 hours ago
JSON representation
Complete Cycle ORM integration for PivotPHP - zero-config database layer with high performance and type safety for the evolutionary microframework.
- Host: GitHub
- URL: https://github.com/pivotphp/pivotphp-cycle-orm
- Owner: PivotPHP
- License: mit
- Created: 2025-07-06T17:40:08.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-07-07T17:20:33.000Z (9 months ago)
- Last Synced: 2025-07-07T17:32:24.887Z (9 months ago)
- Topics: cycle-orm, database, helixphp, integration, mariadb, mysql, orm, performance, php, postgresql, type-safe, zero-config
- Language: PHP
- Homepage: https://pivotphp.github.io/website/
- Size: 409 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# PivotPHP Cycle ORM
[](https://www.php.net/)
[](LICENSE)
[](https://github.com/PivotPHP/pivotphp-cycle-orm/releases)
[](https://phpstan.org/)
[](https://github.com/PivotPHP/pivotphp-cycle-orm/actions)
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
```bash
composer require pivotphp/cycle-orm
```
### Development Setup
When developing locally with both pivotphp-core and pivotphp-cycle-orm:
1. Clone both repositories in the same parent directory:
```bash
git clone https://github.com/PivotPHP/pivotphp-core.git
git clone https://github.com/PivotPHP/pivotphp-cycle-orm.git
```
2. Install dependencies:
```bash
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
```php
use PivotPHP\Core\Core\Application;
use PivotPHP\Core\CycleORM\CycleServiceProvider;
$app = new Application();
$app->register(new CycleServiceProvider());
```
### 2. Configure Database
```php
// 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
```php
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
```php
$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
```php
// 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
```php
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
```php
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
```php
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
```php
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
```php
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
```php
// 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
```bash
# 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
The project includes cross-platform scripts for coverage testing:
- **Primary method**: `composer test-coverage` (works on all platforms)
- **Alternative scripts**: Platform-specific scripts in `scripts/` directory
- **Windows support**: Both CMD and PowerShell scripts included
## 📚 Documentation
- [Integration Guide](docs/integration-guide.md)
- [Complete Guide](docs/guia-completo.md)
- [API Reference](docs/quick-reference.md)
- [Examples](examples/)
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
PivotPHP Cycle ORM is open-sourced software licensed under the [MIT license](LICENSE).
## 🙏 Credits
- Created by [Caio Alberto Fernandes](https://github.com/CAFernandes)
- Built on top of [Cycle ORM](https://cycle-orm.dev/)
- Part of the [PivotPHP](https://github.com/PivotPHP) ecosystem
---
Built with PivotPHP - The modern PHP microframework