futtern/.junie/guidelines.md

Development Guidelines

This document provides guidelines and instructions for developing and maintaining the Futtern project.

Build/Configuration Instructions

Environment Setup

1. PHP Requirements: The project requires PHP 8.4 or higher with the following extensions:

   • ctype
   • iconv

2. Composer: Install dependencies using Composer:

   composer install
   

3. Environment Configuration: Copy .env to .env.local and adjust the settings as needed for your local environment.

Development Server

Start the Symfony development server:

symfony server:start

Building Assets

The project uses Tailwind CSS via the symfonycasts/tailwind-bundle:

# Install importmap assets
symfony console importmap:install

Deployment

The project includes several deployment scripts:

1. Prepare for Deployment:

   ./deploy/prepare-deploy.sh
   

   This script creates a clean copy of the application with only production dependencies.

2. Local Deployment:

   ./deploy/local-deploy.sh
   

   This script deploys the application to a remote server, backing up the database and restarting the service.

3. Update After Deployment:

   ./deploy/update.sh
   

   This script is run on the remote server to clear cache, warm up cache, and run database migrations.

Testing Information

Testing Framework

The project uses Pest PHP, a testing framework built on top of PHPUnit, for testing. Tests are organized into:

• Feature Tests: For testing controllers and API endpoints
• Unit Tests: For testing individual components

Running Tests

Run all tests:

composer test
# or
./vendor/bin/pest

Run specific tests:

./vendor/bin/pest tests/Unit/ExampleTest.php

Run tests in parallel:

./vendor/bin/pest --parallel

Creating Tests

1. Unit Tests: Create files in the tests/Unit directory.
2. Feature Tests:
   • Controller tests: Create files in tests/Feature/Controller
   • API tests: Create files in tests/Feature/Api

Example Test

Here's a simple example of a Pest PHP test:

<?php declare(strict_types=1);

test('example test', function (): void {
    expect(true)->toBeTrue();
    expect(1 + 1)->toBe(2);
    expect('hello world')->toContain('world');
});

test('array operations', function (): void {
    $array = [1, 2, 3];
    
    expect($array)->toHaveCount(3);
    expect($array)->toContain(2);
    expect($array[0])->toBe(1);
});

Test Base Classes

• DbWebTest: Base class for controller tests
• DbApiTestCase: Base class for API tests

Code Quality and Style

Code Style

The project uses Easy Coding Standard (ECS) for code style checking:

composer lint
# or
./vendor/bin/ecs --fix

The code style is defined in ecs.php and includes:

• Custom rules from Lubiana\CodeQuality\LubiSetList::ECS
• All classes should be declared as final

Code Refactoring

The project uses Rector for automated code refactoring:

./vendor/bin/rector

The refactoring rules are defined in rector.php and include:

• Custom rules from Lubiana\CodeQuality\LubiSetList::RECTOR
• StaticClosureRector is skipped in the tests directory

Development Workflow

1. Make changes to the code
2. Run tests to ensure functionality: composer test
3. Fix code style issues: composer lint
4. Commit and push changes
5. Deploy using the deployment scripts

Debugging

• Use the Symfony Web Profiler in development mode
• Check logs in var/log/
• For API debugging, use the API Platform documentation at /api