Tex2Png Bundle Laravel Package

Getting Started

1. Install the dependency: composer require gregwar/tex2png-bundle. Because the package is old and lightly maintained (4 stars, no dependents), pin it and check that it resolves against your PHP/Symfony version before committing — Composer may pull a very old release or fail on modern PHP constraints.
2. Register the bundle: in app/AppKernel.php, add new Gregwar\Tex2pngBundle\GregwarTex2pngBundle(), to the registerBundles() array (or config/bundles.php on Symfony 4+ with a Flex-style shim).
3. Install system binaries: this bundle shells out to LaTeX. You need latex/pdflatex, dvipng, and ImageMagick's convert on the host, plus a writable cache directory. Nothing will work without them, and the bundle has no pure-PHP fallback.
4. Configure the cache path under gregwar_tex2png (or gregwar_tex2png_bundle depending on the version) so generated PNGs land in a web-accessible location, e.g. %kernel.root_dir%/../web/tex.
5. First use case: render a formula inline in a template with the provided Twig filter, e.g. {{ '\\frac{a}{b}'|tex2png }}, which returns a URL to a generated PNG. Hit that page once and confirm a file appears in the configured cache directory.

Start by reading the bundle's DependencyInjection/Configuration.php and the Twig extension class in the repo — those two files document almost everything the package exposes, and there is little beyond them.

Implementation Patterns

• Twig filter as the primary surface: the bundle's value is emitting an <img>-ready URL from a LaTeX string directly in templates. Use it inline for one-off formulas, but wrap it in your own Twig macro if you need consistent alt, class, or width attributes across the app.
• Service injection for non-template code: in controllers, console commands, or importers, pull the converter from the container and call it directly so you can catch failures and fall back to plain text rather than emitting a broken image.
• Cache-aware rendering: every render is a fork/exec of LaTeX plus dvipng. For any page with repeated formulas (a math quiz, a documentation site), pre-generate during a build or console command and store the resulting URL alongside the formula in your database. Treat the bundle as a build-time tool, not a request-time one.
• Pre-warm on deploy: add a deploy step or console command that iterates over distinct formulas in your data and renders them once, so the first user request after a deploy doesn't pay the LaTeX penalty.
• Content ingestion pipeline: if users submit formulas (e.g., in a CMS or forum), sanitize the input before handing it to LaTeX. Whitespace normalization and stripping newlines avoids shell-escaping surprises.
• Fallback rendering: wrap calls in try/catch and store a rendered_at / error flag on the entity. When the binary is missing (common on fresh CI images or containers), degrade to displaying the raw LaTeX in a <code> block.
• Docker integration: bake texlive + dvipng + imagemagick into the image and mount the cache as a volume, otherwise the cache is lost on every container restart.

Gotchas and Tips

• System binaries are the #1 failure mode: the bundle throws cryptic errors when latex, dvipng, or convert aren't on PATH. Verify with which latex dvipng convert inside the exact user/container that runs PHP, not your local shell.
• File permissions: the web server user must own the cache directory. A root-owned cache directory built during deploy is a classic silent failure — the filter returns a URL to a file that was never written.
• Shell escaping / injection: formulas pass through to a shell command. Never pass unsanitized end-user input; LaTeX's \write18 and shell metacharacters are a real risk. Prefer server-controlled formulas or a strict whitelist of LaTeX commands.
• No request-level memoization built in: the same formula on the same page will hit the converter repeatedly. Cache the URL in Twig via a custom extension or in your service layer.
• Cache invalidation is manual: changing DPI, font packages, or the LaTeX preamble does not regenerate existing PNGs. Clear the cache directory after any config or texlive package change.
• Maintenance risk: only 4 stars and zero dependents means this is effectively a personal bundle. Vendoring the thin converter service (gregwar/tex2png) and calling it directly from your own service may be more sustainable than depending on the Symfony bundle wrapper.
• Modern Symfony compatibility: expect deprecation warnings or outright breakage on Symfony 4/5+ due to old container/service definitions. If you must use it, fork and modernize the DI config rather than relying on upstream.
• Testing: mock or wrap the converter behind your own interface so unit tests don't require a LaTeX install. An integration test that asserts a non-empty PNG with the correct magic bytes catches most misconfigurations.
• Extension point: the renderer's binary paths and DPI are configurable — use that to point at a pinned TeX Live install rather than whatever is on the host, so output is reproducible across environments.