From 475da05e99395b1754f8263699e5a02d3fa1f13e Mon Sep 17 00:00:00 2001 From: Hugo Alliaume Date: Tue, 3 Jun 2025 20:41:58 +0200 Subject: [PATCH] [Swup] Deprecate the package --- src/Swup/CHANGELOG.md | 4 + src/Swup/README.md | 108 ++++++++++++++++++ src/Swup/doc/index.rst | 8 ++ .../src/DependencyInjection/SwupExtension.php | 2 + src/Swup/src/SwupBundle.php | 2 + ux.symfony.com/tests/baseline-ignore | 1 + 6 files changed, 125 insertions(+) diff --git a/src/Swup/CHANGELOG.md b/src/Swup/CHANGELOG.md index 32d23f3d22e..fc64ba59c87 100644 --- a/src/Swup/CHANGELOG.md +++ b/src/Swup/CHANGELOG.md @@ -1,5 +1,9 @@ # CHANGELOG +## 2.27.0 + +- Deprecate the package + ## 2.13.2 - Revert "Change JavaScript package to `type: module`" diff --git a/src/Swup/README.md b/src/Swup/README.md index 4d2056ccda5..ce26a792a1f 100644 --- a/src/Swup/README.md +++ b/src/Swup/README.md @@ -1,5 +1,113 @@ # Symfony UX Swup +> [!WARNING] +> **Deprecated**: This package has been **deprecated** in 2.x and will be removed in the next major version. + +We +To keep the same functionality in your Symfony application, follow these migration steps: + +1. Install the `swup` library and its plugins: + +```bash +# If using Symfony AssetMapper: +php bin/console importmap:require swup @swup/fade-theme @swup/slide-theme @swup/forms-plugin @swup/debug-plugin + +# If using NPM (e.g.: with Webpack Encore): +npm install swup @swup/fade-theme @swup/slide-theme @swup/forms-plugin @swup/debug-plugin +``` + +2. Add the following code to your app: + +
assets/controllers/swup_controller.js + +```javascript +import { Controller } from '@hotwired/stimulus'; +import Swup from 'swup'; +import SwupFadeTheme from '@swup/fade-theme'; +import SwupSlideTheme from '@swup/slide-theme'; +import SwupFormsPlugin from '@swup/forms-plugin'; +import SwupDebugPlugin from '@swup/debug-plugin'; + +export default class extends Controller { + static values = { + containers: Array, + mainElement: String, + animateHistoryBrowsing: Boolean, + animationSelector: String, + cache: Boolean, + linkSelector: String, + theme: String, + debug: Boolean, + }; + + connect() { + const dataContainers = this.containersValue; + const mainElement = this.mainElementValue || dataContainers[0] || '#swup'; + const allElements = [mainElement].concat(dataContainers); + const containersList = allElements.filter((item, index) => { + return allElements.indexOf(item) === index; + }); + + const options = { + containers: containersList, + plugins: [ + 'slide' === this.themeValue + ? new SwupSlideTheme({ mainElement: mainElement }) + : new SwupFadeTheme({ mainElement: mainElement }), + new SwupFormsPlugin(), + ], + }; + + if (this.hasMainElementValue) { + options.mainElement = this.mainElementValue; + } + + if (this.hasAnimateHistoryBrowsingValue) { + options.animateHistoryBrowsing = this.animateHistoryBrowsingValue; + } + if (this.hasAnimationSelectorValue) { + options.animationSelector = this.animationSelectorValue; + } + if (this.hasCacheValue) { + options.cache = this.cacheValue; + } + if (this.hasLinkSelectorValue) { + options.linkSelector = this.linkSelectorValue; + } + if (this.debugValue) { + options.plugins.push(new SwupDebugPlugin()); + } + + this.dispatchEvent('pre-connect', { options }); + const swup = new Swup(options); + this.dispatchEvent('connect', { swup, options }); + } + + dispatchEvent(name, payload) { + this.dispatch(name, { detail: payload, prefix: 'swup' }); + } +} +``` + +
+ +3. Replace the `symfony--ux-swup` occurrences in your templates with `swup`, for example: + +```diff +- ++ +``` + +4. Remove `symfony/ux-swup` from your dependencies: + +```bash +composer remove symfony/ux-swup +``` + +You're done! + +--- + Symfony UX Swup is a Symfony bundle integrating [Swup](https://swup.js.org/) in Symfony applications. It is part of [the Symfony UX initiative](https://ux.symfony.com/). diff --git a/src/Swup/doc/index.rst b/src/Swup/doc/index.rst index 5a961b65fcc..4a69ca79eac 100644 --- a/src/Swup/doc/index.rst +++ b/src/Swup/doc/index.rst @@ -1,6 +1,13 @@ Symfony UX Swup =============== +.. warning:: + + **Deprecated: This package has been deprecated in 2.x and will be removed in the next major version.** + + To keep the same functionality in your Symfony application, please follow the migration steps + from the `Symfony UX Swup README.md`_. + Symfony UX Swup is a Symfony bundle integrating `Swup`_ in Symfony applications. It is part of `the Symfony UX initiative`_. @@ -207,3 +214,4 @@ https://symfony.com/doc/current/contributing/code/bc.html .. _`Swup Options`: https://swup.js.org/options .. _StimulusBundle configured in your app: https://symfony.com/bundles/StimulusBundle/current/index.html .. _`@symfony/ux-swup npm package`: https://www.npmjs.com/package/@symfony/ux-swup +.. _`Symfony UX Swup README.md`: https://github.com/symfony/ux/tree/2.x/src/Swup/README.md diff --git a/src/Swup/src/DependencyInjection/SwupExtension.php b/src/Swup/src/DependencyInjection/SwupExtension.php index 117b0b80085..f71cced0f73 100644 --- a/src/Swup/src/DependencyInjection/SwupExtension.php +++ b/src/Swup/src/DependencyInjection/SwupExtension.php @@ -16,6 +16,8 @@ use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface; use Symfony\Component\HttpKernel\DependencyInjection\Extension; +trigger_deprecation('symfony/ux-swup', '2.27.0', 'The package is deprecated and will be removed in 3.0. Follow the migration steps in https://github.com/symfony/ux/tree/2.x/src/Swup to keep using Swup in your Symfony application.'); + /** * @internal */ diff --git a/src/Swup/src/SwupBundle.php b/src/Swup/src/SwupBundle.php index c03476aa96d..1c4694a1115 100644 --- a/src/Swup/src/SwupBundle.php +++ b/src/Swup/src/SwupBundle.php @@ -13,6 +13,8 @@ use Symfony\Component\HttpKernel\Bundle\Bundle; +trigger_deprecation('symfony/ux-swup', '2.27.0', 'The package is deprecated and will be removed in 3.0. Follow the migration steps in https://github.com/symfony/ux/tree/2.x/src/Swup to keep using Swup in your Symfony application.'); + /** * @final */ diff --git a/ux.symfony.com/tests/baseline-ignore b/ux.symfony.com/tests/baseline-ignore index b6c26bc279e..bb9ff61b48d 100644 --- a/ux.symfony.com/tests/baseline-ignore +++ b/ux.symfony.com/tests/baseline-ignore @@ -1,2 +1,3 @@ %Since symfony/ux-typed 2\.27\.0: The package is deprecated and will be removed in 3\.0\.% %Since symfony/ux-lazy-image 2\.27\.0: The package is deprecated and will be removed in 3\.0\.% +%Since symfony/ux-swup 2\.27\.0: The package is deprecated and will be removed in 3\.0\.%