[Core]: Watermark Background

Affected Area or Module

Watermark Background

Problem Statement

Specific
Implement a PDF-generation feature that applies a single, branded full-page background to every page of the document. The background must cover the entire printable area and sit behind all content, replacing the current “first-page-only” layout.

Proposed Solution

Measurable
For any generated PDF, 100% of pages show the same full-page background.
The background fully covers the printable area on each page

The background design on every page visually matches the current first-page template (same colors, gradient, and pattern).

Achievable
Use the existing PDF generation stack and available design assets to:
Add a reusable background layer/template.

Notes or context

No response

it_applies_a_full_page_background_to_every_page

Phase	Description
Arrange	Multi-page HTML fixture and a branded background asset
Act	Generate the PDF
Assert	Every page contains the background

it_covers_the_entire_printable_area_with_the_background

Phase	Description
Arrange	HTML fixture reaching page edges + background asset
Act	Generate the PDF
Assert	Background covers the full printable area on all pages

it_renders_the_background_behind_all_page_content

Phase	Description
Arrange	HTML including overlapping text and images
Act	Generate the PDF
Assert	All content renders above the background

it_uses_the_same_background_template_for_all_pages

Phase	Description
Arrange	Generator configured with a reusable background template
Act	Generate a multi-page PDF
Assert	Background appears on every page

it_matches_the_background_design_of_the_reference_template

Phase	Description
Arrange	Reference background/template
Act	Generate the PDF
Assert	Background visually matches the reference template

it_preserves_content_layout_when_the_background_is_applied

Phase	Description
Arrange	Layout-sensitive HTML (tables, positioned elements)
Act	Generate the PDF
Assert	Layout remains unchanged vs. baseline without background

it_supports_all_page_sizes_and_orientations

Phase	Description
Arrange	Fixtures for A4 portrait, A4 landscape, and Letter
Act	Generate PDFs for each format
Assert	Background scales and positions correctly for each page setup

it_displays_transparent_backgrounds_correctly

Phase	Description
Arrange	Background asset containing transparency
Act	Generate the PDF
Assert	Content remains visible and transparency displays correctly

it_gracefully_handles_missing_or_invalid_background_assets

Phase	Description
Arrange	Generator configured with a missing or invalid background asset
Act	Generate the PDF
Assert	PDF is still generated; error is logged; content pages present

@coderabbitai make pull-request with AAA test Scenario's: Arrange, Act, Assert. And also make sure you test edge cases

@coderabbitai make implementation plan with test Scenario's: Arrange, Act, Assert. And also make sure you test edge cases

Warning

The ticket references a "current first-page-only layout" and "current first-page template" that need to be replaced or matched, but exploration confirms no such implementations exist in the codebase. The ticket assumes "available design assets" (backgrounds, gradients, patterns) that would be used for the watermark, but none were found in any asset directories (public/, storage/, resources/, custom/). Without the reference design/template or actual background assets, it's impossible to implement a feature that must "visually match" something that doesn't exist.

You can reply directly to this comment with additional context or clarifications to help CodeRabbit complete the planning task, with an @-mention to the bot.

Test Suggestions

Added to support future implementation of this request. The issue body is unchanged.

The Problem Statement assumes a "current first-page-only" background layout exists and needs extending to every page — that assumption doesn't hold today. As covered in #95: Modules\Core\Services\PdfGenerationService is an empty stub, and no code in Modules/Invoices or Modules/Quotes renders a PDF at all yet (the domPDF/wkhtmltopdf drivers under Modules\Core\Support\PDF exist but aren't called from anywhere). There is no first-page background today to replace — this and #95 are really the same underlying gap (no PDF template pipeline exists) surfacing as two different feature requests. Whoever picks this up should build the background-layer support into the PDF pipeline from the start rather than trying to "extend" a first-page implementation that isn't there.

PHPUnit: it_renders_the_same_background_on_every_page_of_a_multi_page_invoice()

#[Test]
public function it_renders_the_same_background_on_every_page_of_a_multi_page_invoice(): void
{
    /* Arrange */
    $invoice = Invoice::factory()
        ->for($this->company)
        ->has(InvoiceItem::factory()->count(60), 'invoiceItems')
        ->create();

    /* Act */
    $html = app(PdfGenerationService::class)->renderInvoiceHtml($invoice);

    /* Assert */
    $this->assertStringContainsString('background-repeat', $html);
}

PHPUnit: it_applies_the_companys_configured_watermark_image()

#[Test]
public function it_applies_the_companys_configured_watermark_image(): void
{
    /* Arrange */
    $this->company->update(['watermark_path' => 'watermarks/acme.png']);
    $invoice = Invoice::factory()->for($this->company)->create();

    /* Act */
    $html = app(PdfGenerationService::class)->renderInvoiceHtml($invoice);

    /* Assert */
    $this->assertStringContainsString('watermarks/acme.png', $html);
}

PHPUnit: it_renders_without_a_watermark_when_none_is_configured()

#[Test]
public function it_renders_without_a_watermark_when_none_is_configured(): void
{
    /* Arrange */
    $this->company->update(['watermark_path' => null]);
    $invoice = Invoice::factory()->for($this->company)->create();

    /* Act */
    $html = app(PdfGenerationService::class)->renderInvoiceHtml($invoice);

    /* Assert */
    $this->assertStringNotContainsString('background-image', $html);
}

Edge cases worth covering: the wkhtmltopdf driver historically has weaker CSS background-image support than dompdf, so this may render inconsistently between the two drivers in Modules\Core\Support\PDF\Drivers, and a watermark image large enough to noticeably slow down PDF generation on multi-page documents.

Navigation Menu

Repository navigation

[Core]: Watermark Background #131

Affected Area or Module

Problem Statement

Proposed Solution

Notes or context

it_applies_a_full_page_background_to_every_page

it_covers_the_entire_printable_area_with_the_background

it_renders_the_background_behind_all_page_content

it_uses_the_same_background_template_for_all_pages

it_matches_the_background_design_of_the_reference_template

it_preserves_content_layout_when_the_background_is_applied

it_supports_all_page_sizes_and_orientations

it_displays_transparent_backgrounds_correctly

it_gracefully_handles_missing_or_invalid_background_assets

Test Suggestions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Core]: Watermark Background #131

Description

Affected Area or Module

Problem Statement

Proposed Solution

Notes or context

Activity

nielsdrost7 commented on Nov 19, 2025

it_applies_a_full_page_background_to_every_page

it_covers_the_entire_printable_area_with_the_background

it_renders_the_background_behind_all_page_content

it_uses_the_same_background_template_for_all_pages

it_matches_the_background_design_of_the_reference_template

it_preserves_content_layout_when_the_background_is_applied

it_supports_all_page_sizes_and_orientations

it_displays_transparent_backgrounds_correctly

it_gracefully_handles_missing_or_invalid_background_assets

nielsdrost7 commented on Jan 2, 2026

nielsdrost7 commented on Jan 3, 2026

coderabbitai commented on Jan 3, 2026

nielsdrost7 commented on Jul 16, 2026

Test Suggestions

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions