News Bundle Laravel Package

Getting Started

Minimal Steps for Laravel Integration

1. Install Contao Core First: Since news-bundle is Contao-specific, install Contao as a dependency:

   composer require contao/core-bundle
   

   Run Contao’s installation:

   php bin/contao-console contao:install
   

2. Add the News Bundle:

   composer require contao/news-bundle
   

   Enable it in config/bundles.php:

   Contao\NewsBundle\ContaoNewsBundle::class => ['all' => true],
   

3. Database Setup: Update Contao’s database via:

   php bin/contao-console contao:database:update
   

   Or manually run the tl_news migration (if extracted).

4. First Use Case: Display News in Laravel Blade Create a Blade template (resources/views/news/list.blade.php):

   @foreach(\Contao\NewsBundle\Model\NewsModel::findPublishedByArchive($archiveId) as $news)
       <article>
           <h2>{{ $news->headline }}</h2>
           <p>{{ Str::limit($news->teaser, 200) }}</p>
           <a href="{{ route('news.show', $news->id) }}">Read More</a>
       </article>
   @endforeach
   

5. Route News in Laravel: Define routes in routes/web.php:

   Route::get('/news/{id}', [\App\Http\Controllers\NewsController::class, 'show'])
       ->name('news.show');
   

Implementation Patterns

Workflows

1. Editorial Workflow:

   • Create News: Editors use Contao’s backend (/contao/backend/modules/News).
   • Schedule: Set start/stop dates in tl_news.
   • Categorize: Assign to archives (tl_news_archive).
   • Publish: Use Contao’s versioning or Laravel’s softDeletes.

2. Laravel-Centric Integration:

   • Service Layer: Wrap Contao models in Laravel services:

     // app/Services/NewsService.php
     class NewsService {
         public function getFeaturedNews(int $limit = 3) {
             return \Contao\NewsBundle\Model\NewsModel::findPublishedByArchive(1)
                 ->limit($limit)
                 ->orderBy('date desc');
         }
     }
     

   • API Endpoints: Expose news via Laravel API resources:

     // app/Http/Resources/NewsResource.php
     public function toArray($request, News $news) {
         return [
             'title' => $news->headline,
             'slug' => $news->alias,
             'excerpt' => $news->teaser,
         ];
     }
     

3. Frontend Patterns:

   • Dynamic Lists: Use Laravel Blade directives to fetch news:

     @newsList($archiveId, ['limit' => 5, 'showTeaser' => true])
     

   • Single News Page: Fetch by ID:

     $news = \Contao\NewsBundle\Model\NewsModel::findByPk($id);
     

Integration Tips

• Hybrid Auth: Use Laravel’s auth system to gate Contao news:

  if (auth()->check() && auth()->user()->can('view_premium_news')) {
      $news = NewsModel::findPublishedByArchive(2); // Premium archive
  }
  

• SEO: Leverage Laravel’s meta package with Contao’s SEO fields:

  use Spatie\Meta\Tags;
  Tags::title($news->headline)
      ->description($news->metaDescription ?? $news->teaser);
  

• Media Handling: Use Laravel’s spatie/laravel-medialibrary alongside Contao’s file uploads:

  $news->addMedia(storage_path('app/public/uploads/' . $news->singleSRC))
       ->usingCollection('news_images');
  

Gotchas and Tips

Pitfalls

1. Doctrine 1.x vs. Eloquent:

   • Contao’s NewsModel uses Doctrine 1.x, which lacks Laravel’s Eloquent features (e.g., relationships, accessors).
   • Fix: Extend the model or use a Laravel model as a facade:

     class LaravelNews extends Model {
         public static function findPublished() {
             return NewsModel::findPublished()->getArray();
         }
     }
     

2. Routing Conflicts:

   • Contao’s routes (e.g., /news/[id]) may clash with Laravel’s.
   • Fix: Override Contao’s router or use middleware to proxy requests:

     Route::prefix('contao')->group(function () {
         // Contao routes
     });
     

3. Templating Quirks:

   • Smarty templates assume Contao’s global variables (e.g., $this->News).
   • Fix: Create a Blade wrapper:

     @php
         $news = \Contao\NewsBundle\Model\NewsModel::findByPk($id);
     @endphp
     <h1>{{ $news->headline }}</h1>
     

4. Database Locking:

   • Contao’s tl_news uses serialized fields (e.g., jumpTo), which break in Laravel.
   • Fix: Use json columns or normalize data:

     Schema::table('tl_news', function (Blueprint $table) {
         $table->json('jumpTo')->default('[]');
     });
     

Debugging Tips

• Enable Contao Debugging: Set TL_DEBUG in config/autoload.php:

  'debug' => true,
  'tl_debug' => true,
  

• Log Contao Queries: Use Doctrine’s logging:

  \Doctrine\DBAL\Logging\EchoSQLLogger::enable();
  

• Check DCA Configuration: News fields are defined in dca/tl_news.php. Override them in config/dca.php:

  $GLOBALS['TL_DCA']['tl_news']['fields']['customField'] = [
      'label' => ['tl_news_customField', 'label'],
      'inputType' => 'text',
  ];
  

Extension Points

1. Custom Fields: Add fields via DCA:

   $GLOBALS['TL_DCA']['tl_news']['fields']['author'] = [
       'label' => ['tl_news_author', 'label'],
       'inputType' => 'text',
   ];
   

   Then access in Laravel:

   $news->author;
   

2. Hooks: Use Contao’s hooks to extend functionality:

   // app/Providers/ContaoServiceProvider.php
   public function boot() {
       \Contao\CoreBundle\ContaoCoreBundle::getContainer()
           ->get('hook')->attach('getNewsItem', function ($item) {
               $item->customField = 'value';
               return $item;
           });
   }
   

3. Event Listeners: Listen to Contao events (e.g., insert, delete) via Laravel’s events:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'contao.news.insert' => [NewsListener::class, 'handleInsert'],
   ];
   

4. API Layer: Expose news via Laravel’s API:

   Route::get('/api/news', function () {
       return \Contao\NewsBundle\Model\NewsModel::findPublished()->toArray();
   });
   

Performance Quirks

• N+1 Queries: Contao’s NewsModel may load related data (e.g., tl_news_archive) inefficiently. Fix: Use Laravel’s with():

  $news = NewsModel::findPublished()->with('archive')->get();
  

• Caching: Cache Contao news queries in Laravel:

  $news = Cache::remember("news_{$archiveId}", now()->addHours(1), function () use ($archiveId) {
      return NewsModel::findPublishedByArchive($archiveId);
  });