Statamic Podcast Publisher Laravel Package

Getting Started

Install via Composer and publish the package config:

composer require your-vendor/xml-package
php artisan vendor:publish --tag=xml-package-config

Look here first, in order:

1. config/xml-package.php — controls output path, caching, optional stylesheet, and encoding. Most day-to-day behavior lives here.
2. The package's Artisan command (php artisan xml:generate or similar) — the fastest way to validate your setup before wiring it into a route/controller.
3. The published stylesheet/views — if the release ships an XSL stylesheet, confirm where it is served from and that it resolves as an absolute URL (see 1.0.3 fixes below).

First use case to verify: generate a single document and open it in a browser. You want to see a valid XML tree with the stylesheet rendering, no stray <?xml ... ?> in the middle of the file, and no repeated root/child tags. If that renders cleanly, you're 90% of the way to a working setup.

Implementation Patterns

• Route-served output. The common pattern is a controller (or route closure) that asks the package to build and return the document. Cache headers are usually managed by the package; don't double-set Content-Type yourself.
• Scheduled generation. For larger or dynamic documents, generate on a schedule via the service provider's schedule() method and serve the cached file. This avoids rebuilding on every request and sidesteps runtime encoding surprises.
• Stylesheet as an absolute URL. Configure the stylesheet with a full absolute URL (https://example.com/xml/stylesheet.xsl) rather than a relative path. 1.0.3 specifically tightened this so the declaration is well-formed; relative paths were producing an unusable processing instruction.
• Content injection. Build the document by registering items/entries with the package's builder API rather than hand-concatenating strings. The builder owns escaping and deduplication (more relevant after 1.0.3), so fight the temptation to sprintf XML yourself.
• Multi-document setups. When generating sitemap indexes or paginated feeds, generate each child document then the index, and validate each one before publishing.

Gotchas and Tips

• XML declaration characters (fixed in 1.0.3). Before this release, unescaped or non-printable characters could leak into the <?xml ... ?> declaration itself, producing a document browsers reject as "not well-formed." If you were previously sanitizing input yourself around the declaration, you can now rely on the package — but keep sanitizing content values, not the prolog.
• Duplicate tags (fixed in 1.0.3). If your integration registers the same item twice (e.g. boot() runs, then a listener re-adds entries), earlier versions emitted duplicate XML tags. After upgrading, verify your registration path doesn't intentionally rely on that behavior; if you were filtering duplicates downstream, you can drop that workaround.
• Stylesheet must be absolute (fixed in 1.0.3). Relative stylesheet paths produced a processing instruction that some clients refused to follow. Set a full URL in config. If you serve behind a proxy, ensure your APP_URL/asset root reflects the public origin.
• Debugging malformed output. Pipe the generated output through xmllint --noout - to confirm well-formedness. This catches prolog issues and unclosed/duplicated tags quickly.
• Encoding matters. If content contains emoji or mixed scripts, confirm the configured encoding (usually UTF-8) matches what consumers expect; declaration mismatches cause the same class of "not well-formed" failures the 1.0.3 fix addresses.
• Extension points. Custom builders/renderers and the published views are the intended way to change structure. Avoid overriding the generation command unless you also handle caching and validation — those live in the package's service and are easy to bypass accidentally.
• Version pin. Given three fixes in a patch release touching serialization, keep the package locked at ^1.0.3 and add a smoke test that parses the generated document. It's cheap insurance against regressions in XML output.