SolidInvoice Development Assistant

Expert guide for developing, testing, and maintaining the SolidInvoice codebase—a sophisticated open-source invoicing application built with Symfony.

Overview

SolidInvoice is an enterprise-grade invoicing solution for small businesses and freelancers, featuring client management, quote/invoice generation, recurring billing, multi-gateway payment processing, and a RESTful API.

**Tech Stack:** PHP 8.4+, Symfony 7.1+, Doctrine ORM, API Platform, MySQL/PostgreSQL, Stimulus, Webpack Encore, Docker, FrankenPHP

Project Architecture

Modular Bundle System (19 Bundles)

The application uses a modular bundle architecture with clear separation of concerns:

**Business Logic:**

**Infrastructure:**

**UI & Presentation:**

Standard Bundle Structure

```

BundleNameBundle/

├── Action/ # HTTP entry points (not Controllers)

├── Entity/ # Doctrine ORM entities

├── Form/ # Form types and handlers

├── Listener/ # Event listeners/subscribers

├── Manager/ # Complex business logic

├── Repository/ # Database queries

├── Resources/

│ ├── config/ # Routes, services

│ ├── translations/

│ └── views/ # Twig templates

└── Tests/

├── Functional/

└── Unit/

```

Key Design Patterns

1. Action Pattern (Not Controllers)

Entry points are single-purpose Action classes:

```php

// src/InvoiceBundle/Action/CreateAction.php

class CreateAction

{

public function __invoke(Request $request): Response

{

// Handle invoice creation

}

}

```

2. Event-Driven Architecture

Use Symfony EventDispatcher for decoupling:

3. State Machine (Workflow)

Symfony Workflow manages invoice states:

4. Entity Traits

Common cross-cutting concerns:

5. Repository Pattern

Custom repositories for complex queries:

```php

class InvoiceRepository extends EntityRepository

{

public function findOverdueInvoices(): array

{

// Optimized query logic

}

}

```

Development Workflow

Initial Setup

```bash

Clone and install

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

cd SolidInvoice

composer install

bun install

Build 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

**Frontend:**

```bash

bun run dev # Build with watch

bun run build # Production build

bun run lint:js # ESLint validation

bun run lint:css # StyleLint validation

```

**Backend:**

```bash

bin/console cache:clear # Clear cache

bin/console doctrine:migrations:migrate # Run migrations

bin/console doctrine:schema:validate # Validate schema

```

**Code Quality:**

```bash

bin/ecs check # Check coding standards

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

bin/phpstan analyse # Static analysis (Level 6)

bin/rector process --dry-run # Preview refactoring

bin/rector process # Apply refactoring

```

**Testing:**

```bash

bin/phpunit # Run all tests

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

bin/phpunit --filter testName # Run specific test

bin/phpunit src/InvoiceBundle/Tests # Test specific bundle

```

Testing Strategy

Test Types

**1. Unit Tests**

```php

use Mockery as m;

class InvoiceManagerTest extends TestCase

{

public function testCreateInvoice(): void

{

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

// Test logic

}

}

```

**2. Functional Tests**

**3. API Tests**

Test Configuration

**Key PHPUnit Settings:**

**Fixtures:** Use Foundry for factory-based test data

Code Quality Standards

Required File Header

```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.

*/

```

Coding Standards (ECS)

Configuration: `ecs.php`

Applied standards:

Static Analysis (PHPStan)

Configuration: `phpstan.neon`

Code Refactoring (Rector)

Configuration: `rector.php`

Rules:

Pre-commit Checklist

Before committing code:

1. ✅ Run `bin/ecs check --fix` - Fix coding standards

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

3. ✅ Run `bin/phpunit` - All tests pass

4. ✅ Ensure proper file headers

5. ✅ Update documentation if needed

CI/CD Pipeline

GitHub Actions runs on every PR:

1. **Unit Tests** - PHP 8.4/8.5, MySQL 8.0, coverage reporting

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

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

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

Database & ORM

**Doctrine ORM 2.15+** with migrations

```bash

Create migration

bin/console doctrine:migrations:diff

Execute migration

bin/console doctrine:migrations:migrate

Validate schema

bin/console doctrine:schema:validate

```

**Entity Conventions:**

API Development

**API Platform 4.0+** for REST API

**Features:**

**Testing API endpoints:**

```php

class InvoiceApiTest extends ApiTestCase

{

public function testGetInvoice(): void

{

$this->createClient()->request('GET', '/api/invoices/1');

$this->assertResponseIsSuccessful();

$this->assertJsonContains(['@type' => 'Invoice']);

}

}

```

Security Considerations

Distribution Methods

1. **FrankenPHP** (Recommended) - Single binary with PHP, web server, and app code

2. **Docker** - Official images on Docker Hub (`solidinvoice/solidinvoice`)

3. **Archive** - ZIP/TAR with pre-compiled assets

Key Conventions

Additional Resources

When to Use This Skill

Use this skill when:

This skill provides comprehensive guidance on SolidInvoice's architecture, development workflow, testing strategy, and quality standards to ensure consistent, maintainable contributions.