Add ability to update Subscription Items with different proration modes for addition and removal.

[HelgeSverre]

Summary

This PR introduces a new method updateItemsWithDifferentProration to the Subscription model.

It allows the consumer of the package to specify the proration mode to be used for adding new items or incrementing the quantity of existing items already on the subscription, with a separate proration mode than removing items or decrementing the quantity of existing items.

Why

In non-trivial subscription scenarios, it is sometimes desirable to apply different proration behaviors for addition and removal of a item on a subscription,

A Specific example of this is the following scenario:

• A customer has a subscription with a monthly billing cycle.
• The customer has a subscription with 3 items with a quantity of 1 each.
  • Item 1 - SaaS license - Light Version
  • Item 2 - Add-on - Extra Storage (+1gb)
  • Item 3 - Add-on - Ability to use the API
• The customer wants to add additional storage to their subscription. (increment the quantity of the existing item)
• The customer no longer needs the API access and wants to remove it from their subscription. (remove the existing item)
• The billing date is the 1. of each month, the customer performs the actions on the 15th of the month. (aka half month has passed)

In this scenario, the following is expected:

• Item 1 - no change is done to the SaaS license.
• Item 2 - Customer is charged for rest of the month, (aka prorated_immediately on addition of item)
• Item 3 - Customer is not refunded for half the month, but rather keeps the API Access until it lapses at the end of the month. (aka full_next_billing_period on removal of item)

Usage

$subscription->updateItemsWithDifferentProration(
    items: [
        ['price_id' => '123', 'quantity' => 2],
        ['price_id' => '456', 'quantity' => 1],
    ],
    additionProrationBehaviour: 'prorated_immediately',
    removalProrationBehaviour: 'full_next_billing_period'
);

Etc

The logic could probably be simplified a bit, but i have provided tests for various scenarios so we can refactor it if needed.

Fully understand if this use-case is too niche to put in "core", but it's fairly common practice for B2B SaaS, and is a PITA to implement with Paddle.

(Package does not have pint, so my editor messed with the formatting, assuming this will be auto-fixed by GitHub actions)

[github-actions[bot]]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[taylorotwell]

Too many other formatting changes here.

[HelgeSverre]

Shall reformat and resubmit later, is this repo using the default pint with Laravel preset?