News Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/news-bundle
   

   Add to config/app.php under extra.bundles:

   Ekyna\NewsBundle\EkynaNewsBundle::class
   

2. Database Migration: Run migrations (if provided in the bundle). Check vendor/ekyna/news-bundle/Resources/config/doctrine for News.orm.xml or News.php entity definitions. If missing, manually create a news table:

   php artisan make:migration create_news_table
   

   Example schema:

   Schema::create('news', function (Blueprint $table) {
       $table->id();
       $table->string('title');
       $table->text('content')->nullable();
       $table->boolean('is_published')->default(false);
       $table->timestamps();
   });
   

3. First Use Case: Create a controller to fetch and display news:

   use Ekyna\NewsBundle\Entity\News;
   use Ekyna\NewsBundle\Repository\NewsRepository;
   
   class NewsController extends Controller
   {
       public function index(NewsRepository $newsRepo)
       {
           $news = $newsRepo->findBy(['is_published' => true]);
           return view('news.index', compact('news'));
       }
   }
   

4. Routing: Add routes in routes/web.php:

   use Ekyna\NewsBundle\Controller\NewsController;
   
   Route::get('/news', [NewsController::class, 'index']);
   

Implementation Patterns

Core Workflows

1. CRUD Operations: Use the NewsRepository for database interactions:

   // Create
   $news = new News();
   $news->setTitle('Breaking News');
   $news->setContent('Content here...');
   $news->setPublished(true);
   $entityManager->persist($news);
   $entityManager->flush();
   
   // Read
   $newsRepo->findAll(); // All news
   $newsRepo->findBy(['is_published' => true]); // Published only
   
   // Update
   $news = $newsRepo->find($id);
   $news->setTitle('Updated Title');
   $entityManager->flush();
   
   // Delete
   $newsRepo->remove($news, true);
   

2. Integration with Forms: Use Symfony’s FormBuilder to create a news submission form:

   use Ekyna\NewsBundle\Form\NewsType; // If provided; otherwise, create manually
   
   $form = $this->createForm(NewsType::class, $news);
   

3. Displaying News in Views: Loop through published news in Blade:

   @foreach($news as $item)
       <article>
           <h2>{{ $item->getTitle() }}</h2>
           <p>{{ $item->getContent() }}</p>
           <small>Published: {{ $item->getCreatedAt()->format('M d, Y') }}</small>
       </article>
   @endforeach
   

4. API Endpoints: Use Symfony’s JsonResponse for RESTful APIs:

   public function apiNews(NewsRepository $newsRepo)
   {
       $news = $newsRepo->findBy(['is_published' => true]);
       return new JsonResponse($news);
   }
   

Advanced Patterns

1. Event Listeners: Attach listeners to news lifecycle events (e.g., prePersist, preUpdate). Example:

   // In a service or listener class
   public function onNewsPublish(News $news)
   {
       // Send notification, log, etc.
   }
   

   Register in services.yaml:

   services:
       App\EventListener\NewsListener:
           tags:
               - { name: doctrine.event_listener, event: prePersist }
   

2. Custom Queries: Extend NewsRepository to add custom methods:

   namespace App\Repository;
   
   use Ekyna\NewsBundle\Repository\NewsRepository as BaseNewsRepository;
   
   class NewsRepository extends BaseNewsRepository
   {
       public function findPublishedByCategory($category)
       {
           return $this->createQueryBuilder('n')
               ->where('n.category = :category')
               ->andWhere('n.is_published = :published')
               ->setParameter('category', $category)
               ->setParameter('published', true)
               ->getQuery()
               ->getResult();
       }
   }
   

3. Caching: Cache frequently accessed news to improve performance:

   use Symfony\Contracts\Cache\CacheInterface;
   
   public function getCachedNews(CacheInterface $cache, NewsRepository $newsRepo)
   {
       return $cache->get('published_news', function () use ($newsRepo) {
           return $newsRepo->findBy(['is_published' => true]);
       }, 3600); // Cache for 1 hour
   }
   

Gotchas and Tips

Common Pitfalls

1. Missing Documentation:

   • The bundle lacks a README or detailed documentation. Expect to reverse-engineer from Entity classes and tests (if any).
   • Tip: Inspect vendor/ekyna/news-bundle/src/Entity/News.php and vendor/ekyna/news-bundle/src/Repository/NewsRepository.php for defaults and methods.

2. Outdated Code:

   • Last release in 2015 may cause compatibility issues with modern Laravel/Symfony.
   • Tip: Override or extend classes (e.g., NewsRepository) to adapt to newer Doctrine/Symfony versions.

3. No Built-in Admin:

   • No pre-built admin interface (e.g., no EasyAdmin or SonataAdmin integration).
   • Tip: Use Laravel Nova or Filament to create a custom admin panel for News.

4. Missing Form Types:

   • The bundle may not include Symfony FormType classes for News.
   • Tip: Create a custom NewsType:

     namespace App\Form;
     
     use Ekyna\NewsBundle\Entity\News;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     
     class NewsType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
                 ->add('title')
                 ->add('content', TextareaType::class)
                 ->add('is_published', CheckboxType::class);
         }
     }
     

5. No Soft Deletes:

   • The bundle likely lacks soft-delete functionality.
   • Tip: Add deleted_at column and use Laravel Soft Deletes or Doctrine lifecycle callbacks.

Debugging Tips

1. Check Entity Metadata: If fields are missing or methods undefined, verify the News entity:

   php bin/console doctrine:schema:update --dump-sql
   

   Or inspect the entity with:

   $reflection = new ReflectionClass(Ekyna\NewsBundle\Entity\News::class);
   print_r($reflection->getProperties());
   

2. Query Debugging: Enable Doctrine debugging in .env:

   APP_DEBUG=true
   

   Or use:

   $query = $newsRepo->createQueryBuilder('n');
   dump($query->getQuery()->getSQL()); // Show raw SQL
   

3. Event Debugging: If events (e.g., prePersist) aren’t firing, verify listeners are registered:

   php bin/console debug:event-dispatcher
   

Extension Points

1. Custom Fields: Extend the News entity to add fields (e.g., category, author):

   namespace App\Entity;
   
   use Ekyna\NewsBundle\Entity\News as BaseNews;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class News extends BaseNews
   {
       #[ORM\Column(type: 'string', length: 255)]
       private $category;
   
       // Getters/setters...
   }
   

2. Validation: Add validation rules to the NewsType or entity:

   use Symfony\Component\Validator\Constraints as Assert;
   
   #[ORM\Entity]
   class News extends BaseNews
   {
       #[Assert\NotBlank]
       #[Assert\Length(max: 255)]
       private $title;
   }
   

3. API Resources: Use API Platform or Laravel Transformers to shape API responses:

   use App\Transformers\NewsTransformer;
   
   return Fractal::item($news, new NewsTransformer)->toArray();
   

4. Testing: Write feature tests for news CRUD:

   public function testNewsCreation()