FragmentKitBundle

⭐ Found this useful? Give it a star on GitHub! It helps us maintain and improve the project.

Symfony bundle that makes Twig fragment sub-requests resilient when using {ignore_errors: true}.

This bundle is FrankenPHP worker mode friendly.

This includes kernel reuse (FRANKENPHP_RESET_KERNEL unset or 0); see docs/FRANKENPHP-WORKER-AUDIT.md.

Features

• ✅ HTTP error tolerance — {ignore_errors: true} also covers 403/404 (not only exceptions)
• ✅ Twig fallback — configurable template (or empty string)
• ✅ Optional Sentry — report suppressed failures without breaking the parent page
• ✅ Flex recipe — ships nowo_fragment_kit config
• ✅ FrankenPHP demo — Symfony 8 single-container demo

FrankenPHP: Demos use a single PHP service (FrankenPHP, no nginx). Runtime mode is controlled by FRANKENPHP_MODE in .env (default worker). Set classic for per-request PHP / easier hot-reload (entrypoint swaps in Caddyfile.dev). Recreate the container after changing the mode — no image rebuild. See docs/DEMO-FRANKENPHP.md.

Version information

Version	PHP	Symfony	Status
1.2.x	>= 8.2	7.4 – 8.1+	Stable
1.1.x	>= 8.2	7.4 – 8.1+	Stable
1.0.x	>= 8.2	7.4 – 8.1+	Security / maintenance

Installation

composer require nowo-tech/fragment-kit-bundle

Register the bundle (Flex does this automatically):

Nowo\FragmentKitBundle\NowoFragmentKitBundle::class => ['all' => true],

{{ render(controller('App\\Controller\\WidgetController::index'), {ignore_errors: true}) }}

Requirements

• PHP >= 8.2, < 8.6
• Symfony ^7.4 || ^8.0 (CI covers 7.4, 8.0, 8.1)
• Twig Bundle

Problem

{{ render(controller(...), {ignore_errors: true}) }} only suppresses exceptions thrown during sub-requests. When the sub-request returns an HTTP error status (403, 404, …), FragmentHandler::deliver() throws a RuntimeException and the parent page still fails with a 500; and exceptions thrown by the fragment controller are swallowed into an empty string with no fallback and no report. FragmentKit handles both (see Usage).

Demos

make -C demo up-symfony8   # http://localhost:8050 (default PORT)

Development

make setup-hooks
make up
make install
make release-check

Documentation

• Installation
• Configuration
• Usage
• Contributing
• Code of Conduct
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development
• GitHub Spec Kit

Additional documentation

• PSR evaluation (REQ-CS-007)
• GitHub Actions CI requirements
• Demo with FrankenPHP (includes worker mode)
• FrankenPHP worker audit (FRANKENPHP_RESET_KERNEL unset/false)
• Server cookbook (Nginx, php-fpm, FrankenPHP)

Tests and coverage

make test
make test-coverage

• Tests: PHPUnit (unit + integration)
• PHP: 100% lines (make test-coverage)

License

MIT — see LICENSE.