[11.x] Multiplan swapping

[driesvints]

This PR adds support for multiplan swapping.

// Swap multiple plans at the same time...
$subscription->swap(['new-plan', 'other-plan']);

// Invoice immediately...
$subscription->swapAndInvoice(['new-plan', 'other-plan']);

// Provide extra subscription options...
$subscription->swap(
    ['new-plan', 'other-plan'],
    ['metadata' => ['key' => 'value']]
);

// Provide extra subscription item options...
$subscription->swap(
    ['new-plan' => ['quantity' => 5], 'other-plan'],
    ['metadata' => ['key' => 'value']]
);

Any old plan which isn't in the list during swapping will be removed from the subscription. Any existing plan will be kept.

You also swap individual subscription items:

// Swap an individual subscription item's plan to a different one...
$subscription->findOrFail('my-plan')->swap('other-plan');

// Invoice immediately...
$subscription->findOrFail('my-plan')->swapAndInvoice('other-plan');

Closes #912

[taylorotwell]

Upon looking at this I'm wondering if there was a significant reason you decided not to let plan options be specified in the first argument plan array... ['plan-name '=> ['options'], 'another-plan-without-options']

[driesvints]

@taylorotwell we definitely could do that. No specific reason. I'll update the PR on Monday 👍

[Xenonym]

@driesvints This is great! Thanks so much for putting this together so quickly.

I do wonder about the utility about the multiplan swap on a subscription, as in these functions:

$subscription->swap(['new-plan', 'other-plan']);
$subscription->swapAndInvoice(['new-plan', 'other-plan']);

As an example, suppose I have the following set of plans: plan_a, plan_a_addon1, plan_a_addon2, where the plan_a_addon* plans are add-ons for plan_a. $subscription has all three plans.

Now, suppose that I would like to switch $subscription from plan_a to plan_b. Because the prices for add-ons are tied to the plan, I also have to change plan_a_addon* to plan_2_addon*. I can't simply do $subscription->swap(['plan_b', 'plan_b_addon1', 'plan_b_addon2']) as I need to keep all other parameters on the add-on plans the same.

For the above example, it would be great if I could specify the "from" and "to" plans of each swap eg.:

$subscription->swap([
	'plan_a' => 'plan_b',
	'plan_a_addon1' => 'plan_b_addon1',
	'plan_a_addon2' => 'plan_b_addon2',
]);

The above method is more of a convenience, since I can still do the above swap by swapping on each subscription item individually. However, I don't quite see how the current swap methods on subscriptions are useful, since it's hard to come up with a situation where I want to swap the entire set of plans in a subscription without preserving the parameters of each of them in some way. It is more common for an upgrade or downgrade to apply to the entire subscription and its add-ons - hence, there are always parameters tied to each subscription item (eg. quantity, tax rates) that need to be kept the same after the swap.

[driesvints]

@Xenonym I actually think your use case is less common. If you need to persist data between plans it's probably best that you explicitly provide that in the options. Or do a swap on the item itself like you said.

In my opinion you'll always want new subscription item records when changing to a new plan. Opinions may differ here maybe.

[driesvints]

Stripe confirmed that the more common scenario is to deleted old subscription items and to create new ones so I'm going to leave the PR as is :)

[Xenonym]

@driesvints it's cool :) Like you said, I can do the swaps on the subscription items themselves anyway - this PR is good enough for my use!