Article Bundle Laravel Package

Getting Started

What it actually is. kunstmaan/article-bundle is a thin content-type layer on top of KunstmaanPageBundle. It ships three base classes — Article (the detail page), ArticleOverview (the listing page) and ArticleAuthor — plus admin lists, default Twig views, and hook points for the Kunstmaan generator. You are not meant to use Article directly; you subclass it once per article section (Press, Blog, News…) inside your own bundle. Stars/dependents are low because it is a monorepo split of the CMS, not because it is unused in practice.

Prerequisites. This is a Symfony 2.x-era bundle (last release April 2014). You need kunstmaan/page-bundle, kunstmaan/admin-bundle, kunstmaan/media-bundle and kunstmaan/generator-bundle at compatible versions, plus Doctrine ORM. In real projects you almost never install it standalone — you install kunstmaan/bundles-cms, which pulls this in.

Minimal steps

composer require kunstmaan/article-bundle

Register it in app/AppKernel.php after the bundles it depends on (order matters for the admin menu and page part configs):

new Kunstmaan\PageBundle\KunstmaanPageBundle(),
new Kunstmaan\MediaBundle\KunstmaanMediaBundle(),
new Kunstmaan\AdminBundle\KunstmaanAdminBundle(),
new Kunstmaan\ArticleBundle\KunstmaanArticleBundle(),

Then create the tables (review the SQL first — see Gotchas):

app/console doctrine:schema:update --dump-sql
app/console doctrine:schema:update --force
app/console cache:clear

Where to look first

1. Entity/Article.php — the fields you inherit: title, summary, author (ManyToOne to ArticleAuthor), publicationDate, image (Media), and the body via page parts.
2. Entity/ArticleOverview.php — the listing page.
3. Resources/views/ — the default front-end templates you will override.
4. app/console list kuma — find the generator command (typically kuma:generate:article; the exact name shifts between GeneratorBundle versions).

First use case. Never create an Article — generate a section:

app/console kuma:generate:article
# namespace: Acme\Bundle\PressBundle\Entity
# section name: Press

This writes PressArticle extends Article, PressArticleOverview extends ArticleOverview, an author subclass, matching admin lists, and Twig stubs. Then in the CMS admin, create a "Press overview" page in the page tree and add a couple of Press articles as children. If the overview renders and the detail page resolves a slug, your wiring is correct.

Implementation Patterns

Generator-first, then hand-edit. Treat the generated entity as scaffolding. The generator gets inheritance, @ORM\Table, admin list registration and template paths right; it will not know your business fields. Add those afterwards as plain @ORM\Column properties on the subclass, not the base class.

One subclass per section. Article is a @MappedSuperclass, so PressArticle, BlogArticle and NewsArticle each persist independently while sharing behaviour. Never point two sections at the same entity — you lose the ability to vary fields, templates and admin filters.

Multi-section setup that scales

namespace Acme\Bundle\PressBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Kunstmaan\ArticleBundle\Entity\Article;

/**
 * @ORM\Entity()
 * @ORM\Table(name="acme_press_article")
 */
class PressArticle extends Article
{
    /** @ORM\Column(type="string", nullable=true) */
    protected $sourceOutlet;

    public function getSourceOutlet() { return $this->sourceOutlet; }
    public function setSourceOutlet($v) { $this->sourceOutlet = $v; return $this; }
}

Because the property is on the subclass, the column appears only on the press table and the field is available in the generated admin form and Twig.

Overview page behaviour. The overview is a normal page whose children are the articles; you control ordering, paging and filtering in one place. Sort by publicationDate descending with a stable tiebreaker, and decide explicitly whether the list is server-rendered or AJAX-paged — the 2014 default templates do a plain loop, so pagination is usually the first thing you add.

Template overrides, not edits. Keep the vendor bundle untouched and shadow the views:

app/Resources/KunstmaanArticleBundle/views/Article/view.html.twig
app/Resources/KunstmaanArticleBundle/views/ArticleOverview/view.html.twig

Then style per section by overriding in your own bundle's Resources/views/PressArticle/.

Rendering the detail page — guard the nullable relations, they bite:

<h1>{{ article.title }}</h1>
{% if article.publicationDate %}
  <time>{{ article.publicationDate|date('d/m/Y') }}</time>
{% endif %}
{% if article.author %}
  <span class="byline">{{ article.author.name }}</span>
{% endif %}
{% if article.image %}
  <img src="{{ article.image|media({'thumbnail': 'article_thumb'}) }}" alt="{{ article.title }}">
{% endif %}
{% if article.summary %}<p class="lead">{{ article.summary }}</p>{% endif %}
{{ article.pagePartsHtml('main')|raw }}  {# adjust helper to your PageBundle version #}

Authors. ArticleAuthor is a first-class entity with its own admin list, so editors maintain a directory and articles reference it. Prefer one shared author pool per site; per-section author subclasses multiply admin screens for little gain. If you need bios and photos, extend the author subclass rather than the article.

Extending the admin list. The generated PressArticleAdminList inherits from the bundle's ArticleAdminList. Add columns and filters there (addColumn, addFilter, setDefaultSort) rather than reordering in the template — this keeps the backend usable and matches what editors expect from other Kunstmaan lists.

URLs and SEO. Slugs, page titles and node translations come from PageBundle, not from this bundle. Do not add a slug field; register the section in the page tree and let PageBundle's slug controller route it. Meta fields likewise come from the page's node translation.

Gotchas and Tips

Inheritance mistakes fail silently. The bundle's Article/ArticleOverview carry @MappedSuperclass. Putting @ORM\Entity or a @ORM\Table on a parent class, or adding a column to the base class because "it's easier", produces no schema change and no error — you only notice when a getter returns null in production. Verify with app/console doctrine:mapping:info and doctrine:schema:update --dump-sql after every entity change.

Always dump before forcing. Page inheritance chains in Kunstmaan span AbstractPage plus your subclass plus the node/translation tables. Run --dump-sql and read it; --force on a populated site can attempt destructive alterations. On anything beyond a prototype, use migrations.

Nullable date and author fields. publicationDate and author are both nullable by design (drafts). {{ article.publicationDate|date('d/m/Y') }} throws on null in most Twig configurations — the default templates were written against content where these are always filled. Wrap them.

Draft leakage on the overview. The overview is a page whose list is derived from its children in the page tree; depending on your PageBundle version the raw children relation does not filter on online status. Check the online flag of each child (or query the concrete repository with an online filter) before rendering, otherwise unpublished articles appear on the site and get indexed.

Regeneration overwrites. Running the generator again for the same namespace clobbers your entity, admin list and templates. Commit before running it, or run it once in a scratch bundle and copy out what you want.

Cache clears are not optional. Template overrides, new admin lists and translation files are all cached. app/console cache:clear --env=dev after adding a section, and again for prod; a "my override isn't picked up" bug is almost always this.

Translations are per-page, not per-field. Unlike the page title (which lives on the node translation), title, summary and body page parts are on the page itself. A truly multilingual article section means separate article pages per locale linked in the tree — budget for that rather than assuming Article is translatable.

Media filter dependency. The |media filter and thumbnail definitions come from MediaBundle. If the image renders as a raw ID, your thumbnail set isn't defined in kunstmaan_media config — that's a MediaBundle problem, not an ArticleBundle one.

Thin configuration surface. There is no meaningful kunstmaan_article config block to swap classes or services. The real extension points are (a) subclassing the three entities, (b) overriding templates in app/Resources, and (c) overriding the generated admin lists. Plan customisation around those three and you won't fight the bundle.

Version reality check. Last release 2014, Symfony 2.x, PHP 5.x idioms. On a modern Symfony project do not attempt to install this — either pin to the last kunstmaan/bundles-cms that supports your Symfony version, or reimplement the 200 lines it actually contributes on top of PageBundle (a page type, a listing page, an author entity, two admin lists). The concept is worth copying; the code is not worth resurrecting.