Formatter Bundle Laravel Package

Getting Started

Before you install anything, note the package's status: it is archived, has zero dependents, and is scoped to Symfony2 and the Sonata ecosystem of that era (SonataFormatterBundle + SonataAdminBundle). Treat it as a reference implementation for a legacy application, not a candidate for a new build.

If you must work with it:

1. Confirm your stack first. You need Symfony 2.x, a compatible sonata-project/formatter-bundle (roughly the 2.x line), and the Sonata admin stack the bundle was written against. Check the composer.json constraints before require — expect php >=5.3 and old symfony/symfony ranges.

2. Install via Composer:

   composer require rz/formatter-bundle
   

3. Register the bundle in app/AppKernel.php (Symfony2 style — no Flex auto-discovery):

   public function registerBundles()
   {
       return [
           // ...
           new Sonata\FormatterBundle\SonataFormatterBundle(),
           new Rz\FormatterBundle\RzFormatterBundle(),
       ];
   }
   

4. Look first at DependencyInjection/ and Resources/config/services.yml. That is where the bundle wires its formatter services and any compiler passes. The extension class (RzFormatterBundleExtension) tells you what config keys are exposed.

5. First use case: rendering admin-side text content (markdown/Twig/raw) through Sonata's sonata.formatter.pool — i.e., registering one or more formatter types so a textarea in Sonata Admin can be authored in one syntax and rendered in another.

If you are on Symfony 3.4+ or 4+, the bundle will not boot; look instead at sonata-project/formatter-bundle directly and register formatters as tagged services yourself.

Implementation Patterns

The day-to-day work is really "configuring Sonata's formatter pool," and this bundle is a thin extension of it. Typical patterns:

• Configure the pool centrally. Under sonata_formatter: in config.yml, enable the formatter types you want (markdown, twig, rawhtml, text) and set defaults per admin context:

  sonata_formatter:
      formatters:
          markdown:
              service: sonata.formatter.text.markdown
      default_formatter: markdown
  

• Register a custom formatter as a tagged service. Anything you build implements Sonata's FormatterInterface and is exposed to the pool:

  services:
      app.formatter.custom:
          class: AppBundle\Formatter\CustomFormatter
          tags:
              - { name: sonata.formatter, alias: custom }
  

  The bundle's own services are the template to copy — match the alias convention (sonata.formatter.text.*) so tooling and admin fields resolve them consistently.

• Integrate with Sonata Admin form fields. Use the formatter's type option on a TextareaType/TextType and read back rendered output in a template via the sonata.formatter.pool service:

  $formatter = $this->get('sonata.formatter.pool')->get('markdown');
  $html = $formatter->transform($source);
  

• Workflow: author → store → render. Store the raw source in a text column, keep the formatter alias alongside it (or infer from a field-level config), and render at read time. Do not persist the rendered HTML unless you have a caching requirement — it makes formatter changes a migration problem.

• CMS integration. In the RZ ecosystem this bundle is typically picked up by rz/cms-bundle / rz/admin-bundle content types; if you're extending those, follow their content-type Formatter option rather than overriding Sonata's form fields directly.

Gotchas and Tips

• It is archived — plan an exit. There are no security fixes, no PHP 8 support, and zero community traction. If this is in a live project, budget time to inline the formatter config into your app and drop the bundle.

• Version pinning is fragile. Old Sonata bundles had tight cross-dependency constraints. Pin sonata-project/formatter-bundle, sonata-project/admin-bundle, and sonata-project/core-bundle (a common victim of drift) together, and verify with composer why-not before any upgrade.

• Config key mismatch is the most common failure. If a formatter "doesn't show up," the service tag alias and the sonata_formatter.formatters key must match exactly. Debug with:

  php app/console debug:container sonata.formatter
  php app/console debug:container --tag=sonata.formatter
  

  (Legacy console path — app/console not bin/console.)

• Twig formatters execute arbitrary code. If you expose a Twig formatter to untrusted authors, you're granting template execution. Restrict the pool per admin context and prefer markdown for user-facing content.

• Rendering happens at read time, so cache at the boundaries. Wrap transform() calls in your own cache keyed on (alias, source_hash) if pages are heavy — Sonata's formatter does not cache for you.

• Extension points:

  • Implement FormatterInterface + tag sonata.formatter for a new syntax.
  • Override RzFormatterBundleExtension only if you truly need new config keys; a compiler pass in your own bundle is less brittle.

• Debugging output: if the rendered text is escaped, the issue is almost always the admin template, not the formatter — check for a stray {{ var }} vs {{ var|raw }} in the override templates under Resources/views/.

• Final recommendation: for anything greenfield, skip this bundle and configure sonata-project/formatter-bundle directly. The RZ layer adds little beyond defaults and inherits all of the legacy stack's maintenance burden.