Light News Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require carlescliment/light-news-bundle:dev-master
   

   Update app/AppKernel.php to include:

   new BladeTester\LightNewsBundle\BladeTesterLightNewsBundle(),
   

   Add routing in app/config/routing.yml:

   blade_tester_light_news_bundle:
       resource: "@BladeTesterLightNewsBundle/Resources/config/routing.yml"
       prefix: /news
   

2. First Use Case:

   • Create a custom bundle extending BladeTesterLightNewsBundle:

     namespace App\NewsBundle;
     
     use Symfony\Component\HttpKernel\Bundle\Bundle;
     
     class AppNewsBundle extends Bundle {
         public function getParent() { return 'BladeTesterLightNewsBundle'; }
     }
     

   • Register it in AppKernel.php.

3. Define a News Entity: Extend BladeTester\LightNewsBundle\Entity\News and add a unique id field:

   namespace App\NewsBundle\Entity;
   
   use BladeTester\LightNewsBundle\Entity\News as BaseNews;
   
   class News extends BaseNews {
       // Add custom fields (e.g., title, content, publishedAt)
       /**
        * @ORM\Column(type="string")
        */
       private $title;
   
       /**
        * @ORM\Column(type="text")
        */
       private $content;
   }
   

4. Run Migrations:

   php bin/console doctrine:schema:update --force
   

5. Access the Admin Interface: Navigate to /news/admin to manage news entries.

Implementation Patterns

Core Workflows

1. Entity Customization:

   • Extend BaseNews to add fields (e.g., slug, author, featuredImage).
   • Use annotations (@ORM\Column, @ORM\ManyToOne) or YAML/XML for mapping.
   • Example:

     /**
      * @ORM\ManyToOne(targetEntity="App\User\Entity\User")
      */
     private $author;
     

2. Repository Integration:

   • Override the default repository (BladeTester\LightNewsBundle\Repository\NewsRepository) in your bundle’s Resources/config/doctrine/:

     App\NewsBundle\Entity\News:
         type: entity
         repository: App\NewsBundle\Repository\NewsRepository
     

   • Extend repository methods (e.g., findPublished()):

     public function findPublished() {
         return $this->createQueryBuilder('n')
             ->where('n.publishedAt <= :now')
             ->setParameter('now', new \DateTime())
             ->orderBy('n.publishedAt', 'DESC')
             ->getQuery()
             ->getResult();
     }
     

3. Routing and Controllers:

   • Customize routes in Resources/config/routing.yml:

     news_list:
         path: /list
         defaults: { _controller: AppNewsBundle:News:index }
     

   • Override controllers (e.g., NewsController) in src/App/NewsBundle/Controller/ to add logic (e.g., filtering, pagination).

4. Twig Integration:

   • Pass news data to templates via controllers:

     public function indexAction() {
         $news = $this->getDoctrine()->getRepository('AppNewsBundle:News')->findAll();
         return $this->render('AppNewsBundle:News:index.html.twig', ['news' => $news]);
     }
     

   • Use Twig extensions (e.g., {{ news|light_news_format_date }}) if provided.

5. Form Handling:

   • Extend the default form type (BladeTester\LightNewsBundle\Form\NewsType) in src/App/NewsBundle/Form/NewsType.php:

     namespace App\NewsBundle\Form;
     
     use Symfony\Component\Form\AbstractType;
     use BladeTester\LightNewsBundle\Form\NewsType as BaseNewsType;
     
     class NewsType extends BaseNewsType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             parent::buildForm($builder, $options);
             $builder->add('featuredImage', FileType::class);
         }
     }
     

6. Event Listeners:

   • Subscribe to bundle events (e.g., news.pre_publish) in src/App/NewsBundle/EventListener/:

     namespace App\NewsBundle\EventListener;
     
     use BladeTester\LightNewsBundle\Event\NewsEvent;
     
     class NewsListener {
         public function onPrePublish(NewsEvent $event) {
             $news = $event->getNews();
             $news->setSlug($this->generateSlug($news->getTitle()));
         }
     }
     

   • Register the listener in services.yml:

     services:
         app.news.listener:
             class: App\NewsBundle\EventListener\NewsListener
             tags:
                 - { name: kernel.event_listener, event: news.pre_publish, method: onPrePublish }
     

7. API Endpoints:

   • Use Symfony’s serializers to expose news via API:

     public function apiListAction() {
         $news = $this->getDoctrine()->getRepository('AppNewsBundle:News')->findAll();
         return $this->json($news, 200, [], ['groups' => ['api']]);
     }
     

   • Add serialization groups to your entity:

     use Symfony\Component\Serializer\Annotation\Groups;
     
     /**
      * @Groups({"api"})
      */
     private $title;
     

Gotchas and Tips

Pitfalls

1. Bundle Inheritance:

   • Forgetting to set getParent() in your custom bundle will break functionality. Always verify:

     public function getParent() { return 'BladeTesterLightNewsBundle'; }
     

2. Entity Mapping:

   • The id field is mandatory. Omitting it or misconfiguring it will cause Doctrine errors.
   • Ensure your entity extends BladeTester\LightNewsBundle\Entity\News (not just BaseNews directly).

3. Routing Conflicts:

   • The default prefix (/news) may clash with existing routes. Test with:

     php bin/console debug:router | grep news
     

4. Form Overrides:

   • If extending NewsType, ensure you call parent::buildForm() to retain default fields (e.g., title, content).
   • Clear the cache after form changes:

     php bin/console cache:clear
     

5. Event System:

   • Events like news.pre_publish are not documented. Inspect the bundle’s EventDispatcher for available events:

     $dispatcher = $this->get('event_dispatcher');
     $events = $dispatcher->getListeners();
     

6. Symfony 2.1 Legacy:

   • The bundle targets Symfony 2.1, which may lack modern features (e.g., no native API Platform support). Test thoroughly with:

     php bin/console debug:container --parameters | grep symfony_version
     

7. Doctrine Configuration:

   • If using custom repositories, ensure Resources/config/doctrine/ is properly namespaced and loaded. Place it in:

     src/App/NewsBundle/Resources/config/doctrine/
     

Debugging Tips

1. Check Bundle Loading:

   • Verify the bundle is loaded with:

     php bin/console debug:container | grep light_news
     

2. Entity Validation:

   • Validate your entity with:

     php bin/console doctrine:schema:validate
     

3. Event Debugging:

   • Log events to var/log/dev.log:

     use Psr\Log\LoggerInterface;
     
     class NewsListener {
         public function __construct(LoggerInterface $logger) {
             $this->logger = $logger;
         }
     
         public function onPrePublish(NewsEvent $event) {
             $this->logger->info('News pre-publish event triggered', ['news' => $event->getNews()->getTitle()]);
         }
     }
     

4. Route Debugging:

   • Test routes interactively:

     php bin/console router:debug
     

Extension Points

1. Custom Admin Templates:

   • Override Twig templates in src/App/NewsBundle/Resources/views/ (e.g., News/index.html.twig).

2. Validation Groups:

   • Add custom validation constraints to your entity:

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\NotBlank(groups={"registration"})
      */
     private $title;
     

3. Asset Management:

   • Extend the bundle’s asset pipeline by overriding Resources/public/ files (e.g., CSS/JS for the admin panel).

4. Security:

   • Add voter logic to restrict access: