Part-DB-server/.github/copilot-instructions.md

Copilot Instructions for Part-DB

Part-DB is an Open-Source inventory management system for electronic components built with Symfony 7.4 and modern web technologies.

Technology Stack

• Backend: PHP 8.2+, Symfony 7.4, Doctrine ORM
• Frontend: Bootstrap 5, Hotwire Stimulus/Turbo, TypeScript, Webpack Encore
• Database: MySQL 5.7+/MariaDB 10.4+/PostgreSQL 10+/SQLite
• Testing: PHPUnit with DAMA Doctrine Test Bundle
• Code Quality: Easy Coding Standard (ECS), PHPStan (level 5)

Project Structure

• src/: PHP application code organized by purpose (Controller, Entity, Service, Form, etc.)
• assets/: Frontend TypeScript/JavaScript and CSS files
• templates/: Twig templates for views
• tests/: PHPUnit tests mirroring the src/ structure
• config/: Symfony configuration files
• public/: Web-accessible files
• translations/: Translation files for multi-language support

Coding Standards

PHP Code

• Follow PSR-12 and Symfony coding standards
• Use type hints for all parameters and return types
• Always declare strict types: declare(strict_types=1); at the top of PHP files
• Use PHPDoc blocks for complex logic or when type information is needed

TypeScript/JavaScript

• Use TypeScript for new frontend code
• Follow existing Stimulus controller patterns in assets/controllers/
• Use Bootstrap 5 components and utilities
• Leverage Hotwire Turbo for dynamic page updates

Naming Conventions

• Entities: Use descriptive names that reflect database models (e.g., Part, StorageLocation)
• Controllers: Suffix with Controller (e.g., PartController)
• Services: Descriptive names reflecting their purpose (e.g., PartService, LabelGenerator)
• Tests: Match the class being tested with Test suffix (e.g., PartTest, PartControllerTest)

Development Workflow

Dependencies

• Install PHP dependencies: composer install
• Install JS dependencies: yarn install
• Build frontend assets: yarn build (production) or yarn watch (development)

Database

• Create database: php bin/console doctrine:database:create --env=dev
• Run migrations: php bin/console doctrine:migrations:migrate --env=dev
• Load fixtures: php bin/console partdb:fixtures:load -n --env=dev

Or use Makefile shortcuts:

• make dev-setup: Complete development environment setup
• make dev-reset: Reset development environment (cache clear + migrate)

Testing

• Set up test environment: make test-setup
• Run all tests: php bin/phpunit
• Run specific test: php bin/phpunit tests/Path/To/SpecificTest.php
• Run tests with coverage: php bin/phpunit --coverage-html var/coverage
• Test environment uses SQLite by default for speed

Static Analysis

• Run PHPStan: composer phpstan or COMPOSER_MEMORY_LIMIT=-1 php -d memory_limit=1G vendor/bin/phpstan analyse src --level 5
• PHPStan configuration is in phpstan.dist.neon

Running the Application

• Development server: symfony serve (requires Symfony CLI)
• Or configure Apache/nginx to serve from public/ directory
• Set APP_ENV=dev in .env.local for development mode

Best Practices

Security

• Always sanitize user input
• Use Symfony's security component for authentication/authorization
• Check permissions using the permission system before allowing actions
• Never expose sensitive data in logs or error messages
• Use parameterized queries (Doctrine handles this automatically)

Performance

• Use Doctrine query builder for complex queries instead of DQL when possible
• Lazy load relationships to avoid N+1 queries
• Cache results when appropriate using Symfony's cache component
• Use pagination for large result sets (DataTables integration available)

Database

• Always create migrations for schema changes: php bin/console make:migration
• Review migration files before running them
• Use Doctrine annotations or attributes for entity mapping
• Follow existing entity patterns for relationships and lifecycle callbacks

Frontend

• Use Stimulus controllers for interactive components
• Leverage Turbo for dynamic page updates without full page reloads
• Use Bootstrap 5 classes for styling
• Keep JavaScript modular and organized in controllers
• Use the translation system for user-facing strings

Translations

• Use translation keys, not hardcoded strings: {{ 'part.info.title'|trans }}
• Add new translation keys to translations/ files
• Primary language is English (en)
• Translations are managed via Crowdin, but can be edited locally if needed

Testing

• Write unit tests for services and helpers
• Write functional tests for controllers
• Use fixtures for test data
• Tests should be isolated and not depend on execution order
• Mock external dependencies when appropriate
• Follow existing test patterns in the repository

Common Patterns

Creating an Entity

1. Create entity class in src/Entity/ with Doctrine attributes
2. Generate migration: php bin/console make:migration
3. Review and run migration: php bin/console doctrine:migrations:migrate
4. Create repository if needed in src/Repository/
5. Add fixtures in src/DataFixtures/ for testing

Adding a Form

1. Create form type in src/Form/
2. Extend AbstractType and implement buildForm() and configureOptions()
3. Use in controller and render in Twig template
4. Follow existing form patterns for consistency

Creating a Controller Action

1. Add method to appropriate controller in src/Controller/
2. Use route attributes for routing
3. Check permissions using security voters
4. Return Response or render Twig template
5. Add corresponding template in templates/

Adding a Service

1. Create service class in src/Services/
2. Use dependency injection via constructor
3. Tag service in config/services.yaml if needed
4. Services are autowired by default

Important Notes

• Part-DB uses fine-grained permissions - always check user permissions before actions
• Multi-language support is critical - use translation keys everywhere
• The application supports multiple database backends - write portable code
• Responsive design is important - test on mobile/tablet viewports
• Event system is used for logging changes - emit events when appropriate
• API Platform is integrated for REST API endpoints

Multi-tenancy Considerations

• Part-DB is designed as a single-tenant application with multiple users
• User groups have different permission levels
• Always scope queries to respect user permissions
• Use the security context to get current user information

Resources

• Documentation
• Contributing Guide
• Symfony Documentation
• Doctrine Documentation
• Bootstrap 5 Documentation
• Hotwire Documentation