From 37d5480755349247d944d181fed7fe5c0ea8f85d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 31 May 2026 10:54:53 +0000 Subject: [PATCH 1/3] Add v2.0 deprecation warnings to removed APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mark the five APIs removed in v2.0 with @deprecated docblocks and E_USER_DEPRECATED trigger_error() calls so users upgrading from 1.x receive runtime and static-analysis notice of what needs to change: - SubscribableApplicationServiceProvider — replaced by a published plain stub - Subscriber::userModel() — replaced by polymorphic URL-based model resolution - SubscriberMailChannel — replaced by SubscribableMailMessage::via() explicit opt-in - CheckSubscriptionStatusBeforeSendingNotifications — tied to SubscriberMailChannel - CheckNotifiableSubscriptionStatus — tied to SubscriberMailChannel Each deprecation message links to the relevant section of UPGRADE.md. --- src/Channels/SubscriberMailChannel.php | 13 +++++++++++++ .../CheckNotifiableSubscriptionStatus.php | 6 ++++++ ...ubscriptionStatusBeforeSendingNotifications.php | 6 ++++++ src/SubscribableApplicationServiceProvider.php | 14 ++++++++++++++ src/Subscriber.php | 11 +++++++++++ 5 files changed, 50 insertions(+) diff --git a/src/Channels/SubscriberMailChannel.php b/src/Channels/SubscriberMailChannel.php index 3f4982e..d963f74 100644 --- a/src/Channels/SubscriberMailChannel.php +++ b/src/Channels/SubscriberMailChannel.php @@ -11,6 +11,12 @@ use YlsIdeas\SubscribableNotifications\Contracts\CheckNotifiableSubscriptionStatus; use YlsIdeas\SubscribableNotifications\Contracts\CheckSubscriptionStatusBeforeSendingNotifications; +/** + * @deprecated v1.x will be removed in v2.0. Automatic unsubscribe-link injection via a custom + * MailChannel is replaced by explicit opt-in: return SubscribableMailMessage::via($notifiable, $this) + * from your notification's toMail() method instead. + * See the upgrade guide: UPGRADE.md + */ class SubscriberMailChannel extends MailChannel { /** @@ -29,6 +35,13 @@ class SubscriberMailChannel extends MailChannel */ public function send($notifiable, Notification $notification) { + trigger_error( + 'SubscriberMailChannel is deprecated and will be removed in v2.0.' + . ' Return SubscribableMailMessage::via($notifiable, $this) from your notification\'s' + . ' toMail() method to opt in to unsubscribe-link injection explicitly.', + E_USER_DEPRECATED + ); + // Check if the user would want the mail if ($notifiable instanceof CheckSubscriptionStatusBeforeSendingNotifications && $notification instanceof CheckNotifiableSubscriptionStatus && diff --git a/src/Contracts/CheckNotifiableSubscriptionStatus.php b/src/Contracts/CheckNotifiableSubscriptionStatus.php index f754a16..62fbca6 100644 --- a/src/Contracts/CheckNotifiableSubscriptionStatus.php +++ b/src/Contracts/CheckNotifiableSubscriptionStatus.php @@ -2,6 +2,12 @@ namespace YlsIdeas\SubscribableNotifications\Contracts; +/** + * @deprecated v1.x will be removed in v2.0. Subscription gating is now handled by + * SubscribableMailMessage::via() rather than the SubscriberMailChannel. + * Remove this interface from your notifications. + * See the upgrade guide: UPGRADE.md + */ interface CheckNotifiableSubscriptionStatus { public function checkMailSubscriptionStatus(): bool; diff --git a/src/Contracts/CheckSubscriptionStatusBeforeSendingNotifications.php b/src/Contracts/CheckSubscriptionStatusBeforeSendingNotifications.php index 303b47f..10a7898 100644 --- a/src/Contracts/CheckSubscriptionStatusBeforeSendingNotifications.php +++ b/src/Contracts/CheckSubscriptionStatusBeforeSendingNotifications.php @@ -4,6 +4,12 @@ use Illuminate\Notifications\Notification; +/** + * @deprecated v1.x will be removed in v2.0. Subscription gating is now handled by + * SubscribableMailMessage::via() rather than the SubscriberMailChannel. + * Remove this interface from your models. + * See the upgrade guide: UPGRADE.md + */ interface CheckSubscriptionStatusBeforeSendingNotifications { public function mailSubscriptionStatus(Notification $notification): bool; diff --git a/src/SubscribableApplicationServiceProvider.php b/src/SubscribableApplicationServiceProvider.php index 86fdac0..5d25038 100644 --- a/src/SubscribableApplicationServiceProvider.php +++ b/src/SubscribableApplicationServiceProvider.php @@ -4,6 +4,11 @@ use Illuminate\Support\ServiceProvider; +/** + * @deprecated v1.x will be removed in v2.0. Publish the subscriber-provider stub and configure + * Subscriber callbacks directly in your own service provider's boot() method instead. + * See the upgrade guide: UPGRADE.md + */ abstract class SubscribableApplicationServiceProvider extends ServiceProvider { /** @@ -18,6 +23,15 @@ abstract class SubscribableApplicationServiceProvider extends ServiceProvider public function boot() { + trigger_error( + sprintf( + '%s is deprecated and will be removed in v2.0. Publish the subscriber-provider stub' + . ' and configure Subscriber callbacks directly in your boot() method instead.', + static::class + ), + E_USER_DEPRECATED + ); + if ($this->loadRoutes === true) { $this->loadRoutes(); } diff --git a/src/Subscriber.php b/src/Subscriber.php index 8da2293..3d2e594 100644 --- a/src/Subscriber.php +++ b/src/Subscriber.php @@ -74,11 +74,22 @@ public function routeName() } /** + * @deprecated v1.x will be removed in v2.0. Model resolution is now polymorphic via the URL. + * Remove all Subscriber::userModel() calls and add a morph map instead. + * See the upgrade guide: UPGRADE.md + * * @param string|null $model * @return string|null */ public function userModel(?string $model = null) { + trigger_error( + 'Subscriber::userModel() is deprecated and will be removed in v2.0.' + . ' Model resolution is now polymorphic via the URL.' + . ' Remove all userModel() calls and register a morph map instead.', + E_USER_DEPRECATED + ); + if ($model) { $this->userModel = $model; From e15c057b40acfed1687614ed4c935b04adc656ca Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 10:38:12 +0000 Subject: [PATCH 2/3] Add PHPStan baseline entry for intentional SubscriberMailChannel deprecation SubscribableServiceProvider references SubscriberMailChannel::class to bind it in the container. The class is intentionally deprecated for v2.0, so the resulting phpstan-deprecation-rules error is expected and should be silenced via the baseline rather than removed. --- phpstan-baseline.neon | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon index b3b43df..f3b68fb 100644 --- a/phpstan-baseline.neon +++ b/phpstan-baseline.neon @@ -5,3 +5,8 @@ parameters: identifier: trait.unused count: 1 path: src/MailSubscriber.php + - + message: '#^Access to constant on deprecated class YlsIdeas\\SubscribableNotifications\\Channels\\SubscriberMailChannel#' + identifier: classConstant.deprecatedClass + count: 1 + path: src/SubscribableServiceProvider.php From f993b3ded0e844834094465a3166e09c02841c1a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 11:29:09 +0000 Subject: [PATCH 3/3] Mark Facade userModel() and legacy stub as deprecated - Add @deprecated inline tag to the Subscriber facade's userModel() @method docblock so IDEs surface the deprecation when called via the facade - Add deprecation comment to the SubscribableServiceProvider stub so users who publish it get an immediate hint to migrate to the v2 plain-stub approach --- src/Facades/Subscriber.php | 2 +- stubs/SubscribableServiceProvider.stub | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/Facades/Subscriber.php b/src/Facades/Subscriber.php index 93776a8..0e0f87a 100644 --- a/src/Facades/Subscriber.php +++ b/src/Facades/Subscriber.php @@ -12,7 +12,7 @@ * * @method static void routes() * @method static string routeName() - * @method static mixed userModel(string $model = null) + * @method static mixed userModel(string $model = null) @deprecated v1.x will be removed in v2.0. Remove all userModel() calls; model resolution is now polymorphic via the URL. * @method static void onCompletion(callable|string $handler) * @method static void onUnsubscribeFromMailingList(callable|string $handler) * @method static void onUnsubscribeFromAllMailingLists(callable|string $handler) diff --git a/stubs/SubscribableServiceProvider.stub b/stubs/SubscribableServiceProvider.stub index 7baeb38..d004814 100644 --- a/stubs/SubscribableServiceProvider.stub +++ b/stubs/SubscribableServiceProvider.stub @@ -1,5 +1,9 @@