Poddle Laravel Package

Getting

composer require phanan/poddle

Start by opening the package's src/ directory and tests/ fixtures. The entry point is a small factory that turns a feed URL or a raw XML string into a typed Podcast object; the test fixtures are real-world PSP-1 feeds and are the fastest way to see exactly which tags (podcast:transcript, podcast:chapters, podcast:person, etc.) are mapped. Confirm the factory/method names against the README for your installed version before wiring them in.

First use case: pull a feed and enumerate episodes with their enclosure URLs and durations.

use PhanAn\Poddle\Poddle;

$podcast = Poddle::fromUrl('https://feeds.example.com/show.xml');

foreach ($podcast->episodes() as $episode) {
    echo $episode->title.' — '.$episode->enclosure->url.PHP_EOL;
}

If your app already fetches HTTP elsewhere, pass the body instead: Poddle::fromString($xml).

Implementation Patterns

• Keep network I/O in your app, not the package. Fetch with Laravel's HTTP client (timeouts, retries, explicit user-agent) and hand the body to the parser. That keeps parsing unit-testable and lets you add caching and conditional GET at the HTTP layer.
• Sync job pattern. A queued SyncPodcastFeed job parses the feed, then upserts episodes keyed on the GUID (<guid> or podcast:guid) so re-runs are idempotent. Fall back to enclosure URL when no GUID exists.
• Normalize immediately. Map parsed objects into your own DTO or Eloquent model right after parsing. Don't leak the package's value objects into controllers or Blade views; keeps you free to swap parsers later.
• Store the raw XML alongside the parsed row. Invaluable for debugging bad feeds and for re-parsing after a package upgrade.
• Lean on PSP-1 fields (podcast:transcript, podcast:chapters, podcast:funding, podcast:person) to power richer UIs; generic RSS readers silently drop these.
• Test against fixtures, not live feeds. Assert on a handful of well-known fields per fixture (title, episode count, one enclosure URL).

Gotchas and Tips

• Real feeds are messy. Unescaped ampersands, mismatched CDATA, missing namespaces. If parsing throws, run the body through tidy/DOMDocument first, or catch and log with the feed URL and the first ~500 characters.
• Namespace prefixes vary (podcast: vs psc: for the Podcast Standards Project). Don't regex-match prefixes—rely on namespace-aware parsing (SimpleXMLElement::children($ns)).
• Many hosts reject default PHP user agents or require Accept: application/rss+xml. Set a UA, follow redirects, cap response size.
• itunes:duration is inconsistent: HH:MM:SS, MM:SS, or raw seconds. Normalize to an integer column before persisting.
• Enclosure URLs carry tracking prefixes (podtrac, chartable). Decide early whether to store raw or stripped, and be consistent everywhere.
• Episode order isn't guaranteed in the XML—sort by pubDate yourself.
• Check podcast:locked before allowing edits to feed metadata (relevant if you also publish feeds).
• Extension point: subclass or wrap the package's podcast/episode classes to add app-specific accessors rather than editing vendor code.
• Pin the version and re-run fixture tests on upgrade; PSP-1 is still evolving and tag coverage shifts between minor releases.