Refactor Rename

[ramchale]

Q	A
Documentation	no
Bugfix	no
BC Break	yes
New Feature	no
RFC	no
QA	no

Description

Refactoring for #177

I had a couple of questions around the intent for v3;

• I'm assuming removal of getFile and setFile, but wanted to check if we're also removing addFile
• Currently the input for addFile can be a string, or array of target, etc, or an array of arrays of target, etc. Which of these do we want to support going forward?

[gsteel]

I'm not entirely sure because I haven't had a decent look at it myself, but:

• Make use of Laminas\Filter\File\FileInformation value object which exists to handle the 3 possible argument types of string|PHP $_FILES|PSRUpload
• I think ideally, expect a single input, i.e. 1 path, or 1 PSR Upload or 1 PHP Upload and return a string representing the new, modified file path (Or un-filtered input)
• We may have revise, that, i.e. we might need to accept multiple inputs for PSR/$_FILES but I'd rather avoid that if possible because we then have awkward return type expectations, IMO, successful filtering should === (string) $newFilePath
• If there is a public method other than filter or __invoke, kill it with 🔥

My reasoning here is that we shouldn't need to worry too much about compat with input filter and form, because they are next in line for major release, and, if you want to deal with multiple uploads, then, from input filters perspective, we should be looking at an 'ArrayInput' wrapping n 'FileInput's rather than all this type juggling.

Options:

• I think target should exclusively mean "Target Directory"
• source does not make sense and I think it should be removed - the "source" is the filter input
• overwrite and randomize seem sensible enough

Further reference:

• Existing Filter Docs: https://docs.laminas.dev/laminas-filter/v2/file/#rename
• File uploads with input filter: https://docs.laminas.dev/laminas-inputfilter/file-input/
• File uploads with form: https://docs.laminas.dev/laminas-form/v3/file-upload/

cc @froschdesign @weierophinney

[froschdesign]

@gsteel

• source does not make sense and I think it should be removed - the "source" is the filter input

The source option is relevant if several files are to be filtered, see the example in the documentation:

$filter = new \Laminas\Filter\File\Rename([
    [
        'source'    => 'fileA.txt'
        'target'    => '/dest1/newfileA.txt',
        'overwrite' => true,
    ],
    [
        'source'    => 'fileB.txt'
        'target'    => '/dest2/newfileB.txt',
        'randomize' => true,
    ],
]);

But I would follow your idea and the source option is no longer needed:

I think ideally, expect a single input, i.e. 1 path, or 1 PSR Upload or 1 PHP Upload and return a string representing the new, modified file path (Or un-filtered input)

I also think that is the right way to go:

if you want to deal with multiple uploads, then, from input filters perspective, we should be looking at an 'ArrayInput' wrapping n 'FileInput's rather than all this type juggling.

---

If several values are to be filtered, a decorator can still be created for this purpose.