futtern/.junie/guidelines.md

Development Guidelines for Futtern

This document provides essential information for developers working on the Futtern project.

Build and Configuration

PHP Requirements

• PHP 8.4 or higher
• Required extensions: ctype, iconv

Database Configuration

• Default: SQLite (var/data.db)
• Can be configured for MySQL or PostgreSQL by updating the DATABASE_URL in .env or .env.local

Installation Steps

1. Clone the repository
2. Install PHP dependencies:

   composer install
   

3. Install Node.js dependencies:

   npm install
   

4. Copy static assets to Encore directory:

   mkdir -p assets/css assets/js
   cp public/static/css/water.min.css assets/css/
   cp public/static/js/htmx.min.js assets/js/
   

5. Build frontend assets:

   npm run dev   # For development
   npm run build # For production
   

6. Create database schema:

   php bin/console doctrine:schema:create
   

7. Load fixtures (optional):

   php bin/console doctrine:fixtures:load
   

Development Workflow

• Run npm run watch to automatically rebuild assets when files change
• Use Symfony CLI for local development: symfony server:start

Testing

Test Configuration

• Tests use Pest PHP (built on PHPUnit)
• Test environment is configured in .env.test
• Tests are organized in tests/Feature and tests/Unit directories

Running Tests

• Run all tests: composer test
• Run specific tests: composer test -- --filter=TestName
• Run tests in parallel: composer test (parallel is the default)

Test Types

1. Unit Tests (tests/Unit/):

   • Test individual classes in isolation
   • Extend TestCase or use standalone Pest tests
   • Example:

     test('Favicon returns SVG string', function (): void {
         $favicon = new Favicon();
         $result = (string)$favicon;
     
         expect($result)
             ->toBeString()
             ->toContain('data:image/svg+xml')
             ->toContain('transform=\'rotate(')
             ->toContain('viewBox=\'0 0 512 512\'');
     })
         ->covers(Favicon::class);
     

2. Feature Tests (tests/Feature/):

   • Controller tests: Extend DbWebTest for web controllers
   • API tests: Extend DbApiTestCase for API endpoints
   • Each test gets a fresh database

Creating New Tests

1. Determine the appropriate test type (Unit or Feature)
2. Create a new test file in the corresponding directory
3. Use Pest's test() function to define tests
4. Use expect() for assertions
5. Use ->covers() to specify which classes are covered by the test

Code Quality

Code Style

• The project uses Easy Coding Standard (ECS) for code style checking
• Configuration is in ecs.php
• All classes should be marked as final unless they're meant to be extended
• Run code style checks: composer lint

Code Quality Tools

• Rector is used for automated code refactoring
• Configuration is in rector.php
• Run code quality checks: composer lint

Development Practices

• Use strict types in all PHP files: <?php declare(strict_types=1);
• Follow PSR-12 coding standards
• Use type hints for all method parameters and return types
• Use constructor property promotion where appropriate
• Use readonly properties where appropriate
• Use PHP 8.4 features where appropriate