feat: Add Cycle ORM extension for Express-PHP microframework

- Created composer.json for package management.
- Added configuration file for Cycle ORM settings.
- Implemented commands for entity generation, migration, and schema management.
- Developed middleware for automatic ORM injection, transaction management, and entity validation.
- Created repository factory for managing entity repositories.
- Added helper functions for pagination and dynamic filtering.
- Established a service provider to register and boot Cycle ORM services.
- Included tests for service provider and various components.
- Added documentation for installation, configuration, and usage examples.

Author: CAFernandes

.env.example

@@ -0,0 +1,19 @@
+# Exemplo de configuração .env para express-php/cycle-orm-extension
+
+# Banco de Dados
+DB_CONNECTION=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_DATABASE=express_api
+DB_USERNAME=root
+DB_PASSWORD=
+
+# Configurações do Cycle ORM
+CYCLE_SCHEMA_CACHE=true
+CYCLE_AUTO_SYNC=false
+CYCLE_SCHEMA_STRICT=false
+
+# Outras opções
+APP_ENV=local
+APP_DEBUG=true
+APP_URL=http://localhost

CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Express PHP Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LINCENSE

@@ -0,0 +1,190 @@
+# Express-PHP Cycle ORM Extension
+
+Integração completa do Cycle ORM com o microframework Express-PHP, mantendo a filosofia ultraleve e performance excepcional.
+
+## ⚡ Características
+
+- **Auto-Discovery**: Registra automaticamente via Service Provider
+- **Middleware Integration**: Injeção automática de ORM, EntityManager e helpers
+- **Transaction Management**: Transações automáticas com middleware
+- **CLI Commands**: Comandos para schema, migrações e geração de entidades
+- **Zero Configuration**: Funciona out-of-the-box com configurações sensatas
+- **High Performance**: Otimizado para microframework ultraleve
+
+## 🚀 Instalação
+
+```bash
+composer require express-php/cycle-orm-extension
+```
+
+O Service Provider é registrado automaticamente via auto-discovery.
+
+## ⚙️ Configuração
+
+Publique o arquivo de configuração (opcional):
+
+```bash
+php express vendor:publish --provider="ExpressPHP\CycleORM\CycleServiceProvider"
+```
+
+Configure suas variáveis de ambiente:
+
+```env
+DB_CONNECTION=mysql
+DB_HOST=localhost
+DB_DATABASE=express_db
+DB_USERNAME=root
+DB_PASSWORD=
+```
+
+## 📖 Uso Básico
+
+### Criando uma Entidade
+
+```bash
+php express make:entity User
+```
+
+```php
+<?php
+
+namespace App\Models;
+
+use Cycle\Annotated\Annotation\Entity;
+use Cycle\Annotated\Annotation\Column;
+
+#[Entity(table: 'users')]
+class User
+{
+    #[Column(type: 'primary')]
+    public int $id;
+
+    #[Column(type: 'string')]
+    public string $name;
+
+    #[Column(type: 'string')]
+    public string $email;
+}
+```
+
+### Usando nas Rotas
+
+```php
+$app->get('/api/users', function($req, $res) {
+    // Repository injetado automaticamente
+    $users = $req->repository(User::class)->findAll();
+    $res->json(['users' => $users]);
+});
+
+$app->post('/api/users', function($req, $res) {
+    // Entity helper
+    $user = $req->entity(User::class, $req->body);
+
+    // EntityManager injetado
+    $req->em->persist($user);
+    // Auto-commit via TransactionMiddleware
+
+    $res->status(201)->json(['user' => $user]);
+});
+```
+
+### Comandos CLI
+
+```bash
+# Sincronizar schema
+php express cycle:schema --sync
+
+# Executar migrações
+php express cycle:migrate
+
+# Gerar entidade
+php express make:entity Post
+```
+
+## 🛠️ Middlewares Disponíveis
+
+### CycleMiddleware
+Injeta automaticamente ORM, EntityManager e helpers no request.
+
+### TransactionMiddleware
+Gerencia transações automaticamente:
+
+```php
+$app->post('/api/users', function($req, $res) {
+    // Transação iniciada automaticamente
+    $user = new User($req->body);
+    $req->em->persist($user);
+    // Auto-commit ao final (ou rollback em caso de erro)
+});
+```
+
+## 🎯 Recursos Avançados
+
+### Paginação e Filtros
+
+```php
+use ExpressPHP\CycleORM\Helpers\CycleHelpers;
+
+$app->get('/api/users', function($req, $res) {
+    $query = $req->repository(User::class)->select();
+
+    // Filtros dinâmicos
+    $filters = $req->query['filters'] ?? [];
+    $query = CycleHelpers::applyFilters($query, $filters);
+
+    // Ordenação
+    $query = CycleHelpers::applySorting($query, 'createdAt', 'desc');
+
+    // Paginação
+    $result = CycleHelpers::paginate($query, $req->query['page'] ?? 1);
+
+    $res->json($result);
+});
+```
+
+### Relacionamentos Complexos
+
+```php
+$app->get('/api/users/:id', function($req, $res) {
+    $user = $req->repository(User::class)
+        ->select()
+        ->load('posts', [
+            'method' => \Cycle\ORM\Select::SINGLE_QUERY
+        ])
+        ->where('id', $req->params['id'])
+        ->fetchOne();
+
+    $res->json(['user' => $user]);
+});
+```
+
+## 🧪 Testing
+
+```bash
+composer test
+composer test-coverage
+composer phpstan
+```
+
+## 📊 Performance
+
+- **Zero Overhead**: Registra serviços apenas quando necessário
+- **Lazy Loading**: Repositories e connections são lazy-loaded
+- **Optimized Queries**: Helpers otimizados para queries comuns
+- **Transaction Efficiency**: Transações automáticas evitam commits desnecessários
+
+## 📚 Documentação Completa
+
+Veja a documentação completa em: [docs/cycle-orm-extension.md](docs/cycle-orm-extension.md)
+
+## 🤝 Contribuindo
+
+1. Fork o projeto
+2. Crie uma branch para sua feature
+3. Commit suas mudanças
+4. Push para a branch
+5. Abra um Pull Request
+
+## 📄 Licença
+
+MIT License - veja [LICENSE](LICENSE) para detalhes.

README.md

@@ -0,0 +1,50 @@
+{
+    "name": "express-php/cycle-orm-extension",
+    "description": "Cycle ORM integration for Express-PHP microframework",
+    "keywords": ["express-php", "cycle-orm", "database", "orm", "microframework"],
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Caio Alberto Fernandes",
+            "email": "caio.fernandes@example.com"
+        }
+    ],
+    "require": {
+        "php": "^8.1",
+        "cafernandes/express-php": "^2.1",
+        "cycle/orm": "^2.0",
+        "cycle/annotated": "^3.0",
+        "cycle/migrations": "^3.0",
+        "cycle/schema-builder": "^2.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^10.0",
+        "phpstan/phpstan": "^1.0",
+        "squizlabs/php_codesniffer": "^3.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "ExpressPHP\\CycleORM\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "ExpressPHP\\CycleORM\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "express-php": {
+            "providers": [
+                "ExpressPHP\\CycleORM\\CycleServiceProvider"
+            ]
+        }
+    },
+    "scripts": {
+        "test": "phpunit",
+        "test-coverage": "phpunit --coverage-html coverage",
+        "phpstan": "phpstan analyse src --level=9",
+        "cs-check": "phpcs src --standard=PSR12",
+        "cs-fix": "phpcbf src --standard=PSR12"
+    }
+}

composer.json

@@ -0,0 +1,61 @@
+<?php
+
+return [
+    // Database configuration
+    'database' => [
+        'default' => env('DB_CONNECTION', 'mysql'),
+        'databases' => [
+            'default' => ['connection' => env('DB_CONNECTION', 'mysql')]
+        ],
+        'connections' => [
+            'mysql' => [
+                'driver' => 'mysql',
+                'host' => env('DB_HOST', 'localhost'),
+                'port' => env('DB_PORT', 3306),
+                'database' => env('DB_DATABASE', 'express_db'),
+                'username' => env('DB_USERNAME', 'root'),
+                'password' => env('DB_PASSWORD', ''),
+                'charset' => 'utf8mb4',
+                'collation' => 'utf8mb4_unicode_ci',
+                'options' => [
+                    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
+                    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+                    PDO::ATTR_EMULATE_PREPARES => false,
+                ]
+            ],
+            'sqlite' => [
+                'driver' => 'sqlite',
+                'database' => env('DB_DATABASE', 'database/database.sqlite'),
+                'options' => [
+                    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
+                    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
+                ]
+            ]
+        ]
+    ],
+
+    // Entity configuration
+    'entities' => [
+        'directories' => ['app/Models'],
+        'namespace' => 'App\\Models'
+    ],
+
+    // Schema configuration
+    'schema' => [
+        'cache' => env('CYCLE_SCHEMA_CACHE', true),
+        'auto_sync' => env('CYCLE_AUTO_SYNC', false),
+        'strict' => env('CYCLE_SCHEMA_STRICT', false)
+    ],
+
+    // Migration configuration
+    'migrations' => [
+        'directory' => 'database/migrations',
+        'table' => 'migrations',
+        'safe' => env('CYCLE_SAFE_MIGRATIONS', true)
+    ],
+
+    // Repository configuration
+    'repositories' => [
+        'default' => \Cycle\ORM\Select\Repository::class
+    ]
+];