Maintenance Bundle Laravel Package

Product Decisions This Supports

• Feature Flagging for Scheduled Downtime: Enables seamless, configurable maintenance mode for Symfony applications without disrupting development workflows (dev environment excluded).
• Zero-Downtime Deployments: Supports phased rollouts by allowing whitelisted IPs (e.g., staging, QA) to bypass maintenance while public users see the maintenance page.
• Branded Maintenance Pages: Customizable Twig templates for localized messaging (e.g., "We’ll be back soon" in multiple languages) to align with product branding.
• Roadmap for Scalability: Low-risk foundation for future features like:
  • User Authentication Bypass: Whitelist logged-in users (e.g., for SaaS platforms).
  • Dynamic Maintenance Pages: Fetch content from an API (e.g., CMS-driven messages).
  • Analytics Integration: Track maintenance page views to measure impact.
• Build vs. Buy: Buy—avoids reinventing a lightweight, battle-tested solution. Only consider custom development if needing advanced features (e.g., A/B testing maintenance pages).

When to Consider This Package

Adopt if:

• Your Symfony app requires planned downtime (e.g., deployments, migrations, or infrastructure updates).
• You need IP-based whitelisting for internal teams to access the site during maintenance.
• Your team lacks bandwidth to build/maintain a custom maintenance mode solution.
• You’re using Symfony 5/6/7 and need a minimal, configurable solution (no frontend framework dependencies).

Look elsewhere if:

• You need user-specific bypasses (e.g., logged-in users always see the site).
• Your stack isn’t Symfony (e.g., Laravel, Node.js, or static sites).
• You require multi-language support out-of-the-box (package lacks built-in translation; requires manual Twig overrides).
• You need analytics or A/B testing for maintenance pages (would require custom integration).
• Your team prefers a no-code solution (e.g., cloud-based maintenance pages like Cloudflare Turnstile).

How to Pitch It (Stakeholders)

For Executives: "This package lets us flip a switch to put our Symfony app into maintenance mode—like closing a store for renovations—without disrupting our team’s work. It’s free, lightweight, and lets us customize the message users see (e.g., ‘We’re upgrading your dashboard—back in 2 hours!’). For $0 in dev time, we avoid costly downtime risks and keep our brand messaging consistent. Used by [X] similar companies, it’s a no-brainer for deployments or planned updates."

For Engineering: *"The artgris/maintenance-bundle is a 5-minute setup for Symfony maintenance mode with:

• Config-driven control: Toggle maintenance via config/packages/artgris_maintenance.yaml (no code changes).
• Dev-safe: Automatically excludes the dev environment.
• Customizable: Override the Twig template for branded messages or dynamic content.
• Symfony 5/6/7 compatible: No legacy baggage, active maintenance (last release: March 2024).
• Lightweight: ~200 LOC, MIT-licensed, no external dependencies beyond Symfony/Twig.

Trade-offs:

• No built-in user auth bypass (would need custom logic).
• Manual cache clearing required (php bin/console cache:clear). Recommendation: Use for deployments/migrations. Extend later if needed (e.g., add a MaintenanceService for programmatic control)."*