Add suggestions in deprecation warnings

[Tac Tacelosky]

Feature Request

Q	A
New Feature	no
BC Break	no

Proposal

The deprecation messages don't provide instructions on how call the non-deprecated method. For example, what should be used instead of these two calls?

    /**
     * DEPRECATION WARNING! This method will be removed in the next major point release.
     *
     * @deprecated Since version 9.9.0
     * @codeCoverageIgnore
     *
     * Adds a single record to a CSV Document using PHP algorithm.
     *
     * @see https://php.net/manual/en/function.fputcsv.php
     */
    protected function addRecord(array $record): int|false
    {
        return $this->document->fputcsv($record, $this->delimiter, $this->enclosure, $this->escape, $this->newline);
    }

    /**
     * DEPRECATION WARNING! This method will be removed in the next major point release.
     *
     * @deprecated since version 9.8.0
     * @codeCoverageIgnore
     *
     * Format a record.
     *
     * The returned array must contain
     *   - scalar types values,
     *   - NULL values,
     *   - or objects implementing the __toString() method.
     */
    protected function formatRecord(array $record, callable $formatter): array
    {
        return $formatter($record);
    }

[ignace nyamagana butera]

@tacman thanks for using the package. As you might have noticed those methods:

• are internal used only inside the class hence they are marked as protected.
• are no longer used by the class.
• functionalities have been move directly inside the insertOne method if I remember correctly

From a maintainer POV, you should never have to deal with them only in the case if you went ahead and extended the Writer class which I would not recommend. I would strongly suggest using composition over inheritance. By doing so you would not even have to worry about those methods in the first place because as explained they are not part of the package public API for which SEMVER is fully respected.

As a rule of thumb, this kind of internal BC is only added in minor versions and it falls down onto the developper who indeed extended the class to maintain or fix any issues that comes with it.

[Tac Tacelosky]

Thanks, that makes sense.