Merge pull request #2 from factorial-io/refactor/make-it-dynamic

feat: implement dynamic entity system with code generation (v1.0)

Author: stmh

.github/workflows/code-quality.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        php-version: ['8.1', '8.2', '8.3', '8.4']
+        php-version: ['8.2', '8.3', '8.4']
 
     steps:
     - uses: actions/checkout@v4

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
     - name: Setup PHP
       uses: shivammathur/setup-php@v2
       with:
-        php-version: '8.1'
+        php-version: '8.2'
         extensions: mbstring, json
         coverage: none
 

.gitignore

@@ -2,6 +2,10 @@
 .env
 .env.local
 
+# Code Generation Configuration (may contain API tokens)
+.twenty-codegen.yml
+.twenty-codegen.yaml
+
 # PHPUnit
 phpunit.xml
 .phpunit.result.cache
@@ -28,3 +32,7 @@ composer.lock
 # OS
 .DS_Store
 Thumbs.db
+
+# Twenty CRM OpenAPI specs (instance-specific)
+docs/core.json
+docs/metadata.json

.twenty-codegen.example.yml

@@ -0,0 +1,44 @@
+# Twenty CRM Code Generation Configuration
+# Copy this file to .twenty-codegen.yml and customize for your project
+#
+# Usage: vendor/bin/twenty-generate --config=.twenty-codegen.yml
+
+# Base namespace for generated code
+# Entity, Service, and Collection subdirectories will be created automatically
+namespace: MyApp\TwentyCrm
+
+# Output directory for generated code
+# Entity/, Service/, and Collection/ subdirectories will be created here
+output_dir: src/TwentyCrm
+
+# Twenty CRM API configuration
+# You can use ${VAR_NAME} syntax to reference environment variables
+api_url: ${TWENTY_API_BASE_URI}
+api_token: ${TWENTY_API_TOKEN}
+
+# Alternative: Hardcode values (not recommended for production)
+# api_url: https://your-instance.twenty.com/rest/
+# api_token: your_api_token_here
+
+# List of entities to generate
+# These should match the entity names in your Twenty CRM instance
+# Common entities: person, company, opportunity, note, task, etc.
+entities:
+  - person
+  - company
+  - opportunity
+
+# Code generation options
+options:
+  # Generate service classes with CRUD operations
+  # Creates: PersonService, CompanyService, etc.
+  generate_services: true
+  
+  # Generate typed collection classes
+  # Creates: PersonCollection, CompanyCollection, etc.
+  generate_collections: true
+  
+  # Overwrite existing files during generation
+  # Default: false (will fail if files already exist)
+  # Use --overwrite flag to override this setting
+  overwrite: false

DEVELOPMENT.md

@@ -0,0 +1,134 @@
+# Development Guide
+
+## Repository Structure
+
+This repository contains two distinct packages with clear separation of concerns:
+
+### 1. Core Library (`/`)
+
+The main library providing tools and runtime support for Twenty CRM integration:
+
+- **Location:** Root directory
+- **Package:** `factorial-io/twenty-crm-php-client`
+- **Purpose:** Generic, schema-agnostic tools
+- **Contains:**
+  - DynamicEntity system
+  - Code generation CLI (`bin/twenty-generate`)
+  - Metadata discovery
+  - Entity relations
+  - HTTP client infrastructure
+- **Tests:** Unit tests only (`tests/Unit/`)
+
+### 2. Usage Example (`/usage-example/`)
+
+Example implementation with generated entities demonstrating the library:
+
+- **Location:** `usage-example/` subdirectory
+- **Package:** `factorial-io/twenty-crm-entities` (example, not published)
+- **Purpose:** Usage examples, schema-specific entities, and integration tests
+- **Contains:**
+  - Generated Person, Company, Campaign entities
+  - Integration tests demonstrating library features
+  - Test helpers and factories
+  - Example usage patterns
+- **Tests:** Integration tests (`usage-example/tests/Integration/`)
+
+## Separation of Concerns
+
+| Concern | Core Library | Usage Example |
+|---------|--------------|---------------|
+| Generic tools | ✅ | ❌ |
+| DynamicEntity | ✅ | Uses |
+| Code generator | ✅ | Uses |
+| Generated entities | ❌ | ✅ |
+| Integration tests | ❌ | ✅ |
+| Schema-specific code | ❌ | ✅ |
+| Unit tests | ✅ | ❌ |
+
+## Running Tests
+
+### Core Library (Unit Tests)
+
+```bash
+# Run all unit tests
+vendor/bin/phpunit
+
+# Run with coverage
+vendor/bin/phpunit --coverage-html coverage/
+```
+
+### Usage Example (Integration Tests)
+
+```bash
+# Setup
+cd usage-example
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run integration tests
+cd usage-example
+../vendor/bin/phpunit
+```
+
+## Development Workflow
+
+### Working on Core Library
+
+1. Make changes in `src/`
+2. Add unit tests in `tests/Unit/`
+3. Run `vendor/bin/phpunit`
+4. Ensure no entity-specific code
+
+### Working on Usage Example
+
+1. Generate entities: `vendor/bin/twenty-generate --config=usage-example/.twenty-codegen.yml`
+2. Add integration tests in `usage-example/tests/Integration/`
+3. Run `cd usage-example && ../vendor/bin/phpunit`
+4. Commit generated code
+
+## Usage Example as Template
+
+The `usage-example/` directory serves multiple purposes:
+
+1. **Documentation:** Shows how to use the library with real code
+2. **Testing:** Integration tests validate library features against a live Twenty CRM instance
+3. **Code Generation Example:** Demonstrates the code generation workflow
+4. **Template:** Can be copied/adapted for your own Twenty CRM instance
+
+## Why This Structure?
+
+1. **Flexibility:** Users can use core library with any Twenty instance
+2. **Type Safety:** Generated typed entities with IDE support
+3. **Clean Separation:** No instance-specific code in core library
+4. **Living Documentation:** Real, tested examples of library usage
+5. **Example Code:** Shows how to generate and use entities
+
+## Code Generation
+
+Generate entities using the example configuration:
+
+```bash
+# Using config file
+vendor/bin/twenty-generate --config=usage-example/.twenty-codegen.yml
+
+# Or with CLI args
+vendor/bin/twenty-generate \
+  --api-url=https://your-instance.twenty.com/rest/ \
+  --api-token=$TWENTY_TOKEN \
+  --namespace="Factorial\\TwentyCrm\\Entities" \
+  --output=usage-example/src \
+  --entities=person,company,campaign
+```
+
+## Quality Checks
+
+```bash
+# PHP CodeSniffer
+vendor/bin/phpcs
+
+# PHP CS Fixer
+vendor/bin/php-cs-fixer fix --dry-run --diff
+
+# PHPStan
+vendor/bin/phpstan analyse src
+```