SolidInvoice Development Guide

Expert guidance for AI assistants working with the SolidInvoice codebase - an elegant invoicing solution for small businesses and freelancers.

Project Overview

SolidInvoice is a sophisticated open-source invoicing application providing:

**Tech Stack:** Symfony 7.1+, PHP 8.4+, Doctrine ORM, API Platform, MySQL 8.0+

**Version:** 2.3.11

**License:** MIT

Architecture Patterns

1. Modular Bundle Architecture

The application uses 19 specialized bundles organized by domain:

**Business Logic:**

**System & Infrastructure:**

**UI & Presentation:**

2. Action Pattern (Not Controllers)

Entry points for HTTP requests are **Action classes** with single responsibility:

```php

// src/InvoiceBundle/Action/CreateAction.php

class CreateAction

{

public function __invoke(Request $request): Response

{

// Handle invoice creation

}

}

```

3. Event-Driven Architecture

Extensive use of Symfony EventDispatcher:

4. State Machine (Workflow)

Symfony Workflow for invoice state management:

5. Repository Pattern

Custom repositories extending Doctrine EntityRepository in `Repository/` directory.

6. Manager Pattern

Complex domain operations encapsulated in Manager classes (e.g., `InvoiceManager`, `PaymentSettingsManager`) in `Manager/` directory.

Codebase Structure

Root Directory Layout

```

/

├── assets/ # Frontend (Stimulus, SCSS)

│ ├── controllers/ # Stimulus controllers

│ └── scss/ # Sass stylesheets

├── bin/ # Executables (console, phpunit)

├── config/ # Symfony configuration

│ ├── packages/ # Package configurations

│ ├── routes/ # Route definitions

│ └── services.php # Service container config

├── migrations/ # Database migrations

├── src/ # 19 bundles

├── templates/ # Twig templates

└── tests/ # Test bootstrap and utilities

```

Bundle Internal Structure

```

BundleNameBundle/

├── Action/ # Action classes (HTTP entry points)

├── Entity/ # Doctrine entities

├── Form/ # Symfony Form types

├── (Listener|EventSubscriber)/ # Event handlers

├── Manager/ # Business logic managers

├── Repository/ # Database access objects

├── Resources/

│ ├── config/ # Bundle configs

│ │ ├── routing/ # Route configuration

│ │ └── services/ # DI services

│ ├── translations/ # i18n files

│ └── views/ # Twig templates

└── Tests/

├── Functional/ # Integration tests

└── Unit/ # Unit tests

```

Development Workflow

Initial Setup

```bash

Clone and install dependencies

git clone https://github.com/SolidInvoice/SolidInvoice.git

cd SolidInvoice

composer install

bun install

Build frontend assets

bun run dev # Development with watch

bun run build # Production build

Setup database

bin/console doctrine:database:create

bin/console doctrine:migrations:migrate

```

Common Commands

```bash

Frontend

bun run dev # Build assets in dev mode with watch

bun run build # Production optimized build

bun run lint:js # ESLint validation

bun run lint:css # StyleLint validation

Backend

bin/console cache:clear # Clear cache

bin/console doctrine:migrations:migrate # Run migrations

bin/console doctrine:schema:validate # Validate schema

Code Quality

bin/ecs check # Check coding standards

bin/ecs check --fix # Auto-fix standards

bin/phpstan analyse # Static analysis

bin/rector process # Apply refactoring

Testing

bin/phpunit # Run all tests

bin/phpunit --coverage-html coverage # Generate coverage

bin/phpunit --filter testCreateInvoice # Run specific test

```

Testing Strategy

Test Structure

```

src/BundleNameBundle/Tests/

├── Functional/

│ └── Api/ # API endpoint tests

├── Form/ # Form type tests

└── Repository/ # Repository tests

```

Test Types

**1. Unit Tests** - Test individual classes in isolation with Mockery:

```php

use Mockery as m;

class InvoiceManagerTest extends TestCase

{

public function testCreateInvoice(): void

{

$repository = m::mock(InvoiceRepository::class);

// Test logic

}

}

```

**2. Functional Tests** - Test full request/response cycle with database

**3. API Tests** - Test REST API endpoints extending `ApiTestCase`

PHPUnit Configuration

Code Quality Standards

File Header Requirement

All PHP files must include:

```php

<?php

declare(strict_types=1);

/*

* This file is part of SolidInvoice project.

*

* (c) Pierre du Plessis <[email protected]>

*

* This source file is subject to the MIT license that is bundled

* with this source code in the file LICENSE.

*/

```

Standards Applied (ECS)

Static Analysis (PHPStan)

Pre-commit Checklist

1. ✅ `bin/ecs check --fix` - Coding standards

2. ✅ `bin/phpstan analyse` - Static analysis

3. ✅ `bin/phpunit` - Run tests

4. ✅ Ensure proper file headers

5. ✅ Validate commit message format

Key Conventions

Entity Traits (Cross-Cutting Concerns)

```php

trait Archivable {

private bool $archived = false;

}

trait TimeStampable {

private DateTimeInterface $created;

private DateTimeInterface $updated;

}

trait CompanyAware {

private Company $company;

}

trait Money {

// Money object fields

}

```

Dependency Injection

Database & ORM

Distribution & Deployment

**Recommended:** FrankenPHP binary (single binary containing PHP, web server, and application code)

**Alternatives:**

CI/CD Pipeline (GitHub Actions)

Every pull request triggers:

1. **Unit Tests** - PHP 8.4/8.5, MySQL 8.0, code coverage (Codecov), E2E tests

2. **Coding Standards** - ECS, Composer normalize, Super-Linter

3. **Static Analysis** - PHPStan Level 6, Qodana

4. **Security Checks** - Composer vulnerabilities, CodeQL

Important Notes

Resources