SolidInvoice Development Assistant

You are assisting with development on **SolidInvoice**, a sophisticated open-source invoicing application for small businesses and freelancers. This skill provides comprehensive guidance on the codebase architecture, conventions, workflows, and best practices.

Project Context

**SolidInvoice** is built with:

**Key Features**: Client management, quotes, invoices (including recurring), payment processing (Payum), tax/discount handling, RESTful API, multi-channel notifications.

Architecture Principles

1. Modular Bundle Architecture

**Core Bundles**:

2. Action Pattern (Not Controllers)

```php

class CreateAction

{

public function __invoke(Request $request): Response

{

// Handle invoice creation

}

}

```

3. Event-Driven Architecture

4. State Machine (Workflow)

5. Common Entity Traits

Bundle Internal Structure

Standard layout for each bundle:

```

BundleNameBundle/

├── Action/ # HTTP entry points

├── Entity/ # Doctrine ORM entities

├── Form/ # Symfony Form types

├── Listener/ # Event listeners/subscribers

├── Manager/ # Complex business logic

├── Repository/ # Database access objects

├── Resources/

│ ├── config/ # Bundle configs & routing

│ ├── translations/ # Translation files

│ └── views/ # Twig templates

└── Tests/

├── Functional/ # Integration tests

└── (Unit tests) # Top-level test directory

```

Development Workflow

Initial Setup

```bash

Clone and setup

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

cd SolidInvoice

composer install

bun install

bun run dev

Database setup

bin/console doctrine:database:create

bin/console doctrine:migrations:migrate

```

Common Commands

**Frontend**:

```bash

bun run dev # Development mode 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 (PSR-12, Symfony)

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

bin/phpstan analyse # Static analysis (Level 6)

bin/rector process # Apply PHP/Symfony refactoring

```

**Testing**:

```bash

bin/phpunit # Run all tests

bin/phpunit --filter testName # Run specific test

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

```

Code Quality Standards

File Headers (Required)

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.

*/

```

Coding Standards

Static Analysis

Testing Requirements

Testing Strategy

Test Types

**Unit Tests** (top-level in `Tests/`):

```php

use Mockery as m;

class InvoiceManagerTest extends TestCase

{

public function testCreateInvoice(): void

{

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

// Test logic with mocked dependencies

}

}

```

**Functional Tests** (`Tests/Functional/`):

**API Tests** (`Tests/Functional/Api/`):

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

Pre-Commit Checklist

Before committing code:

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

2. ✅ Run `bin/phpstan analyse` - Pass static analysis

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

4. ✅ Ensure proper file headers

5. ✅ Update tests for new functionality

6. ✅ Validate database schema if entities changed

CI/CD Pipeline

Every pull request triggers:

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

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

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

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

Key Conventions

Naming

Dependency Injection

Database Migrations

```bash

After modifying entities

bin/console doctrine:migrations:diff # Generate migration

bin/console doctrine:migrations:migrate # Apply migration

```

Common Development Tasks

Adding a New Feature

1. Identify appropriate bundle (or create new one)

2. Create Action class in `Action/` directory

3. Define route in `Resources/config/routing/`

4. Implement business logic in Manager or service

5. Add entity/repository if needed

6. Create form types in `Form/`

7. Add Twig templates in `Resources/views/`

8. Write tests in `Tests/Functional/` and unit tests

9. Run quality checks

Working with Money

Always use Money value objects from `moneyphp/money`:

```php

use Money\Money;

use Money\Currency;

$amount = new Money(5000, new Currency('USD')); // $50.00

```

Working with Workflows

Invoice state transitions use Symfony Workflow:

```php

$workflow->apply($invoice, 'send'); // Transition to 'sent' state

```

Security Considerations

Distribution Methods

1. **Docker** (Recommended) - FrankenPHP-based image on Docker Hub

2. **FrankenPHP Binary** - Single binary with PHP, web server, and app code

3. **Archive** (ZIP/TAR) - Manual installation with pre-compiled assets

Helpful Resources

Guidelines for AI Assistance

When helping with SolidInvoice:

1. **Respect the architecture** - Use Action pattern, not traditional controllers

2. **Follow bundle conventions** - Place files in correct directories

3. **Maintain code quality** - Always run ECS, PHPStan, and tests

4. **Use proper file headers** - Include copyright notice

5. **Write tests** - Cover new functionality with unit and functional tests

6. **Event-driven approach** - Use events for cross-bundle communication

7. **Money handling** - Always use Money value objects, never floats

8. **Database changes** - Generate migrations for entity modifications

9. **Dependency injection** - Never instantiate services manually

10. **Security first** - Validate input, escape output, follow Symfony security best practices