Tellyourstory Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Clone the repo and add to composer.json:

   composer require ee/tellyourstory-bundle
   

   Ensure AppKernel.php includes:

   new EE\TYSBundle\EETYSBundle(),
   new TB\TYSBundle\TBTYSBundle(),
   

2. Required Config Add to config.yml:

   fos_rest:
       param_fetcher_listener: force
       body_listener: true
       format_listener: true
       view:
           view_response_listener: 'force'
       routing_loader:
           default_format: json
   
   sensio_framework_extra:
       view: { annotations: false }
   

3. First Use Case Run migrations (if provided) and test the API endpoints (e.g., /api/stories). Verify BootstrapBundle assets load (check /bundles/mopabootstrap/).

Implementation Patterns

Core Workflows

1. Story Creation Use FOSRest annotations for API endpoints:

   use FOS\RestBundle\Controller\Annotations\Route;
   use FOS\RestBundle\Controller\Annotations\NamePrefix;
   
   class StoryController extends Controller {
       /**
        * @Route("/stories", name="story_create", methods={"POST"})
        * @NamePrefix("api_")
        */
       public function createAction() {
           // Logic to save story via TB\TYSBundle
       }
   }
   

2. Serialization Leverage JMS Serializer for story DTOs:

   # config/serializer/Story.yml
   TB\TYSBundle\Entity\Story:
       exclusion_policy: ALL
       properties:
           id: { expose: true }
           title: { expose: true }
           content: { expose: true }
   

3. Frontend Integration Use MopaBootstrapBundle for UI components:

   {% block stylesheets %}
       {{ parent() }}
       {{ mopa_bootstrap_stylesheets() }}
   {% endblock %}
   

Integration Tips

• Doctrine Fixtures: Use DoctrineFixturesBundle for seed data:

  php app/console doctrine:fixtures:load --append
  

• Event Listeners: Extend EETYSBundle events (e.g., story.pre_publish).
• Custom Validation: Add constraints via Symfony Validator:

  use Symfony\Component\Validator\Constraints as Assert;
  
  class Story {
      /**
       * @Assert\Length(min=10)
       */
      private $content;
  }
  

Gotchas and Tips

Pitfalls

1. Bundle State

   • Issue: Bundle is marked as "do not use" in development.
   • Fix: Fork and stabilize before production use. Monitor for updates.

2. Missing Docs

   • Issue: No clear API docs or event reference.
   • Fix: Inspect TB\TYSBundle\Resources/config/routing.yml and EETYSBundle/Event/ for clues.

3. FOSRest Conflicts

   • Issue: param_fetcher_listener: force may break nested routes.
   • Fix: Test with GET/POST separately or adjust to true.

Debugging

• Enable Profiler: Add to config_dev.yml:

  web_profiler: { toolbar: true, intercept_redirects: false }
  

• Check Serialization: Validate DTOs with:

  php app/console debug:serializer
  

Extension Points

1. Custom Story Fields Extend TB\TYSBundle\Entity\Story and update serializer mappings.

2. API Versioning Use FOSRest’s format parameter for versioning:

   # routing.yml
   story_create:
       path: /api/v1/stories
       defaults: { _format: json }
   

3. Bootstrap Themes Override MopaBootstrap templates in app/Resources/MopaBootstrapBundle/views/.