Coding Style

This page covers the coding conventions used in Logidav. The canonical reference is CODING_STYLE.md at the project root.

Principles

• Prefer readable, maintainable code over clever shortcuts
• Keep changes focused and consistent with the surrounding bundle
• Favor explicit dependencies and predictable side effects
• Treat cronjobs, queues, shipments, payments, and stock updates as high-risk flows — code defensively

PHP formatting

• PHP 7.3 compatibility required
• Follow PSR-2 / PSR-12 standards
• 4 spaces for indentation, no tabs
• UTF-8 encoding, Unix line endings
• Short array syntax: []
• Clean imports — remove unused use statements

Formatting rules are enforced by .php-cs-fixer.php at the project root.

# Fix code style
php tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php

Symfony conventions

• Stateless services — keep services stateless when possible
• Constructor injection — prefer constructor injection over container lookups
• Namespace alignment — namespaces must match the bundle directory structure
• Role-based naming — classes are suffixed by their role:

Suffix	Purpose	Example
*Service	Business logic	StockService
*Command	Symfony console command (cronjob)	ImportSalesCommand
*Controller	HTTP controller	OrderController
*Repository	Custom Doctrine queries	SaleRepository

High-risk domain rules

:::danger Defensive coding required The following domains handle money, inventory, and customer commitments. Bugs here have direct business impact. Apply extra caution. :::

Sales and orders

• Validate all incoming data before persisting
• Never silently skip failed order imports — log and re-queue

Stock management

• Always use transactional stock mutations
• Never update stock without a traceable origin (order ID, import batch, etc.)

Refunds and SAV

• Double-check refund amounts against the original order
• Log every refund action with full context

Shipments

• Validate carrier response data before marking a shipment as sent
• Handle label generation failures gracefully — retry, don't ignore

Doctrine guidelines

• Keep query logic in repository classes, not in services or controllers
• Keep transactions short to avoid lock contention
• Avoid loading large result sets into memory in batch processes — use iterators or chunked queries

Testing

• Mirror the src/ namespace structure under tests/
• Suffix test classes with Test (e.g., StockServiceTest)
• Add concise PHPDoc to non-trivial methods
• Update documentation when a production workflow changes

Frontend patterns

Logidav uses jQuery + Twig for its web interface:

• Use App.get() and App.post() helper methods for AJAX calls
• Keep JavaScript logic in dedicated files, not inline in Twig templates
• Follow existing patterns in the codebase for consistency

Validation commands

Run all three before pushing:

# 1. Code style
php tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php

# 2. Static analysis
composer phpstan

# 3. Tests
SYMFONY_DEPRECATIONS_HELPER=weak_vendors vendor/bin/simple-phpunit -c phpunit.xml.dist

:::tip Pre-push checklist Run these three commands in order before every push. The CI pipeline runs the same checks, so catching issues locally saves time. :::