Podcast Categories Laravel Package

Getting Started

This is a Statamic addon, not a general-purpose Laravel package. Confirm you are on Statamic 6 first (v2.0.0 is a Statamic 6 compatibility release) before you spend time anywhere else.

composer require statamic/podcast-categories

Statamic addons autoregister, so there is no config/app.php entry to add. If you need to customize the taxonomy or field behavior, publish the config:

php artisan vendor:publish --tag=podcast-categories-config

Where to look first, in order:

1. composer.json in the package — the statamic/cms, laravel/framework, and php constraints are the real compatibility spec. v2.0.0 gated to Statamic 6; plan accordingly.
2. The published config file — this is where the Apple category/subcategory list lives. Read it before assuming anything about shape.
3. The fieldtype class (typically src/Fieldtypes/...) — confirms the stored value format (single string vs. array of {category, subcategory}) and what your Antlers/Blade templates will actually receive.
4. The blueprint YAML — you author this yourself; there is no scaffold command.

First use case: a podcast entry with canonical Apple categories flowing into itunes:category RSS output.

# resources/blueprints/collections/podcast_episodes.yaml
title: Podcast Episodes
sections:
  main:
    display: Episode
    fields:
      - handle: podcast_category
        field:
          type: podcast_categories
          display: Podcast Category
          instructions: "Select the Apple Podcasts category for this show."

Create or edit an entry, pick a category, save. Then confirm the value round-trips before writing a single line of feed template — the most common first-day mistake is building the feed renderer against an assumed value shape.

Implementation Patterns

Blueprint field on the show/episode collection, not both. Apple categories describe the show, not individual episodes. Put the field on whichever collection is your podcast-level content model (often a podcasts collection or a single-entry podcast global). Duplicating it per-episode invites editors to disagree with themselves and produces feed entries whose category drifts over time.

Render into a compliant feed. The typical Antlers shape, assuming a category/subcategory pair:

{{ if podcast_category }}
<itunes:category text="{{ podcast_category:category }}">
  {{ if podcast_category:subcategory }}
  <itunes:category text="{{ podcast_category:subcategory }}" />
  {{ /if }}
</itunes:category>
{{ /if }}

Validate the output, not the field. Run the generated feed through Apple's Podcasts Connect validation and a generic RSS validator before every release. The field guarantees canonical strings; it does not guarantee you nested the elements correctly.

Blade fallback for anything outside Antlers. If your feed is built in a controller or a Blade view, read the raw value off the entry:

$category = $entry->get('podcast_category');
// Inspect once in tinker to nail the shape before coding against it:
// php artisan tinker --execute="dump(Entry::where('collection','podcasts')->first()?->get('podcast_category'));"

Never guess the shape from the README. The package is tiny and the README is thinner than the source; tinker is the source of truth.

Single source of truth for the taxonomy. If multiple templates, a feed controller, and possibly a JSON:API all need categories, do not re-resolve the field in each. Expose a small accessor (an Entry decorator, a computed value, or a repository service that reads the published config) and have every consumer call it. This is the seam you will use when you inevitably swap the addon for a vendored list.

Config-first customization. If you need extra top-level categories, custom ordering, or additional labels, edit the published config, not the vendor source. Keep the diff against vendor at zero so composer update cannot silently clobber your taxonomy.

Testing against real content. Do not validate on a fresh install. Clone staging data (entries with the field already populated), upgrade, and diff rendered feed output before and after. Fieldtype/addon failures show up as blank or wrong category strings on legacy entries far more often than on empty databases.

Gotchas and Tips

Composer resolution is the first real failure. Run this before writing code on any upgrade:

composer why-not statamic/podcast-categories 2.0.0

A sibling addon pinning Statamic 5 will deadlock resolution and look like "the package is broken." It is almost never this package — it is the other one. Resolve constraints first; it is the cheapest possible failure.

v2.0.0 is a platform-gated major. Its only stated change is "Updated for Statamic 6." There is no published upgrade guide and no visible changelog beyond that line — so do not assume v1 data is forward-compatible without checking. Diff the stored value shape between the v1 you have and the v2 you install, and audit existing entries' category values as part of the upgrade. A silent shape change presents as blank itunes:category in a live feed, which is a brand-visible defect, not a test failure.

Do not upgrade host and addon in one commit. Statamic 6 first (with Laravel and PHP, verified in staging), then this addon, then feature validation, then production. Two changes in one commit double the diagnosis cost when something breaks.

Static caching will serve stale categories. If your feed is behind Statamic's static cache and an editor changes a category, confirm invalidation is wired up. This is the most likely scaling-adjacent bug: an editor "fixes" the category and the feed keeps serving the old value for hours.

The panel payload risk is real but bounded. If the fieldtype resolves its option list per row on a large entry listing, editing pages get heavy. Unlikely at podcast-catalogue sizes (dozens to low hundreds of episodes) — but if you are on a listing with thousands of entries, keep this in mind before filing a performance bug.

Assume zero support and pin hard. One star, zero dependents, one-line changelog, no test suite evident, no published compatibility policy. Pin an exact version in composer.json, add the package to the pre-upgrade checklist, and write your own upgrade notes at the first migration — those notes will be the only documentation that exists when Statamic 7 lands.

The build-vs-vendor question is the highest-leverage decision here. The durable asset is a static, publicly documented taxonomy (Apple's category list). The code wrapping it is thin. If the addon becomes load-bearing, copy the category list into repository-owned config and register your own select field — roughly a day of work that eliminates the dependency, the upgrade obligation, and the bus-factor risk. The addon earns its place only if you value the maintainer's ongoing curation of that list more than you value owning it.

Extension points are the published config and the blueprint field config. There is nothing to subclass meaningfully. If you need multi-directory taxonomy (Spotify, YouTube have different schemes), this package becomes one input among several, not the source of truth — design your accessor seam accordingly from day one rather than after the second directory requirement lands.