Book Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the repository to composer.json under "repositories":

   "repositories": {
       "bibsdb/book-bundle": {
           "type": "vcs",
           "url": "https://github.com/bibsdb/book-bundle"
       }
   }
   

   Require the bundle:

   composer require bibsdb/book-bundle
   

2. Enable the Bundle Register Bibsdb\BookBundle\BibsdbBookBundle in config/bundles.php (Laravel) or AppKernel.php (Symfony):

   // Laravel (config/bundles.php)
   return [
       Bibsdb\BookBundle\BibsdbBookBundle::class => true,
   ];
   

3. Load Templates Run the command to load the slide template:

   php artisan bibsdb:core:templates:load
   

4. Enable in Admin Activate the template via the administration panel (UI-specific; check the bundle’s docs for exact steps).

First Use Case: Uploading a Book Slide

1. Create a Slide Entity Use the bundle’s form or API to upload a book’s frontpage (image) and add a short description. Example (if using a form):

   // Example controller logic (adjust based on bundle's actual API)
   $slide = new \Bibsdb\BookBundle\Entity\Slide();
   $slide->setImage($request->file('frontpage')->getRealPath());
   $slide->setDescription($request->input('description'));
   $slide->setTemplate('book_slide'); // Default template name
   $slideManager = $this->get('bibsdb.book.slide_manager');
   $slideManager->save($slide);
   

2. Display the Slide Render the slide in a Twig template:

   {% include 'BibsdbBookBundle:Slide:display.html.twig' with {
       'slide': slide,
       'showControls': false
   } %}
   

Implementation Patterns

Workflow: Managing Book Slides

1. Upload & Process

   • Use the SlideManager service to handle uploads, validation, and storage.
   • Example:

     $manager = $this->container->get('bibsdb.book.slide_manager');
     $slide = $manager->createFromRequest($request);
     $manager->persist($slide);
     

2. Template Customization

   • Override the default template by copying templates/Slide/ from the bundle to your theme’s directory.
   • Extend the base template (display.html.twig) to add/modify fields.

3. API Integration

   • Fetch slides via a custom API endpoint:

     // Example route (routes/web.php)
     Route::get('/slides/{id}', 'SlideController@show')->name('slides.show');
     
     // Controller
     public function show($id) {
         $slide = $this->get('bibsdb.book.slide_repository')->find($id);
         return response()->json($slide);
     }
     

4. Admin Panel Integration

   • Use the bundle’s admin configuration to expose slide management in your backend.
   • Example (Symfony):

     # config/packages/bibsdb_book.yaml
     bibsdb_book:
         admin:
             enabled: true
             route: admin.slides
     

Integration Tips

• File Storage: Configure the bundle to use your preferred storage (e.g., S3) by binding the slide_storage service:

  $this->app->bind('bibsdb.book.slide_storage', function () {
      return new \Bibsdb\BookBundle\Storage\S3Storage();
  });
  

• Validation: Extend the Slide entity’s validation rules by overriding the validate() method or using Symfony’s validator constraints.
• Events: Listen for slide events (e.g., SlideCreatedEvent) to trigger actions like notifications:

  $dispatcher->addListener(
      'bibsdb.book.slide.created',
      function ($event) {
          // Send email, log, etc.
      }
  );
  

Gotchas and Tips

Pitfalls

1. Template Loading

   • Forgetting to run bibsdb:core:templates:load will result in missing templates. Run this command after every bundle update.
   • Fix: Add it to a post-update hook or CI pipeline.

2. Book.com API Dependencies

   • The bundle relies on book.com for shared video content. Without a PLUS account, ads/video controls cannot be disabled.
   • Workaround: Mock the API responses in tests or use a local proxy.

3. File Size Limits

   • The bundle may not handle large frontpage images by default. Configure Symfony’s max_file_size in php.ini or use a CDN.
   • Tip: Add validation in the Slide entity:

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\File(maxSize="2048k")
      */
     private $image;
     

4. Admin Panel Conflicts

   • If using another admin bundle (e.g., EasyAdmin), the bibsdb_book.admin.route may conflict.
   • Fix: Rename the route or disable the bundle’s admin features:

     bibsdb_book:
         admin:
             enabled: false
     

Debugging

1. Template Not Loading

   • Check if the template files exist in vendor/bibsdb/book-bundle/Resources/views/Slide/.
   • Clear the cache:

     php artisan cache:clear
     php artisan config:clear
     

2. Slide Not Saving

   • Verify the SlideManager is autowired correctly. Debug with:

     dump($this->container->has('bibsdb.book.slide_manager')); // Should return true
     

   • Check for validation errors:

     $errors = $validator->validate($slide);
     dump($errors);
     

3. Book.com API Errors

   • Mock the API in tests or use a local development proxy (e.g., MailHog for similar tools).
   • Example test mock:

     $this->partialMock(\Bibsdb\BookBundle\Service\BookApiClient::class, ['fetchVideoConfig'])
          ->shouldReceive('fetchVideoConfig')
          ->andReturn(['ad_free' => true]);
     

Extension Points

1. Custom Slide Types

   • Extend the Slide entity to support additional fields (e.g., isbn, author):

     class CustomSlide extends Slide {
         private $isbn;
     
         public function getIsbn() { return $this->isbn; }
         public function setIsbn($isbn) { $this->isbn = $isbn; }
     }
     

   • Register the new type in the bundle’s configuration.

2. Storage Backends

   • Implement a custom storage adapter by extending AbstractStorage:

     class LocalStorage extends AbstractStorage {
         public function save($filePath, $content) {
             // Custom logic (e.g., save to local directory)
         }
     }
     

   • Bind it in services:

     $this->app->bind('bibsdb.book.slide_storage', LocalStorage::class);
     

3. Event Listeners

   • Dispatch custom events for slides (e.g., SlideDownloaded):

     $dispatcher->dispatch(new SlideDownloadedEvent($slide));
     

   • Listen globally in EventSubscriber:

     class SlideSubscriber implements EventSubscriber {
         public static function getSubscribedEvents() {
             return [
                 'bibsdb.book.slide.downloaded' => 'onSlideDownloaded',
             ];
         }
     }
     

Configuration Quirks

1. Default Template Name

   • The bundle uses 'book_slide' as the default template. Override it globally:

     bibsdb_book:
         default_template: 'custom_book_template'
     

2. File Naming

   • The bundle may rename uploaded files. Disable this by configuring the SlideManager:

     $manager->setRenameFiles(false);
     

3. CORS for API

   • If using the bundle’s API endpoints, ensure CORS is configured in .env:

     APP_URL=http://yourdomain.com
     CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE