Feat/preserve duplicate file basenames

[Nitram1123]

Q	A
Gotenberg API version ?	8.x
Bug fix ?	yes
New feature ?	no
BC break ?	no
Issues	Fix #264

Description

By default, nothing changes. MergePdfBuilder::files() still deduplicates by resolved path and lets Gotenberg sort uploads alphanumerically by basename.
Files that share the same basename keep overwriting each other silently.

$pdf->merge()
    ->files('/a/report.pdf', '/b/report.pdf', '/a/report.pdf')
    ->generate();
// one file named 'report.pdf'

New opt-in: keep every file
allowDuplicates() opts in to disambiguating colliding basenames with a zero-padded suffix inserted before the extension, so every file actually reaches Gotenberg:

$pdf->merge()
    ->allowDuplicates()
    ->files('/a/report.pdf', '/b/report.pdf')
    ->generate();
// report.pdf, report000001.pdf

Gotenberg still sorts alphanumerically by basename. When the original basename already ends with digits (e.g. report_1.pdf), the suffixed sibling (report_1000001.pdf) is read as a larger integer and drifts to the end of the merge — so the order is preserved but not always the one the user expects.
Guaranteed call order
For a deterministic order, combine allowDuplicates() with sortFilesByCall(). Each filename is then prefixed with its call index (%06d-), which is alphanumerically stable regardless of the original basename:

$pdf->merge()
    ->allowDuplicates()
    ->sortFilesByCall()
    ->files('/reports/q4.pdf', '/cover.pdf', '/reports/q4.pdf')
    ->generate();
// 000001-q4.pdf, 000002-cover.pdf, 000003-q4.pdf

[Jean-Beru]

Already proposed in #277, right?

[Nitram1123]

Yes exactly this branch is based on #277.

[Jean-Beru]

What about a single method dedupeFiles(bool $dedupe): self ?

[Nitram1123]

Yes, that’s probably a good idea. I was thinking of doing it like the sort methods, but it’s more of a boolean-based approach.

[Neirda24]

why not enum then ?

[Jean-Beru]

Is it worth it since it's purely internal to this trait?

[Neirda24]

then boolean seems safer if there are only 2 possible usecases

[Jean-Beru]

OK for bool, it could be changed later. Also, we could mark these properties as internal since builder can see them.

[Nitram1123]

For me, sorting is not really a boolean concern, because we never know if we might need a third sorting strategy later.
The value never leaves this trait and isn't part of the public API, so an enum felt like overkill. A private constant would have been my preferred option, but trait constants were only introduced in PHP 8.2 and we still support PHP 8.1.

[Neirda24]

so it means it replace the use FilesTrait in the final builder class. Let's see if there is a way to properly document this or maybe prevent errors using phpstan. Because they are mutually exclusive

[Nitram1123]

PHP already prevents the error at load time. As soon as a class does use FilesTrait and use FilesOrderTrait composition fails with a fatal ...

[Neirda24]

this looks like a BC. Am I wrong ?

[Jean-Beru]

Not sure since DataPart will retrieve basename from the File instance given

    // DataPart
    public function __construct($body, ?string $filename = null, ?string $contentType = null, ?string $encoding = null)
    {
        if ($body instanceof File && !$filename) {
            $filename = $body->getFilename();
        }

    // File
    public function __construct(
        private string $path,
        private ?string $filename = null,
    ) {
    }

    public function getFilename(): string
    {
        return $this->filename ??= basename($this->getPath());
    }

So, I'm wondering if this change is needed 🤔

[Nitram1123]

I finally refactored it to put the change directly in the FilesOrderTrait. I feel like that’s safer.
Let me know if that works for you.