Band Accounting Bundle Laravel Package

Getting Started

Minimal Setup for First Use

1. Install the Bundle

   composer require arnaugm/band-accounting-bundle
   

2. Enable Bundles Add to AppKernel.php:

   new ArnauGM\BandAccountingBundle\ArnauGMBandAccountingBundle(),
   new Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle(),
   

3. Configure Locale & Doctrine Extensions

   # app/config/config.yml
   stof_doctrine_extensions:
       default_locale: en_US  # Adjust to your locale
       orm:
           default:
               timestampable: true
   

4. Load Routes

   # app/config/routing.yml
   band_accounting:
       resource: "@ArnauGMBandAccountingBundle/Resources/config/routing.yml"
       prefix: /admin/accounting
   

5. Install Assets

   php app/console assets:install --symlink
   

6. First Use Case: Create a Band Use the provided CRUD interface at /admin/accounting/band to register a band. The bundle likely includes:

   • Band entity management (name, members, etc.).
   • Basic accounting entries (income/expenses) tied to bands.

Implementation Patterns

Core Workflows

1. Band Management

   • Use the /admin/accounting/band route to create/update bands.
   • Extend the Band entity (e.g., src/ArnauGM/BandAccountingBundle/Entity/Band.php) to add custom fields (e.g., taxId, genre).

2. Accounting Entries

   • Create entries via /admin/accounting/entry with:
     • Type: Income/Expense.
     • Amount, Date, Description.
     • Band Association: Link entries to a band.
   • Example:

     $entry = new Entry();
     $entry->setBand($band);
     $entry->setType(Entry::TYPE_EXPENSE);
     $entry->setAmount(150.00);
     $entry->setDate(new \DateTime());
     $entry->setDescription("Guitar strings");
     $em->persist($entry);
     $em->flush();
     

3. Reports

   • Generate reports (e.g., monthly income/expenses) using the bundle’s query builder or extend with custom Doctrine queries.
   • Example query:

     $qb = $em->createQueryBuilder();
     $qb->select('e')
        ->from('ArnauGMBandAccountingBundle:Entry', 'e')
        ->where('e.band = :band')
        ->andWhere('e.date BETWEEN :start AND :end')
        ->setParameter('band', $band)
        ->setParameter('start', $startDate)
        ->setParameter('end', $endDate);
     

4. Forms

   • Extend the bundle’s forms (e.g., EntryType) to add fields:

     // src/ArnauGM/BandAccountingBundle/Form/EntryType.php
     $builder->add('category', EntityType::class, [
         'class' => Category::class,
         'placeholder' => 'Select category',
     ]);
     

5. Frontend Integration

   • Use the Grunt-based client assets for admin UI. Customize SCSS/JS in client/:

     cd client
     npm install
     grunt watch  # Auto-reload during development
     

Integration Tips

• Doctrine Events: Listen for prePersist/preUpdate on Entry to auto-calculate totals or validate amounts.

  $em->getEventManager()->addEventListener(
      Entry::class,
      new EntryLifecycleListener()
  );
  

• Symfony Security: Restrict routes to ROLE_ADMIN in security.yml:

  access_control:
      - { path: ^/admin/accounting, roles: ROLE_ADMIN }
  

• API Layer: Expose entries via a custom API controller:

  // src/AppBundle/Controller/Api/EntryController.php
  class EntryController extends Controller {
      public function getBandEntries(Band $band) {
          return $this->json($this->getDoctrine()->getRepository(Entry::class)->findBy(['band' => $band]));
      }
  }
  

Gotchas and Tips

Pitfalls

1. Symfony 2.7 Dependency

   • The bundle targets Symfony 2.7. Avoid using newer Symfony features (e.g., make:controller).
   • Fix: Use php app/console generate:controller for legacy compatibility.

2. Locale Configuration

   • The bundle relies on stof_doctrine_extensions for timestampable entities. Ensure default_locale matches your app’s locale (e.g., en_US).
   • Debug: Check STOF_DOCTRINE_EXTENSIONS_DEFAULT_LOCALE in app/config/parameters.yml if timestamps fail.

3. Asset Pipeline

   • Frontend assets require grunt and npm. If missing:

     npm install -g grunt-cli
     cd client && npm install && grunt
     

   • Tip: Use grunt watch in development to auto-compile SCSS/JS.

4. Database Schema

   • The bundle assumes standard Doctrine mappings. Custom fields may require:

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

   • Warning: Back up your database before running migrations.

5. Routing Conflicts

   • The /admin/accounting prefix may clash with existing routes. Use _controller in routing.yml to override:

     band_accounting_entry:
         path: /accounting/entries
         defaults: { _controller: ArnauGMBandAccountingBundle:Entry:list }
     

Debugging Tips

• Doctrine Queries: Enable SQL logging in config.yml:

  doctrine:
      dbal:
          logging: true
  

• Form Errors: Validate forms with:

  $form->handleRequest($request);
  if ($form->isSubmitted() && !$form->isValid()) {
      dump($form->getErrors(true)); // Debug form errors
  }
  

• Bundle Isolation: Test changes in a dummy app (as per README) to avoid conflicts with your main project.

Extension Points

1. Custom Entities

   • Extend Band or Entry in your app’s Entity/ folder and update orm.xml:

     <entity name="AppBundle\Entity\ExtendedBand" extends="ArnauGM\BandAccountingBundle\Entity\Band">
         <field name="taxId" type="string" length="20" />
     </entity>
     

2. Event Listeners

   • Add listeners for Entry events (e.g., prePersist to auto-calculate totals):

     // src/AppBundle/EventListener/EntryListener.php
     class EntryListener {
         public function prePersist(Entry $entry) {
             if ($entry->getType() === Entry::TYPE_EXPENSE) {
                 $entry->setIsTaxDeductible(true);
             }
         }
     }
     

     Register in services.yml:

     services:
         app.entry_listener:
             class: AppBundle\EventListener\EntryListener
             tags:
                 - { name: doctrine.event_listener, event: prePersist, entity: ArnauGMBandAccountingBundle\Entity\Entry }
     

3. Custom Reports

   • Create a custom query builder or use the bundle’s base repository:

     // src/AppBundle/Repository/CustomEntryRepository.php
     class CustomEntryRepository extends ServiceEntityRepository {
         public function findByBandAndCategory(Band $band, $category) {
             return $this->createQueryBuilder('e')
                 ->where('e.band = :band')
                 ->andWhere('e.category = :category')
                 ->setParameter('band', $band)
                 ->setParameter('category', $category)
                 ->getQuery()
                 ->getResult();
         }
     }
     

4. API Integration

   • Use FOSRestBundle to expose entries as JSON:

     # config/routing.yml
     app_entry_api:
         path: /api/entries/{id}
         defaults: { _controller: 'FOSRestBundle:Default:getItem' }
         requirements:
             id: \d+