Undocumented breaking change in 2.3.6 - \Magento\Sales\Model\Order\Pdf\Invoice class

[pixel-paul]

Summary (*)

After upgrading from 2.3.5-p1 to 2.3.6 an undocumented breaking change was introduced to the \Magento\Sales\Model\Order\Pdf\Invoice class. This prevents invoices from being printed if the class has been extended.

Ref: https://devdocs.magento.com/guides/v2.3/release-notes/backward-incompatible-changes/reference.html

Examples (*)

Before (2.3.5-p1):

public function __construct(
....
\Magento\Framework\Locale\ResolverInterface $localeResolver,
....

public function getPdf($invoices = []) {
..............
if ($invoice->getStoreId()) {
    $this->_localeResolver->emulate($invoice->getStoreId());
    $this->_storeManager->setCurrentStore($invoice->getStoreId());
 }
.........
if ($invoice->getStoreId()) {
    $this->_localeResolver->revert();
 }

After (2.3.6):

/**
* @var \Magento\Store\Model\App\Emulation
*/
private $appEmulation;

public function __construct(
....
\Magento\Store\Model\App\Emulation $appEmulation,
....

if ($invoice->getStoreId()) {
    $this->appEmulation->startEnvironmentEmulation(
    $invoice->getStoreId(),
     \Magento\Framework\App\Area::AREA_FRONTEND,
    true
    );
    $this->_storeManager->setCurrentStore($invoice->getStoreId());
}
......................
if ($invoice->getStoreId()) {
    $this->appEmulation->stopEnvironmentEmulation();
}

Because of this change and the introduction of a private function, extending this class has significantly changed.

Proposed solution

Ensure breaking changes are documented

---

• Severity: S3 - Affects non-critical data or functionality and does not force users to employ a workaround.

[m2-assistant]

Hi @pixel-paul. Thank you for your report.
To help us process this issue please make sure that you provided the following information:

• Summary of the issue
• Information on your environment
• Steps to reproduce
• Expected and actual results

Please make sure that the issue is reproducible on the vanilla Magento instance following Steps to reproduce. To deploy vanilla Magento instance on our environment, please, add a comment to the issue:

@magento give me 2.4-develop instance - upcoming 2.4.x release

For more details, please, review the Magento Contributor Assistant documentation.

Please, add a comment to assign the issue: @magento I am working on this

---

• Join Magento Community Engineering Slack and ask your questions in #github channel.

⚠️ According to the Magento Contribution requirements, all issues must go through the Community Contributions Triage process. Community Contributions Triage is a public meeting.

🕙 You can find the schedule on the Magento Community Calendar page.

📞 The triage of issues happens in the queue order. If you want to speed up the delivery of your contribution, please join the Community Contributions Triage session to discuss the appropriate ticket.

🎥 You can find the recording of the previous Community Contributions Triage on the Magento Youtube Channel

✏️ Feel free to post questions/proposals/feedback related to the Community Contributions Triage process to the corresponding Slack Channel

[ihor-sviziev]

@gabrieldagama @sidolov could you move this issue to https://github.com/magento/devdocs repo?

[webr]

Experienced this issue when upgrading this week too, having extended the Invoice and Shipment models.

The issue is the $appEmulation attribute being private, having replaced the $_localeResolver attribute which was protected. It makes it not possible to extend/override the getPdf method (unless you also extend the __construct method and re-declare the $appEmulation attribute, which seems messy).

I don't see this as purely a documentation problem. Correct me if I'm wrong but couldn't this simply be fixed by the new attribute being changed to protected? Its only use in the class is in a public function. I don't see why $appEmulation has to be private.

[ihor-sviziev]

Hi, Unfortunately making new properties is considered as backward incompatible change as someone could have another property with the same name but different object type

…

On Sun, 22 Nov 2020 at 16:36 Rik Weber ***@***.***> wrote: Experienced this issue when upgrading this week too, having extended the Invoice and Shipment models. The issue is the $appEmulation attribute being private, having replaced the $_localeResolver attribute which was protected. It makes it not possible to extend/override the getPdf method (unless you also extend the __construct method and re-declare the $appEmulation attribute, which seems messy). I don't see this as purely a documentation problem. Correct me if I'm wrong but couldn't this simply be fixed by the new attribute being changed to protected? Its only use in the class is in a public function. I don't see why $appEmulation has to be private. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <https://github.com/magento/magento2/issues/30965#issuecomment-731757636>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOJOUIP5C6ATQSGCNIXQBLSREOVLANCNFSM4TZ2B3KA> .

[webr]

@ihor-sviziev I guess I understand the justification in theory, but I would bet money on more Magento installs being broken by their getPdf override now throwing an error, than Magento installs that have extended one of the Pdf classes AND happen to have a new attribute called $appEmulation...

[ihor-sviziev]

Hi @webr,
If you have some ideas how to improve it in backward compatible manner - let us know.

[pixel-paul]

Breaking changes such as these should not be introduced in a minor point release. And if they are required for a specific reason, they should be clearly highlighted and documented.

As a quick-fix workaround, this issue can be bypassed by removing the if statements in the getPdf() function.

Note: this will only work if you have one store on the affected site.

Remove these lines from the getPdf() function:

/*if ($invoice->getStoreId()) {
    $this->_localeResolver->emulate($invoice->getStoreId());
    $this->_storeManager->setCurrentStore($invoice->getStoreId());
}*/

/*if ($invoice->getStoreId()) {
    $this->_localeResolver->revert();
}*/

[ihor-sviziev]

Hi @pixel-paul,
I do agree with you that it should be highlighted, so it's better to update docs, that's why I suggested to move this issue to devdocs repo. @gabrieldagama @sidolov @sivaschenko could you do so?

As I said before - reverting these changes will re-introduce the fixes issue back and will cause one more time backward incompatible changes, so it's better to keep the changes as is.

[m2-assistant]

Hi @pixel-paul. Thank you for your report.
To help us process this issue please make sure that you provided sufficient information.

Please, add a comment to assign the issue: @magento I am working on this

---

• Join Magento Community Engineering Slack and ask your questions in #github channel.

[erikmarr]

@maghamed can you please take a look at this issue and recommend someone who can help with documentation?

[dshevtsov]

NOTE
The reported change wasn't detected by our automation. See #8316
This should be considered at magento/magento-semver#34.

[hostep]

If people end up here from a search engine, here's how we solved the constructor problem if you have a module which needs to support both Magento 2.3.5 and 2.3.6: magento/magento2#30684 (comment)

[jfrontain]

@pixel-paul, thanks for bringing this issue to our attention. I've updated the 2.3.6 release notes and will close this issue now. Let us know if we need to add additional information -- we want to get this right! Thanks again.

[pixel-paul]

@jfrontain - thanks for updating the breaking changes. I'm sure that will help people with updating. For me, this wasn't operationally a big deal, although I had to spend quite a bit of time debugging etc. to figure out the problem and then a solution.

I appreciate on such a big project, keeping track of all the breaking changes must be a major challenge, however it's still not clear why such a change was made on a minor point release. Are you are following semver 2? If so, you can't 'BC Break' a minor release or patch version......

[jfrontain]

Actually, @pixel-paul, I wrote too quickly and mixed up this BiC with another issue. I'm re-opening this issue and will follow up today. Tracking these types of changes is a challenge, and we appreciate your help and patience.

[jfrontain]

Okay, the 2.3.6 release notes have been updated. Here's the PR: https://github.com/magento-commerce/devdocs/pull/2164